From 99d6de546c74f0eed230ea8253dda6b85109d2e7 Mon Sep 17 00:00:00 2001
From: Markus Koivisto <markus@vaadin.com>
Date: Fri, 22 Jan 2016 14:55:18 +0200
Subject: Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674
---
 .../components/components-combobox.asciidoc        | 112 +++++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 documentation/components/components-combobox.asciidoc

(limited to 'documentation/components/components-combobox.asciidoc')

diff --git a/documentation/components/components-combobox.asciidoc b/documentation/components/components-combobox.asciidoc
new file mode 100644
index 0000000000..f119cfbc40
--- /dev/null
+++ b/documentation/components/components-combobox.asciidoc
@@ -0,0 +1,112 @@
+---
+title: ComboBox
+order: 16
+layout: page
+---
+
+[[components.combobox]]
+= [classname]#ComboBox#
+
+ifdef::web[]
+[.sampler]
+image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/multiple-value/combo-box]
+endif::web[]
+
+[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
+kbd:[Enter].
+ifdef::web[]
+See <<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 kbd:[Enter] will complete the item in the input box. Pressing kbd:[Up] and kbd:[Down] arrow keys 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.
-- 
cgit v1.2.3

