Файл: book-of-vaadin.pdf

User Interface Components

5.14.3. ListSelect

The ListSelect component is list box that shows the selectable items in a vertical list. If the number of items exceeds the height of the component, a scrollbar is shown.The component allows both single and multiple selection modes, which you can set with setMultiSelect(). It is visually identical in both modes.

// Create the selection component

ListSelect select = new ListSelect("My Selection");

// Add some items select.addItem("Mercury"); select.addItem("Venus"); select.addItem("Earth");

...

select.setNullSelectionAllowed(false);

// Show 5 items and a scrollbar if there are more select.setRows(5);

The number of visible items is set with setRows().

Figure 5.39. The ListSelect Component

CSS Style Rules

.v-select {}

.v-select-select {}

The component has a v-select overall style. The native select element has v-select-select style.

5.14.4. Native Selection Component NativeSelect

NativeSelect offers the native selection component of web browsers, using the HTML <select> element. The component is shown as a drop-down list.

// Create the selection component

final NativeSelect select = new NativeSelect("Native Selection");

//Add some items select.addItem("Mercury"); select.addItem("Venus");

...

//Set the width in "columns" as in TextField select.setColumns(10);

select.setNullSelectionAllowed(false);

User Interface Components

The setColumns() allows setting the width of the list as "columns", which is a measure that depends on the browser.

Figure 5.40. The NativeSelect Component

Multiple selection mode is not allowed; you should use the ListSelect component instead. Also adding new items, which would be enabled with setNewItemsAllowed(), is not allowed.

CSS Style Rules

.v-select {}

.v-select-select {}

The component has a v-select overall style. The native select element has v-select-select style.

5.14.5. Radio Button and Check Box Groups with OptionGroup

The OptionGroup class provides selection from alternatives using a group of radio buttons in single selection mode. In multiple selection mode, the items show up as check boxes.

OptionGroup optiongroup = new OptionGroup("My Option Group");

// Use the multiple selection mode. myselect.setMultiSelect(true);

Figure 5.41, “Option Button Group in Single and Multiple Selection Mode” shows the OptionGroup in both single and multiple selection mode.

Figure 5.41. Option Button Group in Single and Multiple Selection Mode

User Interface Components

You can create check boxes individually using the CheckBox class, as described in Section 5.13, “CheckBox”. The advantages of the 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.

Disabling Items

You can disable individual items in an OptionGroup with 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 isItemEnabled().

The setItemEnabled() identifies the item to be disabled by its item ID.

// Have an option group

OptionGroup group = new OptionGroup("My Disabled Group"); group.addItem("One");

group.addItem("Two");

group.addItem("Three");

// Disable one item group.setItemEnabled("Two", false);

The item IDs are also used for the captions in this example. The result is shown in Figure 5.42, “OptionGroup with a Disabled Item”.

Figure 5.42. OptionGroup with a Disabled Item

Setting an item as disabled turns on the v-disabled style for it.

CSS Style Rules

.v-select-optiongroup {}

.v-select-option.v-checkbox {}

.v-select-option.v-radiobutton {}

The v-select-optiongroup is the overall style for the component. Each check box will have the v-checkbox style, borrowed from the CheckBox component, and each radio button the v-radiobutton style. Both the radio buttons and check boxes will also have the v-select-option style that allows styling regardless of the option type. Disabled items have additionally the v-disabled style.

The options are normally laid out vertically. You can use horizontal layout by setting display: inline-block for the options. The 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.

/* 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 {

User Interface Components

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 horizontal style name for the component. The result is shown in Figure 5.43, “Horizontal OptionGroup”.

Figure 5.43. Horizontal OptionGroup

5.14.6. Twin Column Selection with TwinColSelect

The 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.

TwinColSelect is always in multi-select mode, so its property value is always a collection of the item IDs of the selected items, that is, the 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 setLeftColumnCaption() and setRightColumnCaption().

final TwinColSelect select =

new TwinColSelect("Select Targets to Destroy");

//Set the column captions (optional) select.setLeftColumnCaption("These are left"); select.setRightColumnCaption("These are done for");

//Put some data in the select

String planets[] = {"Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune"};

for (int pl=0; pl<planets.length; pl++) select.addItem(planets[pl]);

// Set the number of visible items select.setRows(planets.length);

The resulting component is shown in Figure 5.44, “Twin Column Selection”.

User Interface Components

Figure 5.44. Twin Column Selection

The setRows() method sets the height of the component by the number of visible items in the selection boxes. Setting the height with setHeight() to a defined value overrides the rows setting.

CSS Style Rules

.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 TwinColSelect component has an overall v-select-twincol style. If set, the left and right column captions have v-select-twincol-options-caption and v-select-twincol-options-caption style names, respectively.The left box, which displays the unselected items, has v-select-twincol-options-caption style and the right box, which displays the selected items, has v-select-twincol-options-selections style. Between them is the button area, which has overall v-select-twincol-buttons style; the actual buttons reuse the styles for the Button component. Between the buttons is a divider element with v-select-twincol-deco style.

5.14.7. Allowing Adding New Items

The selection components allow the user to add new items, with a user interface similar to combo boxes in desktop user interfaces. You need to enable the newItemsAllowed mode with the setNewItemsAllowed() method.

myselect.setNewItemsAllowed(true);

The user interface for adding new items depends on the selection component and the selection mode. The regular Select component in single selection mode, which appears as a combo box, allows you to simply type the new item in the combo box and hit Enter to add it. In most other selection components, as well as in the multiple selection mode of the regular Select component, a text field that allows entering new items is shown below the selection list, and clicking the + button will add the item in the list, as illustrated in Figure 5.45, “Select Component with Adding New Items Allowed”.

User Interface Components

Figure 5.45. Select Component with Adding New Items Allowed

The identifier of an item added by the user will be a String object identical to the caption of the item.You should consider this if the item identifier of automatically filled items is some other type or otherwise not identical to the caption.

Adding new items is possible in both single and multiple selection modes and in all styles. Adding new items may not be possible if the Select is bound to an external Container that does not allow adding new items.

5.14.8. Multiple Selection Mode

Setting the Select, NativeSelect, or OptionGroup components to multiple selection mode with the setMultiSelect() method changes their appearance to allow selecting multiple items.

Select and NativeSelect

These components appear as a native HTML selection list, as shown in Figure 5.45, “Select Component with Adding New Items Allowed”. By holding the Ctrl or Shift key pressed, the user can select multiple items.

OptionGroup

The option group, which is a radio button group in single selection mode, will show as a check box group in multiple selection mode. See Section 5.14.5, “Radio Button and Check Box Groups with OptionGroup”.

The TwinColSelect, described in Section 5.14.6, “Twin Column Selection with TwinColSelect”, is a special multiple selection mode that is not meaningful for single selection.

myselect.setMultiSelect(true);

As in single selection mode, the selected items are set as the property of the Select object. In multiple selection mode, the property is a Collection of currently selected items. You can get and set the property with the getValue() and setValue() methods as usual.

A change in the selection will trigger a ValueChangeEvent, which you can handle with a Propery.ValueChangeListener. As usual, you should use setImmediate(true) to trigger the event immediately when the user changes the selection. The following example shows how to handle selection changes with a listener.

public class SelectExample

extends CustomComponent

implements Property.ValueChangeListener { // Create a Select object with a caption.

Select select = new Select("This is a Select component");