PMGuide - Value Set Controls
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
A value set control (WC_VALUESET window class), like a radio button, is a visual component that enables a user to select one choice from a group of mutually exclusive choices. However, unlike radio buttons, a value set can use graphic images (bit maps or icons), as well as colors, text, and numbers, to represent the items a user can select. This chapter presents the basics about value set controls and tells you how to create and use them in PM applications.
About Value Set Controls
Even though text is supported, the purpose of a value set control is to display choices as graphic images for faster selection. The user can see the selections instead of having to take time to read descriptions of the choices. Using graphic images in a value set also lets you conserve space on the display screen. For example, if you want to let a user choose from a variety of patterns, you can present those patterns as value set choices. If long strings of data are to be displayed as choices, radio buttons should be used. However, for small sets of numeric or textual information, you can use either a value set or radio buttons.
The value set is customizable to meet varying application requirements, while providing a user interface component that can be used easily to develop products that conform to the Common User Access (CUA) user interface guidelines. The application can specify different types of items, sizes, and orientations for its value sets, but the underlying function of the control remains the same. For a complete description of CUA value sets, refer to the SAA CUA Guide to User Interface Design and the SAA CUA Advanced Interface Design Reference.
Value Set Styles
Value set control window styles are set when a value set window is created.
- Set one of the following styles when creating a value set control window. You can override these styles by specifying VIA_BITMAP, VIA_ICON, VIA_TEXT, VIA_RGB, or VIA_COLORINDEX attributes for individual value set items:
* VS_BITMAP: The attribute for each value set item is set to the VIA_BITMAP value set item attribute, which means the value set treats each item as a bit map unless otherwise specified. This is the default. * VS_COLORINDEX: The attribute for each value set item is set to the VIA_COLORINDEX value set item attribute, which means the value set treats each item as an index into the logical color table unless otherwise specified. This style is most often used when the colors currently available are adequate. * VS_ICON: The attribute for each value set item is set to the VIA_ICON value set item attribute, which means the value set treats each item as an icon unless otherwise specified. * VS_RGB: The attribute for each value set item is set to the VIA_RGB value set item attribute, which means the value set treats each item as a RGB color value unless otherwise specified. This style is most often used when you need to create new colors. * VS_TEXT: The attribute for each value set item is set to the VIA_TEXT value set item attribute, which means the value set treats each item as a text string unless otherwise specified.
- Specify one or more of the following optional window styles, if desired, by using an OR operator (|) to combine them with the style specified from the preceding list:
* VS_BORDER: The value set draws a thin border around itself to delineate the control. * VS_ITEMBORDER: The value set draws a thin border around each item to delineate it from other items. Note: The VS_ITEMBORDER style is useful for items that are hard to see, such as faint colors or patterns. * VS_OWNERDRAW: The application is notified whenever the background of the value set window is to be painted. * VS_RIGHTTOLEFT: The value set interprets column orientation as right-to-left, instead of the default left-to-right arrangement. This means columns are numbered from right-to-left with the rightmost column being 1 and counting up as you move left. Home is the rightmost column and end is the leftmost column. There is no visible difference between a value set ordered left-to-right and a value set ordered right-to-left. Therefore, if your application uses multiple value sets, the ordering of the items should be consistent in each value set to avoid confusing the user. Note: The VS_RIGHTTOLEFT style is used on creation of the control. Changing this style after creation causes unexpected results. * VS_SCALEBITMAPS: The value set automatically scales bit maps to the size of the cell. If this style is not used, each bit map is centered in its cell. Also, if the cell is smaller than the bit map, the bit map is clipped to the size of the cell.
Using Value Set Controls
This section provides information that will enable you to create and use a value set control effectively.
Creating a Value Set
You create a value set by using the WC_VALUESET window class name in the ClassName parameter of WinCreateWindow call.
Before the value set is created, a temporary VSCDATA data structure is allocated so that the number of rows and columns of the value set can be specified.
Also, VS_* values are specified in the ulValueSetStyle variable so that the value set can be customized. The following sample code shows the creation of a value set:
VSCDATA vscData; /* VSCDATA data structure */
HWND hwndValueSet; /* Value set window handle */
ULONG ulValueSetStyle; /* Value set style variable */
/**********************************************************************/
/* Initialize the parameters in the data structure. */
/**********************************************************************/
vscData.cbSize = /* Size of value set equals size */
sizeof(VSCDATA); /* of VSCDATA */
vscData.usRowCount = 1; /* 1 row in the value set */
vscData.usColumnCount = 3; /* 3 columns in the value set */
/**********************************************************************/
/* Set the VS_* style flags to customize the value set. */
/**********************************************************************/
ulValueSetStyle =
VS_RGB | /* Use colors for items. */
VS_ITEMBORDER | /* Put border around each value */
/* set item. */
VS_BORDER; /* Put border around the entire */
/* value set */
/**********************************************************************/
/* Create the value set control window. */
/* The handle of the window is returned in hwndValueSet. */
/**********************************************************************/
hwndValueSet = WinCreateWindow(
hwndClient, /* Parent window handle */
WC_VALUESET, /* Value set class name */
(PSZ)NULL, /* No window text */
ulValueSetStyle, /* Value set styles */
(SHORT)10, /* X coordinate */
(SHORT)10, /* Y coordinate */
(SHORT)300, /* Window width */
(SHORT)200, /* Window height */
hwndClient, /* Owner window handle */
HWND_TOP, /* Z-order position */
ID_VALUESET, /* Value set window ID */
&vscData, /* Control data structure */
(PVOID)NULL); /* No presentation parameters */
/**********************************************************************/
/* Set the color value for each item in each row and column. */
/**********************************************************************/
WinSendMsg(hwndValueSet, /* Value set window handle */
VM_SETITEM, /* Message for setting items */
MPFROM2SHORT(1,1), /* Set item in row 1, column 1 */
MPFROMLONG(0x00FF0000)); /* to the color red. */
WinSendMsg(hwndValueSet, /* Value set window handle */
VM_SETITEM, /* Message for setting items */
MPFROM2SHORT(1,2), /* Set item in row 1, column 2 */
MPFROMLONG(0x0000FF00)); /* to the color green. */
WinSendMsg(hwndValueSet, /* Value set window handle */
VM_SETITEM, /* Message for setting items */
MPFROM2SHORT(1,3), /* Set item in row 1, column 3 */
MPFROMLONG(0x000000FF)); /* to the color blue. */
/**********************************************************************/
/* Set the default selection. */
/**********************************************************************/
WinSendMsg(hwndValueSet, /* Value set window handle */
VM_SELECTITEM, /* Message for selecting items */
MPFROM2SHORT(1,2), /* Item in row 1, column 2 */
NULL); /* Reserved value */
/**********************************************************************/
/* Since all items have been set in the control, */
/* make the control visible. */
/**********************************************************************/
WinShowWindow(hwndValueSet, /* Value set window handle */
TRUE); /* Make the window visible */
Retrieving Data for Selected Value Set Items
The next step is to be able to retrieve the data represented by a value set item. To do this, variables are specified for combined row and column index values, item attributes, and item information. Then the VM_QUERYSELECTEDITEM, VM_QUERYITEMATTR, and VM_QUERYITEM messages are used to retrieve the index values, attributes, and data. The following sample code shows how data for selected value set items is retrieved:
ULONG ulIdx; /* Combined row and column */
/* index value */
USHORT usItemAttr; /* Item attributes */
ULONG ulItemData; /* Item data */
/**********************************************************************/
/* Get the row and column index values of the item selected by the */
/* user. These values are returned in the ulIdx parameter. */
/**********************************************************************/
ulIdx = (ULONG)WinSendMsg(
hwndValueSet, /* Value set window handle */
VM_QUERYSELECTEDITEM, /* Message for querying */
/* the selected item */
NULL, NULL); /* Reserved values */
/**********************************************************************/
/* Determine the type of item that was selected. This message is */
/* only to determine how to interpret item data when a value set */
/* contains different types of items. */
/**********************************************************************/
usItemAttr = (USHORT)WinSendMsg(
hwndValueSet, /* Value set window handle */
VM_QUERYITEMATTR, /* Message for querying item attribute */
MPFROMLONG(ulIdx), /* Row and column of selected item */
NULL); /* Reserved value */
/**********************************************************************/
/* Get the information about the selected (non-textual) item. */
/* If you are dealing with text, you need to allocate a buffer */
/* for the text string. */
/**********************************************************************/
ulItemData = (ULONG)WinSendMsg(
hwndValueSet, /* Value set window handle */
VM_QUERYITEM, /* Message for querying an item */
MPFROMLONG(ulIdx), /* Row and column of selected item */
NULL); /* Set to NULL because the item is not */
/* a text item */
Arranging Value Set Items
The application defines the arrangement of value set items; they can be arranged in one or more rows, columns, or both. Items are placed from left to right in rows and from top to bottom in columns. The application can change the number of rows and columns at any time.
The number of items that can be displayed depends on the number of items that fit into the spaces provided by the defined rows and columns. If the number of items exceeds the number of spaces, the excess items are not displayed.
You can change the composition of a value set by specifying new items. The new items either can be added to the value set or can replace existing items.
Graphical User Interface Support for Value Set Controls
This section describes the support the value set control provides for graphical user interfaces (GUIs). Except where noted, this support conforms to the guidelines in the SAA CUA Advanced Interface Design Reference.
The GUI support provided by the value set control consists of navigating to and selecting value set items.
Since all value set items are mutually exclusive, only one of them can be selected at a time. Therefore, the only type of selection supported by the value set control is single selection.
Note: If more than one value set window is open, navigating to and selecting items in one value set window has no effect on the items displayed in any other value set window.
An initial choice is selected when the value set control is first displayed. If the application does not provide the initial selection by using the VM_SELECTITEM message, the choice in row 1, column 1 is selected automatically.
The value set control supports the use of a pointing device, such as a mouse, and the keyboard for navigating to and selecting items, except for items that are dimmed on the screen. This dimming of items is called unavailable-state emphasis and indicates that the items cannot be selected. However, the selection cursor, a dotted outline that usually indicates that an item can be selected, can be moved to unavailable items so that a user can press F1 to determine why they cannot be selected. The following sections describe the pointing device and keyboard support for the value set control.
Pointing Device Support
A user can use a pointing device to select value set items. The SAA CUA Guide to User Interface Design defines mouse button 1, the select button, to be used for selecting items. This definition also applies to the same button on any other pointing device.
An item can be selected by moving the pointer of the pointing device to the item and clicking the select button. When this happens, a black box is drawn around the item to show that it has been selected. The black box is called selected-state emphasis. In addition, the selection cursor is drawn inside the black box.
Keyboard Support
The value set control supports automatic selection, which means that an available item is selected when the selection cursor is moved to that item. The item is given selected-state emphasis as soon as the selection cursor is moved to it. No further action, such as pressing the spacebar, is required. The same black box and dotted outline are used, for selected-state emphasis and the selection cursor respectively, as when an item is selected with a pointing device.
A user can navigate to and select an item by using either the navigation keys or mnemonic selection to move the selection cursor to the item, as described in the following list:
- Items can be selected using the Up, Down, Left, and Right Arrow keys to move the selection cursor from one item to another.
- The Home and End keys can be used to select the leftmost and rightmost items, respectively, in the current row. If the Ctrl key is pressed in combination with the Home or End key, the item in the top row and the leftmost column, or the item in the bottom row and the rightmost column, respectively, is selected. Note: The preceding description assumes that the current style of the value set window is left-to-right. However, if the VS_RIGHTTOLEFT style bit is set, the directions described for the Home, End, Ctrl+Home, and Ctrl+End keys in the preceding paragraph are reversed.
- The PgUp key can be used to select the item in the top row that is directly above the current position of the selection cursor. The PgDn key can be used to select the item in the bottom row that is directly below the current position of the selection cursor. If the space in the top or bottom row directly above or below the current cursor position is blank, the cursor moves to the blank space.
- Another keyboard method of selecting items is mnemonic selection. A user performs mnemonic selection by pressing a character key that corresponds to an underlined character. Coding a tilde (~) before a text character in the item causes that character to be underlined and activates it as a mnemonic selection character. When this happens, the selection cursor is moved to the item that contains the underlined character, and that item is selected.
Enhancing Value Set Controls Performance and Effectiveness
This section provides dynamic resizing and scrolling to enable you to fine-tune a value set control.
Dynamic Resizing and Scrolling
The value set control supports dynamic resizing if the application sends the WM_SIZE message to a value set window. This means that the value set control automatically recalculates the size of the items when either the user or the application changes the size of the value set window.
If the value set window's size is decreased so that the window is not large enough to display all of the items the value set contains, the items are clipped. If scroll bars are desired to allow the clipped information to be scrolled into view, they must be provided by the application.