PMGuide - Spin Button Controls
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
A spin button control (WC_SPINBUTTON window class) is a visual component that gives users quick access to a finite set of data by letting them select from a scrollable ring of choices. Because the user can see only one item at a time, a spin button should be used only with data that is intuitively related, such as a list of the months of the year, or an alphabetic list of cities or states. This chapter explains when and how to use spin buttons in PM applications.
About Spin Button Controls
A spin button consists of at least one spin field that is a single-line entry (SLE) field, and up and down arrows that are stacked on top of one another. These arrows are positioned to the right of the SLE field.
You can create multi-field spin buttons for those applications in which users must select more than one value. For example, in setting a date, the spin button control can provide individual fields for setting the month, day, and year. The first spin field in the spin button could contain a list of months; the second, a list of numbers; and the third, a list of years.
The application uses a multi-field spin button by creating one master component that contains a spin field and the spin arrows, and servant components that contain only spin fields. The spin buttons are created at component initialization. The servant components are passed a handle to the master component in a message. When a servant spin field has the focus, it is spun by the arrows in the master component.
The list of values in a spin button entry field can be an array of data or a list of consecutive integers, defined by an upper and a lower limit.
Using Spin Button Controls
This section describes how to create a spin button control.
Creating a Spin Button
A spin button is created as a public window class by using WinCreateWindow, with a class style of WC_SPINBUTTON and a window style of WS_VISIBLE. These are joined with any of the spin button style flags by using a logical OR (|). The spin button style flags let you specify:
- Character input restrictions (none, numeric, read-only)
- Presentation of the data in the spin field (left-justified, right-justified, centered)
- Presence or absence of a border around the spin field
- Spin speed
- Zero-padding of numeric spin fields
The placement and width of the spin button component are specified as parameters in WinCreateWindow.
The upper and lower limits of numeric fields, the value array pointer for arrays of strings, and the initial value in the spin field are all set by messages sent from the application to the component.
You can destroy the spin button component window using WinDestroyWindow when finished. The component handle that was returned when the spin button was created is the input parameter to WinDestroyWindow. The following sample code shows an example of how to create a spin button.
ULONG ulSpinStyle; /* Spin Button style */
HWND hwndSpin; /* Spin Button window handle */
/**********************************************************************/
/* Set the SPBS_* style flags. */
/**********************************************************************/
ulSpinStyle = SPBS_MASTER | /* Spin button has its own */
/* buttons, */
SPBS_NUMERICONLY | /* and it only holds numbers */
SPBS_JUSTRIGHT | /* that are right justified, */
SPBS_FASTSPIN; /* and it spins faster as */
/* the arrows are held down */
/**********************************************************************/
/* Create the Spin Button control window. */
/* The handle of the window is returned in hwndSpin. */
/**********************************************************************/
hwndSpin = WinCreateWindow (
hwndClient, /* Parent window handle */
WC_SPINBUTTON, /* Spin Button window class name */
(PSZ)NULL, /* No window text */
ulSpinStyle, /* Spin Button styles variable */
(LONG)10, /* X coordinate */
(LONG)10, /* Y coordinate */
(LONG)150, /* Window width */
(LONG)50, /* Window height */
hwndClient, /* Owner window handle */
HWND_TOP, /* Sibling window handle */
ID_SPINBUTTON, /* Spin Button control window ID */
(PVOID)NULL, /* No control data structure */
(PVOID)NULL); /* No presentation parameters */
/**********************************************************************/
/* Set the limits of the Spin Button control, since it has a style */
/* of SPBS_NUMERICONLY. */
/**********************************************************************/
WinSendMsg (hwndSpin, /* Spin Button window handle */
SPBM_SETLIMITS, /* Set limits message */
(MPARAM)1000, /* Spin Button maximum setting */
(MPARAM)0); /* Spin Button minimum setting */
/**********************************************************************/
/* Set the initial value of the Spin Button. */
/**********************************************************************/
WinSendMsg (hwndSpin, /* Spin Button window handle */
SPBM_SETCURRENTVALUE, /* Set current value message */
(MPARAM)100, /* Spin Button initial value */
(MPARAM)NULL); /* Reserved value */
/**********************************************************************/
/* Because all items have been set, make the control visible. */
/**********************************************************************/
WinShowWindow (hwndSpin, /* Spin Button window handle */
TRUE); /* Make the window visible */
Graphical User Interface Support for Spin Button Controls
Users can interact with the spin button using either the keyboard or a pointing device, such as a mouse, as follows:
- Using the select button (button 1) on the pointing device, users first give focus to the spin field they want to change, and then click on either the Up Arrow or Down Arrow until the value they want is displayed in the spin field.
- Using a keyboard, users press the:
* Up Arrow and Down Arrow keys to see the choices * Left Arrow and Right Arrow keys to move the cursor left and right within a spin field * Home and End keys to move the cursor to the first and last characters in a spin field * Tab and Shift+Tab keys to move the input focus from one field to another in multi-field spin buttons
Users can view the values in a spin field one at a time, or they can rapidly scroll a list by keeping either the Up or Down Arrow keys pressed. When a spin button is not read-only, users can advance quickly to the value they want to set in a spin field by typing over the value currently displayed.