Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 115 insertions, 0 deletions

diff --git a/documentation/components/components-combobox.asciidoc b/documentation/components/components-combobox.asciidoc
new file mode 100644
index 0000000000..189933ee5e
--- /dev/null
+++ b/documentation/components/components-combobox.asciidoc
@@ -0,0 +1,115 @@
+---
+title: ComboBox
+order: 16
+layout: page
+---
+
+[[components.combobox]]
+= [classname]#ComboBox#
+
+[classname]#ComboBox# is a selection component allows selecting an item from a
+drop-down list. The component also has a text field area, which allows entering
+search text by which the items shown in the drop-down list are filtered. Common
+selection component features are described in
+<<dummy/../../../framework/components/components-selection#components.selection,"Selection
+Components">>.
+
+.The [classname]#ComboBox# Component
+image::img/combobox-basic.png[]
+
+[classname]#ComboBox# supports adding new items when the user presses
+Enter
+ifdef::web[]
+, as described in
+<<dummy/../../../framework/components/components-selection#components.selection.newitems,"Allowing
+Adding New
+Items">>.
+endif::web[]
+
+[[components.combobox.filtering]]
+== Filtered Selection
+
+[classname]#ComboBox# allows filtering the items available for selection in the
+drop-down list by the text entered in the input box.
+
+[[figure.components.combobox.filter]]
+.Filtered Selection in [classname]#ComboBox#
+image::img/combobox-filtering.png[]
+
+Pressing Enter will complete the item in the input box. Pressing Up- and
+Down-arrows can be used for selecting an item from the drop-down list. The
+drop-down list is paged and clicking on the scroll buttons will change to the
+next or previous page. The list selection can also be done with the arrow keys
+on the keyboard. The shown items are loaded from the server as needed, so the
+number of items held in the component can be quite large. The number of matching
+items is displayed by the drop-down list.
+
+Filtering is enabled by setting a __filtering mode__ with
+[methodname]#setFilteringMode()#.
+
+
+[source, java]
+----
+cb.setFilteringMode(FilteringMode.CONTAINS);
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#component.select.combobox.filtering[on-line example, window="_blank"].
+
+The modes defined in the [classname]#FilteringMode# enum are as follows:
+
+[parameter]#CONTAINS#:: Matches any item that contains the string given in the text field part of the
+component.
+
+[parameter]#STARTSWITH#:: Matches only items that begin with the given string.
+
+[parameter]#OFF#(default):: Filtering is by default off and all items are shown all the time.
+
+
+
+The above example uses the containment filter that matches to all items
+containing the input string. As shown in <<figure.components.combobox.filter>>
+below, when we type some text in the input area, the drop-down list will show
+all the matching items.
+
+
+[[components.combobox.css]]
+== CSS Style Rules
+
+
+[source, css]
+----
+.v-filterselect { }
+  .v-filterselect-input { }
+  .v-filterselect-button { }
+
+// Under v-overlay-container
+.v-filterselect-suggestpopup { }
+  .popupContent { }
+    .v-filterselect-prevpage,
+      .v-filterselect-prevpage-off { }
+    .v-filterselect-suggestmenu { }
+      .gwt-MenuItem { }
+    .v-filterselect-nextpage,
+      .v-filterselect-nextpage-off { }
+    .v-filterselect-status { }
+----
+
+In its default state, only the input field of the [classname]#ComboBox#
+component is visible. The entire component is enclosed in
+[literal]#++v-filterselect++# style (a legacy remnant), the input field has
+[literal]#++v-filterselect-input++# style and the button in the right end that
+opens and closes the drop-down result list has
+[literal]#++v-filterselect-button++# style.
+
+The drop-down result list has an overall
+[literal]#++v-filterselect-suggestpopup++# style. It contains the list of
+suggestions with [literal]#++v-filterselect-suggestmenu++# style. When there are
+more items that fit in the menu, navigation buttons with
+[literal]#++v-filterselect-prevpage++# and
+[literal]#++v-filterselect-nextpage++# styles are shown. When they are not
+shown, the elements have [literal]#++-off++# suffix. The status bar in the
+bottom that shows the paging status has [literal]#++v-filterselect-status++#
+style.
+
+
+
+