- ---
- title: TwinColSelect
- order: 20
- layout: page
- ---
-
- [[components.twincolselect]]
- = TwinColSelect
-
- ifdef::web[]
- [.sampler]
- image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/multiple-value/list-builder"]
- endif::web[]
-
- The [classname]#TwinColSelect# field provides a multiple selection component
- that shows two lists side by side, with the left column containing unselected
- items and the right column the selected items. The user can select items from
- the list on the left and click on the ">" button to move them to the list on
- the right. Items can be deselected by selecting them in the right list and
- clicking on the "<" button.
-
- [[figure.components.twincolselect.basic]]
- .Twin Column Selection
- image::img/twincolselect-basic.png[width=50%, scaledwidth=80%]
-
- [classname]#TwinColSelect# is always in multi-select mode, so its selection
- is always a collection of the selected items in the right column.
-
- The selection columns can have their own captions, separate from the overall
- component caption, which is managed by the containing layout. You can set the
- column captions with [methodname]#setLeftColumnCaption()# and
- [methodname]#setRightColumnCaption()#.
-
-
- [source, java]
- ----
- TwinColSelect<String> select =
- new TwinColSelect<>("Select Targets");
-
- // Put some items in the select
- select.setItems("Mercury", "Venus", "Earth", "Mars",
- "Jupiter", "Saturn", "Uranus", "Neptune");
-
- // Few items, so we can set rows to match item count
- select.setRows(select.size());
-
- // Preselect a few items
- select.select("Venus", "Earth", "Mars");
-
- // Handle value changes
- select.addSelectionListener(event ->
- layout.addComponent(
- new Label("Selected: " + event.getNewSelection())));
- ----
-
- The resulting component is shown in <<figure.components.twincolselect.basic>>.
-
- The [methodname]#setRows()# method sets the height of the component by the
- number of visible items in the selection boxes. Setting the height with
- [methodname]#setHeight()# to a defined value overrides the rows setting.
-
- [WARNING]
- The [classname]#TwinColSelect# does not provide lazy loading mechanism.
- Hence it will slow down significantly if used with large itemsets.
- The lazy loading feature could be implemented using two single column Grids instead.
-
- Common selection component features are described in
- <<components-selection#components.selection,"Selection
- Components">>.
-
- == CSS Style Rules
-
-
- [source, css]
- ----
- .v-select-twincol {}
- .v-select-twincol-options-caption {}
- .v-select-twincol-selections-caption {}
- .v-select-twincol-options {}
- .v-select-twincol-buttons {}
- .v-button {}
- .v-button-wrap {}
- .v-button-caption {}
- .v-select-twincol-deco {}
- .v-select-twincol-selections {}
- ----
-
- The [classname]#TwinColSelect# component has an overall
- [literal]#++v-select-twincol++# style. If set, the left and right column
- captions have [literal]#++v-select-twincol-options-caption++# and
- [literal]#++v-select-twincol-options-caption++# style names, respectively. The
- left box, which displays the unselected items, has
- [literal]#++v-select-twincol-options-caption++# style and the right box, which
- displays the selected items, has
- [literal]#++v-select-twincol-options-selections++# style. Between them is the
- button area, which has overall [literal]#++v-select-twincol-buttons++# style;
- the actual buttons reuse the styles for the [classname]#Button# component.
- Between the buttons is a divider element with
- [literal]#++v-select-twincol-deco++# style.
|