When a user selects
the choice, a check mark symbol
(&check.) appears in the check box to indicate that the
choice is selected.A control is a part of the user interface that lets a user interact with data.
Controls are usually identified by text; for example, headings, labels in push buttons, field prompts, and titles in windows.
Static text controls are text fields, bitmaps, icons, and boxes that you can use to label or box other controls. Your user typically does not interact with these controls using the keyboard or mouse. Generally, you do not need to change a static control's appearance on the screen, so visually these controls tend to be unchanging. Static text control classes include IBitmapControl, IIconControl, IOutlineBox, IGroupBox, and IStaticText. The IStaticText class creates and manages the static text control window.
You can set the text and its color, size, and position in the static text window.
An entry field is a control window that enables a user to view and edit a single line of text. An entry field provides the text-editing capabilities of a simple text editor and is useful whenever an application requires a short line of text from the user.
If the application requires more sophisticated text-editing capabilities and multiple lines of text from the user, the application can use a Multiline edit field.
Applications typically use entry fields in dialog windows, although they can be used in non-dialog windows as well. The following section contains a sample and an example to show you how to create an entry field.
A multiline edit (MLE) field enables users to view and edit multiple lines of text. Use the IMultiLineEdit class to create an MLE field. The member functions of the IMultiLineEdit class enable you to display text files with horizontal and vertical scrolling, read a file into and save it from an MLE, or perform basic clipboard tasks (for example, cut, paste, copy, and clear).
A button is a type of control window used to initiate an operation or to set the attributes of an operation. A button can appear alone or with a group of other buttons. When buttons are grouped, you can move from button to button within the group by pressing the Arrow keys. You can also move among groups by pressing the Tab key.
A user can select a button by clicking it with the mouse or by pressing the spacebar when the button has the keyboard focus. In most cases, a button changes its appearance when selected.
A button is always owned by another window, usually a dialog window or an application's client window. It posts messages or sends notification messages to its owner when a user selects the button. The owner window receives messages from a button and can send messages to the button to alter its position, appearance, and enabled or disabled state.
To use a button in a dialog window, your application specifies the control in a dialog template in the application's resource-definition file. The application processes button messages in the dialog-window procedure. This is not supported on Motif.
There are four (three for Motif) main types of buttons, which determine how the button looks and behaves:
A radio button, check box, or three-state check box control an operation; a push button initiates an operation. For example, you might set printing options (such as paper size, print quality, and printer type) in a print-command dialog window containing an array of radio buttons and check boxes. After setting the options, you select a push button to notify an application that printing should begin (or be canceled). Then the application queries the state of each check box and radio button to determine the printing parameters.
A push button is a rectangular window that contains a text string. Typically, an application uses a push button to let the user start or stop an operation. A push button represents an action that is initiated when a user selects it. You can label it with text, graphics, or both. When a user selects a push button, the action occurs immediately if there is a handler for the generated command event.
Use the IPushButton class to create and maintain the push button window. By default, a push button generates an application ICommandEvent. You can change the default style by changing the window style value to generate a help event or a system command event. Using system command events is not recommended for portable applications. You cannot set colors for push buttons on the WIndows operating system
The command events generated by pressing the Left, Center, and Right push buttons are handled by the AHelloWindow::command member function. Note, the command events are the same as those used for the corresponding menu items. Therefore, the command function processing is the same whether you press the push button or select the item on the menu bar.
A radio button is a window with text displayed to the right of a small circular indicator. Use radio buttons to display a set of choices from which the user can select one. Each time the user selects a radio button, that button's state toggles between selected and unselected. This state remains until the next time the user selects the button. An application typically uses radio buttons in groups.
A group of radio buttons contains at least two radio buttons. Within a group, usually one button is selected by default. The user can move the selection to another button by using the cursor keys; however, only one button can be selected at a time. Radio buttons are appropriate if an exclusive choice is required from a fixed list of options. For example, applications often use radio buttons to let users select the screen foreground and background colors.
The IRadioButton class lets you create and manage the radio button window. The ISelectHandler class processes the selection of a radio button. You add the handler to either the radio button or its owner window by calling the handler's handleEventsFor function.
Check boxes are similar to radio buttons, except that they can offer multiple-choice selection, as well as individual choice.
When a user selects
the choice, a check mark symbol
(&check.) appears in the check box to indicate that the
choice is selected.
When a user selects
the choice, the check box is filled in to
indicate that the choice is selected.
By selecting the choice again, the user deselects the check box. Use a check box to set a choice in a group of choices that are not mutually exclusive.
Check boxes also toggle application features on or off. For example, a word processing application might use a check box to let the user turn word wrapping on or off.
The ICheckBox class lets you create and maintain a check box. The selection of a check box is processed by using the ISelectHandler class. You add the handler to either the check box or its owner window.
Three-state check boxes are similar to check boxes, except that they can be displayed in halftone as well as selected and unselected. An application might use the halftone state to indicate that, currently, the check box is not selectable. This control is not supported on Motif. The selection of a three-state check box is processed by using the ISelectHandler class and adding the handler to either the three-state check box or its owner window.
If a three-state check box is selected, it can be either checked or halftoned. You have to use a combination of the isSelected and isHalftone member functions to determine the state of a three-state check box. The following table shows the state of the three-state check box and its relation to the isSelected and isHalftone member functions.
| Current State |
isSelected |
isHalftone |
|
|---|---|---|---|
| checked | true | false | |
| halftone | true | true | |
| not checked | false | false |
A list box is a control that displays several items at a time, one or more of which can be selected by the user.
An application uses a list box when it requires a list of selectable fields that is too large for the display area or a list of choices that can change dynamically. Each list item contains a text string and an optional handle. The text string is displayed in the list box window, but the handle is available to the application to reference other data associated with each of the items in the list.
The IBaseListBox class creates and manages list box control windows. Two types of list box controls are derived from IBaseListBox. They are IListBox and ICollectionViewListBox. IListBox extends the IBaseListBox list box control creation and management to include adding, removing, and replacing list box items. ICollectionViewListBox<Element, Collection> template class extends the IBaseListBox control to enabling viewing of an ordered collection as items in a list box. The sequence of elements is the same between the ordered collection and the list box.
A combination box is two controls in one: an entry field and a list box. There are three types of combination box controls:
This section describes combination box controls, also called combination boxes and prompted entry fields, which let the user choose and edit items from a list in an application.
Combination box controls enable the user to enter data by typing in the entry field or by choosing an item in the list box, unless it is a drop-down list, in which case, you cannot edit the entry field. Combination box controls manipulate the list box using the following member functions:
A combination box control automatically manages the interaction between the entry field and the list box. For example, when the user chooses an item in the list box, the combination box control displays the text for that item in the entry field. Then, the user can edit the text without affecting the item in the list box. When the user types letters in the entry field, the combination box control scrolls the list box contents so that items with those letters become visible.
Objects of the IBaseComboBox class create and manage combination box control windows. There are two types of combination boxes derived from IBaseComboBox. They are IComboBox and ICollectionViewComboBox.
Population of the combination box list box items is done by the derived classes. IComboBox contains the add, remove, and replace functionality, while ICollectionViewComboBox populates the combination box list box from collection elements using the setItems member function.
A slider is a visual component that enables a user to set, display, or modify a value by moving the slider arm along the slider shaft.
A slider consists of a slider arm, one or two slider scales and, optionally, detents, tick marks, tick text, and slider buttons.
Note that you can have two
native slider scales, but only the primary one is visible.
The following table lists the slider components and their descriptions:
| Slider Component | Description | |
|---|---|---|
| Detent (PM and CCL control only) | A user-selectable mark that can be placed anywhere along the slider scale. | |
| Progress indicator | A read-only version of a slider. | |
| Slider arm | An arm that shows the current value by its position on the slider shaft and can be changed programmatically, as well as by users. Users can move the arm along the shaft to set slider values. | |
| Slider buttons | Buttons that move the slider arm incrementally in the indicated direction. | |
| Slider shaft | A track for the slider arm to move along. | |
| Tick text | A label indicating the value the tick mark represents. | |
| Tick mark | An incremental value in a slider scale. |
Typically, sliders let users set values that have familiar increments, such as feet, degrees, or decibels. You can use sliders for other purposes when immediate feedback is required, such as to blend colors or show a task's percentage of completion. For example, your application might let a user mix and match color shades by moving a slider arm, or a progress indicator (with the ribbonStrip style) could show how much of a task is complete by filling in the slider shaft as the task progresses.
The slider's appearance and user's interaction with a slider is similar to that of a scroll bar. However, these two controls are not interchangeable because each has a unique purpose. A scroll bar scrolls information into view that is outside a window's work area, while the slider sets, displays, or modifies that information.
You can customize a slider to meet varying application requirements, while providing a user interface component that can be used easily to develop applications that conform to the Common User Access (CUA) user interface guidelines. Your application can specify different scales, sizes, and orientations for its sliders, but the underlying function of the control remains the same.
The ISlider class inherits from the IProgressIndicator class, which is a read-only version of the slider control. Typically, you use a progress indicator to display the percentage of a task that is complete by filling in its shaft as the task progresses. The default for progress indicators is to use the ribbonStrip style to fill the shaft. If you do not use this, there is a slider arm present to indicate the current value. Users cannot move the slider arm in a progress indicator.
Typically, you use the ISliderArmHandler class to handle events resulting from a user changing a control's input value without releasing the mouse, such as rotating the circular slider or moving the arm of a slider. ISliderArmHandler objects process input tracking events for the ISlider and ICircularSlider controls.
You create a handler derived from ISliderArmHandler and attach it to either the control whose input users can change or to the control's owner window. Call IHandler::handleEventsFor to pass the appropriate control window or owner window to the edit handler.
A spin button control 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 the months of the year or an alphabetic list of cities or states.
A spin button consists of at least one spin field and up and down arrows that are stacked on top of one another. These arrows are positioned to the right of the spin field.
Two types of spin buttons are derived from IBaseSpinButton. They are INumericSpinButton and ITextSpinButton.
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 during the construction of the master. When a servant spin field has the focus, it is spun by the arrows in the master component or by the cursor keys.
The value in a spin button entry field can be an element in an array of data or within a range of integers, defined by an upper and lower limit. Spin buttons that use arrays of data are text spin buttons and those that use a range of integers are numeric spin buttons.
Attach a handler derived from ISpinHandler to the spin button to capture spin events, such as the user pressing the up or down arrow.
Creating and Using Text Controls
Using List and Slider Controls
IBitmapControl
IIconControl
IOutlineBox
IGroupBox
IStaticText
IEntryField
IMultiLineEdit
IPushButton
IRadioButton
ICheckBox
IBaseListBox
IBaseComboBox
ISlider
ICircularSlider
IProgressIndicator
IBaseSpinButton
