Update documentation (+javadoc) references to obsolete OptionGroup #237.

Change-Id: Ie90e91f61a5795c90de3c690c3b6af80ec1448d9

1 files changed, 135 insertions, 0 deletions

diff --git a/documentation/components/components-optiongroups.asciidoc b/documentation/components/components-optiongroups.asciidoc
new file mode 100644
index 0000000000..e6f6394fcd
--- /dev/null
+++ b/documentation/components/components-optiongroups.asciidoc
@@ -0,0 +1,135 @@
+---
+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[]