Using the Editors

This chapter describes each of the selection widgets and how, when they are grouped together, they provide users with choices. Selection widgets include:

• Check boxes—Allow users to make one or more choices.

• List boxes—Can function as a selection list box, allowing the user to select any number of items from the list, or as an action list box, where each item in the list has a corresponding action or event.

• Radio buttons—Allow users to make a single selection.

• Toggle buttons—Allow users to select and deselect a behavior or action.

Selection widgets provide a graphical way of displaying valid choices to your users. Each of these widget types offers a unique presentation and facility for selecting and indicating which option or choice the user has made.

To determine what choice a user has made, refer to "Selection Group Data" in Application Development Guide for information on querying selection groups.

Using Check Boxes

Check boxes provide a method for turning conditions off or on. When you group check boxes (refer to "Grouping Selection Widgets"), you provide a set of choices from which a user can select one or more options, or none. At runtime, when a check box item is selected, a check mark or an x (in Windows) appears next to the selected item; a three-dimensional, shaded box changes color in Motif.

In the following illustration, the grouped check boxes allow for one or more selections to be made. You can use the library function sm_getfield to determine what choices a user has made.

Figure 20-1 One or more options can be checked.

Use the Label property to define the literal text that displays next to the check box. If your application runs on a GUI platform, you can assign a pixmap to a check box so that an image appears next to the check box instead of text; assign one to display when the check box is selected, another to indicate that it is not armed, and still another to indicate that the check box is inactive. Refer to "Displaying a Picture on Widgets" for more information.

Using List Boxes

A list box presents the user with a noneditable, vertical column of choices. The list box can be one of two list box types:

• Select Any—Allows the user to select any number of items from the list.

• Action—Has an action or event associated with each item in the list.

When you group a list box (choose EditGroupCreateSelection Group), you can control the number of allowable selections and assign group entry and exit functions to the widget.

How to Define a List Box's Behavior

Select a list box. Under Identity, specify the how you want to use the list box in the Listbox Type property:

• Select Any—The user can choose zero to any number of items (to change the number of allowable selections, you must make the list box a selection group; refer to "Grouping Selection Widgets" for more information).

  To make a selection, the user can:

  • Use arrow keys to move the cursor to the desired item in the list, and then press the Space bar to select.

  • Enter the first character of a listed item to move the cursor to that occurrence.

  • Mouse click to select and deselect items. Shift+click to select contiguous items; Ctrl+click to select noncontiguous items.

  • Ctrl+click to deselect an already selected item.

  • Mouse click to select the first item and drag the mouse to select additional contiguous items.

  • Double-click on the list box to execute the associated control string set in the Double Click property.

• Action—Allows the list box to act like a menu. You can associate an action or event with each item in the list. When the user clicks on one of the items, the corresponding control string is executed (a double-click event is not executed on an action-type list box).

Selected items are displayed in reverse video.

You can determine the user's selection by querying the selected property of the list box's occurrences.

Refer to "Making Selections in List Boxes" in Application Development Guide for more information about extended selections in list boxes.

By default, a list box has a border around it. For character mode, you can assign a border style and title as well. You can also set the Border property to No to display no border at all. These settings have no effect on the GUI platforms. However, to include a title on a list box, you can draw a box (use the box widget) and assign a label to the box. Refer to "Adding Borders to Widgets" for details on creating borders and boxes around widgets.

Figure 20-2 illustrates three list boxes that are synchronized arrays. In this example, the data from three different, but related, columns scroll together and allow the user to select one or more records from the group. This is achieved by using a validation function on each list box that ensures that the other list boxes have the same occurrence selected as the one the user selected.

Figure 20-2 Synchronized list boxes can provide a means of selecting multiple records.

To restrict the number of selections to only one, define a list box as a group (refer to "Grouping Selection Widgets") and set the # of Selections property appropriately.

Scrolling the Data

You define how many occurrences display on the screen. When the number of items, or occurrences, exceeds what can be displayed at one time, the user can scroll the list.

How to Make a Scrolling List Box

1. Select a list box.
2. Define the number or rows that display on the screen by doing either of the following:

   • Under Geometry, enter the number in the Onscreen Rows property.

   • Drag the widget by one of its resize handles to the desired height.

If the number of elements in the array exceeds what can be displayed onscreen in the list box:

3. Under Geometry, set the Scrolling property to Yes. Additional scrolling-related properties are displayed. By default, a vertical scroll bar appears on the widget.
4. Under the Scrolling property in the Max Occurrences subproperty, enter the total number of occurrences required to accommodate the data. A blank (empty) value will return the maximum number of elements.
5. (Optional) Under the Scrolling property, set the Vertical Scroll Bar property accordingly.

   • Yes—(default) Allows the user to display offscreen occurrences by clicking on the vertical scroll bar.

   • No—The scroll bar is not displayed on the widget. The user can display offscreen occurrences by using the arrow keys or the SHIFT or SCROLL logical keys.

     Note: The ZOOM logical key displays offscreen occurrences only for an action-type list box.

