WkValueSet

Widget Encyclopedia : WkValueSet

WkValueSet

The WkValueSet widget provides a means for selecting one item from a set of pictorial choices. It consists of a two-dimensional grid of graphical cells, where only one cell is selected at a time. ValueSets are very popular interface components, used for creating such GUI objects as tool bars, ribbons, paging buttons, and color choosers. Note that valuesets are useful in situations where one item is always selected from a group of choices. For applications where choosing an item will issue a command rather than make a selection, the WkImageButton classes should be used instead.

The user can select a particular item by clicking on it directly with the mouse, or using the arrow keys to move the selection. When an item is selected it notifies the single selection callback.

Each cell may contain a label, an image and/or a color. To set the contents of a cell, the method #cellAt:put: is provided. The object put into a cell can be an renderable object (e.g., an image, a String, or a Color). By default WindowBuilder Pro will use instances of WbLabelledImage which may be composed of an image, a label and specify a background color.

Two methods are provided to retrieve the valueset’s selection: #itemPosition returns the point representing the column and row of the current selection, and #item returns the actual object in the selected cell.

Protocol

drawPolicy: anInteger
Specifies the drawing policy used in rendering buttons on the valueset. The drawing policy determines two things for a button:

how the button draws itself so it looks like a button

how the button animates when pressed

Default: XmSHADOWEDTHREESTATEDRAWPOLICY (Shadowed Three State)

Valid resource values:

XmSHADOWEDTWOSTATEDRAWPOLICY (Shadowed Two State) - Buttons are drawn with a 3D shadowed outline and exhibit a simple 2-state (OFF and ON) state rendering.

XmSHADOWEDTHREESTATEDRAWPOLICY (Shadowed Three State) - Buttons are drawn with a 3D shadowed outline and exhibit a 3-state (OFF, ON, and PRESSED) state rendering.

XmOUTLINEDRAWPOLICY (Outlined) - Buttons are drawn with a simple etched (non-shadowed) outline and exhibit a 2-state (OFF and ON) state rendering.

XmFLATDRAWPOLICY (Flat) - Buttons are drawn flat without a 3D shadow.

numColumns: anInteger
Specifies the number of columns that are made to accommodate the receiver’s buttons. This attribute always sets the x-axis dimension.

numRows: anInteger
Specifies the number of rows that are made to accommodate the receiver's buttons. This attribute always sets the y-axis dimension.

selection: aPoint
Specifies the widget's initial selection.

Callbacks & Events

Default Action Callback
These callbacks are triggered when the widget is double clicked.

Call data arguments:

item - the selected item.

itemPosition - the point position of the selected item in the value set.

Single Selection Callback
These callbacks are triggered when a value set item is clicked.

Call data arguments:

item - the selected item.

itemPosition - the point position of the selected item in the value set.

Editor

Border Width
Specifies the width of the border that surrounds the widget’s window on all four sides. The width is specified in pixels. A width of zero means that no border will show.

Border - Causes the widget to have a border.

No Border - Causes the widget to have no border.

Enabled
Determines whether a widget will react to input events. Disabled (insensitive) widgets do not react to input events.

Draw Policy
Specifies the drawing policy used in rendering buttons on the valueset. The drawing policy determines two things for a button:

1.

how the button draws itself so it looks like a button

2.

how the button animates when pressed

Shadowed Two State - Buttons are drawn with a 3D shadowed outline and exhibit a simple 2-state (OFF and ON) state rendering.

Shadowed Three State - Buttons are drawn with a 3D shadowed outline and exhibit a 3-state (OFF, ON, and PRESSED) state rendering.

Outlined - Buttons are drawn with a simple etched (non-shadowed) outline and exhibit a 2-state (OFF and ON) state rendering.

Flat - Buttons are drawn flat without a 3D shadow.

Num Columns
Specifies the number of columns that are made to accommodate the receiver’s buttons. This attribute always sets the x-axis dimension.

Num Rows
Specifies the number of rows that are made to accommodate the receiver's buttons. This attribute always sets the y-axis dimension.

Selection
Specifies the widget's initial selection.

Visible
Maps the widget (makes visible) as soon as it is both realized and managed, if set to True. If set to False, the client is responsible for mapping and unmapping the widget.

Cell Editor

Background Color
Specifies the background color for the cell.

Foreground Color
Specifies the foreground color for the cell.

Label - Default
Specifies the default label string.

Label - Pressed
Specifies the label string when the widget is pressed.

Label - Disabled
Specifies the label string when the widget is disabled.

Label - Checked
Specifies the label string when the widget is checked.

Image - Default
Specifies the default label image.

Image - Pressed
Specifies the label image when the widget is pressed.

Image - Disabled
Specifies the label image when the widget is disabled.

Image - Checked
Specifies the label image when the widget is checked.

Example

The following example code creates a WkValueSet that has been set up as a two by two grid containing the letters “A” through “D”.

aWkValueSet := WkValueSet

createWidget: 'aWkValueSet'

parent: aCwForm

argBlock: [:w | w

x: 12;

y: 8;

width: 92;

height: 64;

atRow: 1 column: 1 put:

(WbLabeledImage stateDriven

image: nil label: 'A';

yourself);

atRow: 1 column: 2 put:

(WbLabeledImage stateDriven

image: nil label: 'B';

yourself);

atRow: 2 column: 1 put:

(WbLabeledImage stateDriven

image: nil label: 'C';

yourself);

atRow: 2 column: 2 put:

(WbLabeledImage stateDriven

image: nil label: 'D';

yourself);

scale].

The next example code creates a WkValueSet that has been set up as a two by two grid containing colors red, green, blue and yellow

aWkValueSet := WkValueSet

createWidget: 'aWkValueSet'

parent: aCwForm

argBlock: [:w | w

x: 116;

y: 8;

width: 92;

height: 64;

atRow: 1 column: 1 put:

(WbLabeledImage stateDriven

image: nil;

backgroundColor: (CgRGBColor

red: 16rFFFF green: 16r0 blue: 16r0);

yourself);

atRow: 1 column: 1 put:

(WbLabeledImage stateDriven

image: nil;

backgroundColor: (CgRGBColor

red: 16r0 green: 16rFFFF blue: 16r0);

yourself);

atRow: 1 column: 1 put:

(WbLabeledImage stateDriven

image: nil;

backgroundColor: (CgRGBColor

red: 16r0 green: 16r0 blue: 16rFFFF);

yourself);

atRow: 1 column: 1 put:

(WbLabeledImage stateDriven

image: nil;

backgroundColor: (CgRGBColor

red: 16rFFFF

green: 16rFFFF

blue: 16r0);

yourself);

scale].