include::components-nativeselect.asciidoc[leveloffset=+2]
-include::components-optiongroup.asciidoc[leveloffset=+2]
+include::components-optiongroups.asciidoc[leveloffset=+2]
include::components-twincolselect.asciidoc[leveloffset=+2]
checked or unchecked. The caption of the check box will be placed right of the
actual check box. Vaadin provides two ways to create check boxes: individual
check boxes with the [classname]#CheckBox# component described in this section
-and check box groups with the [classname]#OptionGroup# component in multiple
-selection mode, as described in
-<<dummy/../../../framework/components/components-optiongroup#components.optiongroup,"OptionGroup">>.
+and check box groups with the [classname]#CheckBoxGroup# component, as described in
+<<dummy/../../../framework/components/components-optiongroups#components.optiongroups,"CheckBoxGroup and RadioButtonGroup">>.
Clicking on a check box will change its state. The state is a [classname]#Boolean#
property that you can set with the [methodname]#setValue()# method and obtain with
+++ /dev/null
----
-title: OptionGroup
-order: 19
-layout: page
----
-
-[[components.optiongroup]]
-= [classname]#OptionGroup#
-
-ifdef::web[]
-[.sampler]
-image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/multiple-value/option-group"]
-endif::web[]
-
-[classname]#OptionGroup# is a selection component that allows selection from a
-group of radio buttons in single selection mode. In multiple selection mode, the
-items show up as check boxes. The common selection component features are
-described in
-<<dummy/../../../framework/components/components-selection#components.selection,"Selection Components">>.
-
-[[figure.components.optiongroup]]
-.Option Button Group in Single and Multiple Selection Mode
-image::img/optiongroup-basic.png[width=45%, scaledwidth=70%]
-
-Option group is by default in single selection mode. Multiple selection is
-enabled with [methodname]#setMultiSelect()#.
-
-
-[source, java]
-----
-// A single-select radio button group
-OptionGroup<String> single =
- new OptionGroup<>("Single Selection");
-single.setItems("Single", "Sola", "Yksi");
-
-// A multi-select check box group
-OptionGroup<String> multi =
- new OptionGroup<>("Multiple Selection");
-multi.setMultiSelect(true);
-multi.setItems("Many", "Muchos", "Monta");
-----
-
-<<figure.components.optiongroup>> shows the [classname]#OptionGroup# in both
-single and multiple selection mode.
-
-You can also create check boxes individually using the [classname]#CheckBox#
-class, as described in
-<<dummy/../../../framework/components/components-checkbox#components.checkbox,"CheckBox">>.
-The advantages of the [classname]#OptionGroup# component are that as it
-maintains the individual check box objects, you can get an array of the
-currently selected items easily, and that you can easily change the appearance
-of a single component.
-
-ifdef::web[]
-[[components.optiongroup.disabling]]
-== Disabling Items
-
-You can disable individual items in an [classname]#OptionGroup# with
-[methodname]#setItemEnabled()#. The user can not select or deselect disabled
-items in multi-select mode, but in single-select mode the use can change the
-selection from a disabled to an enabled item. The selections can be changed
-programmatically regardless of whether an item is enabled or disabled. You can
-find out whether an item is enabled with [methodname]#isItemEnabled()#.
-
-[source, java]
-----
-// Have an option group with some items
-OptionGroup<String> group = new OptionGroup<>("My Disabled Group");
-group.setItems("One", "Two", "Three");
-
-// Disable one item
-group.setItemEnabled("Two", false);
-----
-
-[[figure.components.optiongroup.disabling]]
-.[classname]#OptionGroup# with a Disabled Item
-image::img/optiongroup-disabling.png[width=25%, scaledwidth=50%]
-
-Setting an item as disabled turns on the [literal]#++v-disabled++# style for it.
-endif::web[]
-
-[[components.optiongroup.css]]
-== CSS Style Rules
-
-
-[source, css]
-----
-.v-select-optiongroup {}
- .v-select-option.v-checkbox {}
- .v-select-option.v-radiobutton {}
-----
-
-The [literal]#++v-select-optiongroup++# is the overall style for the component.
-Each check box will have the [literal]#++v-checkbox++# style, borrowed from the
-[classname]#CheckBox# component, and each radio button the
-[literal]#++v-radiobutton++# style. Both the radio buttons and check boxes will
-also have the [literal]#++v-select-option++# style that allows styling
-regardless of the option type. Disabled items have additionally the
-[literal]#++v-disabled++# style.
-
-ifdef::web[]
-
-[[components.optiongroup.css.horizontal]]
-=== Horizontal Layout
-
-The options are normally laid out vertically. You can use horizontal layout by
-setting [literal]#++display: inline-block++# for the options. The
-[literal]#++nowrap++# setting for the overall element prevents wrapping if there
-is not enough horizontal space in the layout, or if the horizontal width is
-undefined.
-
-
-[source, css]
-----
-/* Lay the options horizontally */
-.v-select-optiongroup-horizontal .v-select-option {
- display: inline-block;
-}
-
-/* Avoid wrapping if the layout is too tight */
-.v-select-optiongroup-horizontal {
- white-space: nowrap;
-}
-
-/* Some extra spacing is needed */
-.v-select-optiongroup-horizontal
- .v-select-option.v-radiobutton {
- padding-right: 10px;
-}
-----
-
-Use of the above rules requires setting a custom [literal]#++horizontal++# style
-name for the component. The result is shown in
-<<figure.components.optiongroup.horizontal>>.
-
-[[figure.components.optiongroup.horizontal]]
-.Horizontal [classname]#OptionGroup#
-image::img/optiongroup-horizontal.png[width=35%, scaledwidth=50%]
-
-endif::web[]
--- /dev/null
+---
+title: CheckBoxGroup and RadioButtonGroup
+order: 19
+layout: page
+---
+
+[[components.optiongroups]]
+= [classname]#CheckBoxGroup# and [classname]#RadioButtonGroup#
+
+ifdef::web[]
+[.sampler]
+image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/multiple-value/option-group"]
+endif::web[]
+
+[classname]#RadioButtonGroup# is a single selection component that allows
+selection from a group of radio buttons. [classname]#CheckBoxGroup# is a multi selection
+component where items displayed as check boxes. The common selection component features are
+described in
+<<dummy/../../../framework/components/components-selection#components.selection,"Selection Components">>.
+
+[[figure.components.optiongroups]]
+.RadioButtonGroup and CheckBoxGroup
+image::img/optiongroup-basic.png[width=45%, scaledwidth=70%]
+
+[source, java]
+----
+// A single-select radio button group
+RadioButtonGroup<String> single =
+ new RadioButtonGroup<>("Single Selection");
+single.setItems("Single", "Sola", "Yksi");
+
+// A multi-select check box group
+CheckBoxGroup<String> multi =
+ new CheckBoxGroup<>("Multiple Selection");
+multi.setItems("Many", "Muchos", "Monta");
+----
+
+<<figure.components.optiongroups>> shows the [classname]#RadioButtonGroup# and
+[classname]#CheckBoxGroup#.
+
+You can also create check boxes individually using the [classname]#CheckBox#
+class, as described in
+<<dummy/../../../framework/components/components-checkbox#components.checkbox,"CheckBox">>.
+The advantages of the [classname]#CheckBoxGroup# component are that as it
+maintains the individual check box objects, you can get an array of the
+currently selected items easily, and that you can easily change the appearance
+of a single component and use it with a [classname]#Binder#.
+
+ifdef::web[]
+
+[[components.optiongroups.disabling]]
+== Disabling Items
+
+You can disable individual items in a [classname]#RadioButtonGroup# or a [classname]#CheckBoxGroup# with
+[methodname]#setItemEnabledProvider()#. The user can not select or deselect disabled
+items in a [classname]#CheckBoxGroup#, but in a [classname]#RadioButtonGroup# the user can change the
+selection from a disabled to an enabled item. The selections can be changed
+programmatically regardless of whether an item is enabled or disabled.
+
+[source, java]
+----
+// Have a radio button group with some items
+RadioButtonGroup<String> group = new RadioButtonGroup<>("My Disabled Group");
+group.setItems("One", "Two", "Three");
+
+// Disable one item
+group.setItemEnabledProvider( item-> !"Two".equals(item));
+----
+
+[[figure.components.optiongroups.disabling]]
+.[classname]#RadioButtonGroup# with a Disabled Item
+image::img/optiongroup-disabling.png[width=25%, scaledwidth=50%]
+
+Setting an item as disabled turns on the [literal]#++v-disabled++# style for it.
+endif::web[]
+
+[[components.optiongroups.css]]
+== CSS Style Rules
+
+
+[source, css]
+----
+.v-select-optiongroup {}
+ .v-select-option.v-checkbox {}
+ .v-select-option.v-radiobutton {}
+----
+
+The [literal]#++v-select-optiongroup++# is the overall style for the component.
+Each check box will have the [literal]#++v-checkbox++# style, borrowed from the
+[classname]#CheckBox# component, and each radio button the
+[literal]#++v-radiobutton++# style. Both the radio buttons and check boxes will
+also have the [literal]#++v-select-option++# style that allows styling
+regardless of the option type. Disabled items have additionally the
+[literal]#++v-disabled++# style.
+
+ifdef::web[]
+
+[[components.optiongroups.css.horizontal]]
+=== Horizontal Layout
+
+The options are normally laid out vertically. You can use horizontal layout by
+setting [literal]#++display: inline-block++# for the options. The
+[literal]#++nowrap++# setting for the overall element prevents wrapping if there
+is not enough horizontal space in the layout, or if the horizontal width is
+undefined.
+
+
+[source, css]
+----
+/* Lay the options horizontally */
+.v-select-optiongroup-horizontal .v-select-option {
+ display: inline-block;
+}
+
+/* Avoid wrapping if the layout is too tight */
+.v-select-optiongroup-horizontal {
+ white-space: nowrap;
+}
+
+/* Some extra spacing is needed */
+.v-select-optiongroup-horizontal
+ .v-select-option.v-radiobutton {
+ padding-right: 10px;
+}
+----
+
+Use of the above rules requires setting a custom [literal]#++horizontal++# style
+name for the component. The result is shown in
+<<figure.components.optiongroups.horizontal>>.
+
+[[figure.components.optiongroups.horizontal]]
+.Horizontal [classname]#RadioButtonGroup#
+image::img/optiongroup-horizontal.png[width=35%, scaledwidth=50%]
+
+endif::web[]
Provides selection using the native selection component of the browser, typically a drop-down list for single selection and a multi-line list in multiselect mode.
This uses the [literal]#++<select>++# element in HTML.
-[classname]#OptionGroup# (<<components-optiongroup#components.optiongroup,"OptionGroup">>)::
-Shows the items as a vertically arranged group of radio buttons in the single selection mode and of check boxes in multiple selection mode.
+[classname]#RadioButtonGroup# (<<components-optiongroups#components.optiongroups,"CheckBoxGroup and RadioButtonGroup">>)::
+Shows the items as a vertically arranged group of radio buttons in single selection mode.
+
+[classname]#CheckBoxGroup# (<<components-optiongroups#components.optiongroups,"CheckBoxGroup and RadioButtonGroup">>)::
+Shows the items as a vertically arranged group of check boxes in multiple selection mode.
[classname]#TwinColSelect# (<<components-twincolselect#components.twincolselect, "TwinColSelect">>)::
Shows two list boxes side by side where the user can select items from a list of available items and move them to a list of selected items using control buttons.
[[components.selection.multiple]]
== Multiple Selection
-Some selection components, such as [classname]#OptionGroup# and
-[classname]#ListSelect# support a multiple selection mode, which you can enable
-with [methodname]#setSelectionMode(SelectionMode.MULTI)#.
-For [classname]#TwinColSelect#, which is especially intended for
-multiple selection, it is enabled by default.
-
+Some selection components, such as [classname]#CheckBoxGroup#,
+[classname]#ListSelect# and [classname]#TwinColSelect# are multiselect components,
+they extend [classname]#AbstractMultiSelect# class.
-[source, java]
-----
-myselect.setSelectionMode(SelectionMode.MULTI);
-----
-In multiple selection mode the [interfacename]#Select# value is a
-[classname]#Collection# of the items of the currently selected items.
-You can get and set the selection with the [methodname]#getSelected()# and
-[methodname]#setSelected()# methods as usual.
+Multiselect components use the [interfacename]#SelectionModel.Multi# selection model.
+This model allows to select multiple items.
+You can get and set the selection with the [methodname]#SelectionModel.getSelectedItems()# and
+[methodname]#SelectionModel.Multi.selectItems()# methods.
A change in the selection will trigger a [classname]#SelectionChange#, which
you can handle with a [classname]#SelectionChangeListener#. The
select.setItems("Mercury", "Venus", "Earth",
"Mars", "Jupiter", "Saturn", "Uranus", "Neptune");
-// Multiple selection mode
-select.setSelectionMode(SelectionMode.MULTI);
-
// Feedback on value changes
-select.addSelectionChangeListener(event -> {
+select.addSelectionListener(event -> {
// Some feedback
layout.addComponent(new Label("Selected: " +
- event.getSelected()));
+ event.getNewSelection()));
}
});
** Code example: Setting, getting and reacting to events from a NativeSelect
** Design question: Is nullSelectionAllowed a feature of each component or a feature of the selection model?
* Other listings can be configured to allow selecting one or many items. Depending on how it is configured, it uses a different selection model type for working with the selection.
-** Code example: OptionGroup in single / multi mode. Using different selection model types to access the selection.
+** Code example: CheckBoxGroup/RadioButtonGroup. Using different selection model types to access the selection.
** Code example: Using each selection model type with a Binder
////
/***************************************************************************
*
- * OptionGroup styles
+ * RadioButtonGroup/CheckBoxGroup styles
*
**************************************************************************/
/**
- * Small size option group. Can be combined with any other OptionGroup
- * style.
+ * Small size option group. Can be combined with any other
+ * RadioButtonGroup/CheckBoxGroup style.
*/
public static final String OPTIONGROUP_SMALL = "small";
/**
- * Large size option group. Can be combined with any other OptionGroup
- * style.
+ * Large size option group. Can be combined with any other
+ * RadioButtonGroup/CheckBoxGroup style.
*/
public static final String OPTIONGROUP_LARGE = "large";
projects / vaadin-framework.git / commitdiff