Do any of the following to populate a list box:

• The list box's Initial Text property.

  Select the list box. Under Format/Display in the Initial Text property, enter the data (one item per line). Press Enter after each line. You can also choose the Read File button to read data from an external file. Choose OK to save your additions and to exit the Initial Text dialog box.

• At runtime, from a database or from an LDB screen (refer to "Using Local Data Blocks" in Application Development Guide).

• The screen's Entry Function.

  Select the screen that contains the list box. Under Focus in the Entry Function property, enter the name of the function that will populate the list. At runtime, when the screen opens, its screen entry function will populate the list.

Performing Actions

You can assign a control string to each occurrence in a list box to cause an action or event to occur when the user chooses items on the list. In this way, the list box functions as a menu might. However, if you define the list box to function as a selection group (by choosing EditGroupCreateSelection Group), the behavior is controlled by the group validation via a control string attached to the entire list box (for more information on group validation hook functions, refer to "Group Functions" in Application Development Guide).

How to Make a List Box Function Like a Menu

1. Create or select a list box.
2. Under Identity, specify Action in the Listbox Type property.
3. Under Validation in the Control String property, enter a control string for each list item by either:

   • Typing the string in the Setting field of the Properties window. Press Enter between each to define one control for each occurrence.

   • Choosing More. The Zoom window opens where you can enter or edit the control strings. Assign one control string per occurrence. Choose Close to exit.

Refer to Chapter 18, "Programming Control Strings," in Application Development Guide for details on control string syntax and invoking a control string from a widget.

Using Radio Buttons

Radio buttons allow the user to make exactly one selection (or none) in a group. When the user selects a radio button at runtime, its button appears darkened, and any other radio buttons in the group are immediately deselected.

By default, a radio button specifies that zero or one selection can be made, and on screen entry, none of the radio buttons are selected.

How to Define the Number of Selections

1. Select a radio button group (refer to "Grouping Selection Widgets" for details on creating/selecting selection groups).

   The Type field at the top of the Properties window should indicate that a Group is selected.

2. Under Identity, specify either of the following specifications in the # of Selections property:

   • 0 or 1—(default) Allows the user to select one button or none.

   • 1—The user must select one of the radio buttons in the group.

1. Select a radio button group (refer to "Grouping Selection Widgets" for details on creating/selecting selection groups).

   The Type field at the top of the Properties window should indicate that a Group is selected.

2. Under Identity in the Init Selections property, enter the number of the radio button that should appear selected on screen entry. The members of a group are numbered sequentially from left to right and top to bottom.

   For example, in Figure 20-3, the radio button group consists of two buttons. The Init Selections property is set to 1. So when the screen opens, the first radio button (Customer) is selected. This group of radio buttons also specifies that one of the two radio buttons must be chosen before the user can proceed.

   

   Figure 20-3 The user can choose one radio button: Customer or Employee.

---

Using Toggle Buttons

Toggle buttons are in/out graphical buttons. At runtime, when a toggle button is pushed, a particular behavior is turned on. The button remains on—or in the "in" position—until it is selected again. It then appears to be in the off or "out" position—so the behavior is toggled off.

By default, any number of toggle buttons can be selected. You can redefine the number of possible selections by grouping the buttons and setting the # of Selections property for the group.

Figure 20-4 illustrates how toggle buttons can be used to turn a specific behavior on or off. The screen, typical of many word processing applications, allows the user to choose B to implement bold text, U to underline, and I to italicize.

Figure 20-4 Both the B and I toggle buttons are selected—turning both bold and italic attributes on.

Use the Label property to define the literal text that displays on the toggle button. By default, the text is centered. In Motif, you can change the default alignment of the text by changing the value in the Panther distributed resource file (refer to "Aligning Button Labels in Motif" for information).

If your application runs on a GUI platform, you can assign pixmaps to a toggle button so that an image appears on the button instead of text; assign one to display when the button is selected, another to indicate that it is not armed, and still another to indicate that the button is inactive. Refer to "Displaying a Picture on Widgets" for more information on displaying pictures on buttons.

Grouping Selection Widgets

When you group selection widgets, you can define behavior for the group as a single entity, as opposed to defining behavior for individual widgets. By virtue of creating a group, you gain access to properties that define the group as a whole—such as group name, number of selections, tabbing behavior, group entry, exit and validation functions—and you can use group-specific library functions at runtime.

This section describes:

• How to create a group (only selection widgets of the same type can be grouped).

• How to set group properties.

• How to change group members—adding and removing widgets.

Depending on the widget type and the property specification for the group, a user can make one or more selections from the group.

Creating Selection Groups

1. Create the widgets that are to be a part of the group—these can be any number of check boxes, radio buttons, or toggle buttons, or a single list box.

   All widgets in the group must be of the same type. They can be close together or far apart on the screen.

2. Select the widget or widgets that you want to assign to the group.
3. Choose EditGroupCreateSelection Group. An invisible group widget is created; notice that the Type field at the top of the Properties window indicates that a Group is selected. You now have access to the group properties.

To identify and assign property values to all widgets that comprise a group, you must first find all members of the group. You can set properties for all members and thereby ensure that they are the same color, font, size, etc.

How to Identify the Members of the Group

1. Do either of the following:

   • Choose ViewWidget List and select the group widget from the Name list

   • Select any widget or widgets associated with a group.

2. Choose EditGroupSelect Members.

   All members of the group are selected, and you can set the intersecting properties for the widgets.

   If you select widgets associated with two or more different groups, the Select Group Member dialog box (Figure 20-5) opens. Select the group from the left hand column and choose OK.

   All members that comprise the group are selected.

   

   Figure 20-5 The Select Group Members dialog box displays all the groups with which the selected widget is associated.

While you can define unique property settings for each member of a group, you can also define how the group as a whole should behave through its properties. There are two methods you can use to access a group's properties:

Note: Although a group is selected, its members are not visibly selected on the workspace screen.

How to Select a Group from the Widget List

1. Choose ViewWidget List.
2. Select the desired group from the Name list. A group name is, by default, group followed by a number. The hidden group identifier precedes the members that comprise that group. Be sure that no other widgets are selected. Only the group identifier should be highlighted in the Widget List to access its properties.

1. Select any member of the group.
2. Choose EditGroupSelect Groups. The Properties window now displays the properties associated with the group.

Table 20-1 lists the group properties alphabetically along with the heading under which they can be found in the Properties window.

Naming a Group

Panther assigns a default name to a group when it is created—group followed by a consecutive number. The groups on a screen are numbered in the order in which they are created. So, the first group you create on the screen is identified as group1.

How to Assign a Name to the Group

1. Select the group. (For methods of selection, refer to "How to Select a Group from the Widget List" or "How to Select a Group via a Group Member".
2. Under Identity, type the name in the Name property.

   Group names follow the same conventions as widget names; they can be up to 31 character long, and must start with an alphabetic character. A group and widget cannot share the same name on the screen.

1. Select the group. (For methods of selection, refer to "How to Select a Group from the Widget List" or "How to Select a Group via a Group Member".
2. Under Identity, set the # of Selections property to the desired number. Each widget type has a default setting for the number of selections. There are three possible settings:

   • 0 or 1—Specifies that no selection or only a single selection is required. This is the default specification for grouped radio buttons.

   • 1—Specifies that one and only one selection must be made.

   • Any—Specifies that zero or many selections can be made. This is the default specification for check boxes, toggle buttons, and list boxes.

     Note: The ZOOM logical key is supported only for a list box in a Panther selection group with the # of Selections property set to 0 or 1.

1. Select the group. (For methods of selection, refer to "How to Select a Group from the Widget List" or "How to Select a Group via a Group Member".
2. Under Identity, enter the number of the selection in the Init Selections property. Members of a group are numbered left to right and top to bottom on your screen, starting with 1.

   Use the Widget List to determine the number that corresponds to the desired widget. For groups that allow more than one selection, separate the numbers with a comma in the property specification.

   For example, to specify that the second widget in a group be the initial selection on screen entry, enter 2 in the Init Selections property. Figure 20-6 illustrates how that might look in a group consisting of four check boxes—two-by-two. The second check box in the group is already selected on screen entry.

   

   Figure 20-6 The second widget in the selection group is identified as the initial selection for the group.

To change the content of a group—by either adding or removing widgets—you essentially redefine the group as a whole.

How to Add a Widget or Widgets to an Existing Group

1. Select all members of the existing group, by either:

   • Selecting the group widget from the Widget List.

   • Selecting at least one member of the group.

2. Choose EditGroupSelect Members.
3. Select (Shift+click) any additional widgets that you want to add to the group.
4. With all the widgets selected that are to be grouped, choose EditGroupUpdate Group Members.

   The existing group now includes the additional widgets, and the group's properties are displayed in the Properties window.

1. Select members of the group that you wish to keep in the existing group by either:

   • Clicking on the desired widgets in the group.

   • Selecting at least one member of the group and choosing EditGroupSelect Members. Then deselect any of the members that should be eliminated from the group.

2. With the widgets selected that are to be grouped, choose EditGroupUpdate Group Members.

   The existing group is redefined to includes the new set of widgets, and the group's properties are displayed in the Properties window.