PreviousWindow Objects Using DialogNext

Chapter 5: Control Objects

The previous chapter looked at window objects. This chapter describes:

5.1 Control Objects

Control objects are also known as widgets or gadgets and they can be used in windows and dialog boxes. They cannot exist outside a window or dialog box, so you have to define a window or dialog box and select it before you can define controls. See the chapter Window Objects for further details.

Depending upon the control, you can use it to:

The controls covered in this chapter are:

Control
Use to
Text and Entry fields Read and enter data items, and supply text for labeling.
Push buttons Enable the user to select an immediate action.
Radio buttons Give the user a fixed set of mutually exclusive choices, when grouped.
Check boxes Give the user a set of choices that are not mutually exclusive, that is, the user can select none, any, or all of the choices.
List boxes Display a list of choices from which the user can select one or more.
Selection boxes Present a scrollable list of choices and place a selection in an entry field.
Scroll bars Enable the user to scroll to a particular value, when used with another control like an entry field.
Group boxes Outline a control or group of controls for the visual convenience of the user.
Tab control and Tab control pages Organize information like a spiral bound notebook containing pages and tabbed divider pages.
OLE2 controls Display a window from which the user can call any external object, for example, a spreadsheet.
User controls Contain objects not paintable by the Dialog System definition software. How you use a user control depends on its implementation.
ActiveX controls Display objects with predefined functions, usually supplied by third parties.

5.1.1 Text and Entry Fields

The most basic controls are entry fields. This section describes:

5.1.1.1 Displaying Text (Text Objects)

A text object is a control that you can use to help your user understand what information is displayed or asked for. You can think of a text field as a label. Figure 5-1 shows an example of the use of text fields.

Text object
Figure 5-1: Examples of Text Fields

You can use text fields as:

A text field is static. That is, no events or functions are associated with a text control. If you need a text field that you can change at run time, such as a status line or a dynamic prompt, use a display-only entry field. See the section Display-only Entry Fields for more information.

The topic Objects and Properties in the Help provides detailed information on defining text fields.

5.1.1.2 Getting Input Using Entry Fields

Entry fields are control objects that display the contents of a data item at run time and enable the user to edit the contents. You use an entry field when you do not know the possible values for a data item. In this situation, the user must supply the needed information.

An entry field is associated with a data item. Changes to the entry field made by the user are immediately put into its data item with no further action on your part. If the contents of the data item change, the entry field must be refreshed before it reflects the change. An entry field is refreshed when:

An entry field is not refreshed when its parent window is shown using the SHOW-WINDOW function.

If you set focus on a numeric entry field and the associated master field does not contain valid numeric data, the value will be set to zero.

Dialog System provides two types of entry fields – single line entry and multiple line entry (MLE).

5.1.1.2.1 Single Line Entry Field

The simplest entry field is a single line entry field, which can display or collect only one line of text.

As an example, in the Customer sample, users must supply information such as customer code, name, address and credit limit. They enter this information using entry fields.

Figure 5-2 shows several examples of single line entry fields.

Entry fields
Figure 5-2: Examples of Entry Fields

5.1.1.2.2 Using Entry Fields with Other Controls

You can also use entry fields with other controls to help the user select appropriate values.

For example, if you know the data item is in a particular range of values, you could use the entry field with a scroll bar to let the user "scroll" to the correct value.

Figure 5-3 shows an example of using an entry field with a scroll bar.

Entry field with scroll bar
Figure 5-3: Using an Entry Field with Scroll Bar

You can find an example of the dialog needed to implement this feature in the chapter Sample Programs.

The topic Data Definition and Validation in the Help describes how to set up validation checks using Data Definition.

5.1.1.2.3 Display-only Entry Fields

Some entry fields need to be display-only. For example, you might have a dialog box that lets the user update address information for employees. You might want the user to see, but not update, some fields, for example the employee name.

Another use of display-only entry fields is to build dynamic prompts or status lines. For example, you might not know the exact wording of a prompt at definition time. You can make the prompt a display-only entry field, then supply the correct text at run time.

To illustrate how to make a dynamic prompt, you might have a display-only entry field that is associated with an item in the Data Block named generic-prompt. In your program, fill the item using a statement like:

    move "Dynamic Prompt" to generic-prompt

The new prompt is then displayed when the entry field associated with generic-prompt is refreshed.

Display-only is a property of single line entry fields. The topic Objects and Properties in the Help describes how you set an entry field to display-only.

5.1.1.2.4 Autoswipe

Autoswipe is a property of an entry field: when the user tabs to the field, all the data associated with that field is selected. If the user inputs any data in the field, the field is cleared before the new data is entered.

You can use Autoswipe to clear a default value when you know the user would not use the default. For example, if you use an entry field to enter a filename, you may want the default to be a descriptive string like filename.ext. This gives the user an indication of the format you expect for the filename, but it is unlikely that a file would have that default name.

As soon as the user enters any data in the field, the existing text is cleared and the data entry begins in the first position of the field.

The SET-AUTOSWIPE-STATE function lets you change the Autoswipe state of an entry field. In the example above, once the user has entered a valid filename, you may want to set SET-AUTOSWIPE-STATE off. Then when the user tabs to this field, the field is not cleared before data is entered. See the topic Dialog Statements: Function in the Help.

5.1.1.3 Multiple Line Entry Fields

Like a single line entry field, a multiple line entry field (MLE) enables you to display and edit the contents of a data item. However, this control is most useful when you have a lot of information to collect, for example a lengthy text description of a product.

The MLE appears on the screen as a box with horizontal and vertical scroll bars. The scroll bars allow you to adjust the view of the data in the MLE. The scroll bars do not have any dialog associated with them; that is, Dialog System controls all the scroll bar actions for the MLE.

Figure 5-4 shows two MLEs. The one on the left has the word-wrap option set and the one on the right does not.

Multiple line entry
Figure 5-4: Multiple Line Entry Field

The data item associated with the MLE can contain alphanumeric and DBCS characters, and line feeds (ANSI decimal 10, x"0A"), which place successive characters on the next line in the display area of the MLE as you would expect. The user can view characters that extend beyond the right-hand or lower boundary by using the scroll bars.

You can set the MLE to word-wrap the displayed text so it never extends beyond the right-hand boundary. Single words that cannot fit are simply split.

The Objects sample program shows the differences between an MLE that has the word-wrap option set and an MLE that does not.

5.1.1.4 Editing an MLE

You can put or edit text in the MLE by:

5.1.1.5 Refreshing an MLE

When an MLE's data item is changed at run time, the MLE needs to be refreshed before the change is visible. An MLE is refreshed when:

Changes made by the user to the MLE are immediately put into its data item with no further action on your part.

5.1.2 Push Buttons

A push button lets a user select an action. The action indicated by the text in the push button occurs immediately. Figure 5-5 shows an example of a window with a push button.

Puch button
Figure 5-5: Typical Push Button

5.1.2.1 Assigning Bitmaps to Push Buttons

When you define a push button, you can use the Push Button Properties window to attach a set of bitmaps, instead of text, to a push button. You define a bitmap for each of the three possible states a push button can be in; normal, disabled, and depressed.

You must define a bitmap for the normal state. If you do not define a bitmap for the depressed or disabled states, the bitmap defined for the normal state is used.

However, you might want to set or change bitmaps at run time. See the chapter Using Bitmaps to Change the Mouse Pointer for further information.

5.1.3 Radio Buttons

Unlike push buttons, you can group radio buttons together to show the user a fixed set of mutually exclusive choices. For example, Figure 5-6 shows this use of radio buttons, in which the user must select only one method of billing.

Radio buttons
Figure 5-6: Typical Radio Buttons

Grouping radio buttons gives them the characteristic behavior, which is that only one button in the group can be selected at a time. When the user selects a new button, the previously selected button is deselected. See the section Grouping Controls in this chapter for a description of how to define a control group.

The dialog associated with a radio button is the same as the dialog for a push button. For example, the radio button VISA can have dialog such as:

BUTTON-SELECTED
    BRANCH-TO-PROCEDURE BILL-TO-VISA

where the procedure BILL-TO-VISA contains the necessary billing functions.


Note: You can deselect a radio button only by selecting another radio button within the control group.


For information on defining a radio button, see the topic Objects and Properties in the Help.

5.1.4 Check Boxes

Check boxes are much like radio buttons except the user can select choices that are not mutually exclusive. For example, as shown in Figure 5-7 you can use check boxes when you have a "check all that apply" situation.

Check boxes
Figure 5-7: Group of Check Boxes

You can attach a numeric data item to a check box. If the check box is set, the data item associated with the check box is set to one. If the check box is not set, the data item is set to zero.

See the chapter Sample Programs for further information.

5.1.5 List Boxes

You use list boxes to display a list of choices from which the user can select one or more. A list box consists of:

Dialog System provides three types of list boxes:

The Objects sample application shows the differences between a single selection list box and a multiple selection list box.

Figure 5-8 shows an example of a list box.

List box
Figure 5-8: Example of a List Box

For information on defining a list box, see the topic Objects and Properties in the Help.

5.1.5.1 Adding Items to a List Box

You can insert items into the list box in the following ways:

5.1.6 Selection Boxes

A selection box is a control object that is used to present a scrollable list of choices and place a selection in an entry field. It is sometimes known as a combination box or combo box.

Figure 5-9 shows the three types of selection boxes that are available:

Selection boxes
Figure 5-9: Typical Selection Boxes

The following describes the types of selection boxes:

Simple (or fixed) Consists of an entry field and a list box. You can either type in the entry field, or select an item from the list, which is then placed in the entry field.
Drop-down Consists of an entry field with an arrow button at the right-hand end and a hidden list box. When you press the arrow button, the list box drops down. The user can type in the entry field, or select an item from the drop-down list to be placed in the entry field. The list box disappears again when the user makes a selection or clicks elsewhere.
Drop-down list Consists of a display-only entry field with an arrow button at the right-hand end and a hidden list box. You cannot type into the display-only field; you must select a choice from the list. You can think of it as a list box that shrinks to show only the current selection.

You define the three types of selection box in exactly the same way, then choose the specific type you want as a property in the Selection Box Properties dialog box.

To add selection boxes individually to windows or dialog boxes:

  1. Select the window or dialog box.
  2. Click Selection box on the Objects toolbar
    - or -
    Click Selection box on the Object menu.

If you define a selection box where the drop-down list will obscure other controls in the window or dialog box, ensure that the selection box receives focus before the controls that might be obscured. Either define the selection box first, or use Controls on the Edit menu to change the control order. This ensures that all the controls are properly displayed at run time.

5.1.6.1 Entry Field

The entry field part of the selection box is linked to a data item called its master field. You normally place text in the entry field just to supply a default choice.

5.1.6.1.1 Refreshing the Entry Field

To display the contents of the master field in the entry field at run time, the selection box must be refreshed. A selection box is refreshed when:

If you show a selection box using the SHOW-WINDOW function, it is not refreshed.

5.1.6.1.2 Changing the Entry Field

If the user makes changes to the entry field by typing or selecting a choice in the list box, these changes are immediately put into the master field with no further action on your part.

Selecting an item in a selection box causes an ITEM-SELECTED event to be generated.

You can place text items in the list box in the following ways:

5.1.7 Scroll Bars

In a list box and an MLE, a scroll bar indicates the position and quantity of information visible in the list box. Using the scroll bar, the user can adjust the view of the information visible. However, in Dialog System you can also create a scroll bar as an independent control.

As an example, you can use the scroll bar with an entry field to let the user "scroll" to the correct value. The scroll bar example in the sample application Objects shows this usage.

Figure 5-10 shows a horizontal scroll bar.

Scroll bars
Figure 5-10: Horizontal Scroll Bar

The Scroll Bar Properties dialog box lets you assign defaults to scroll bar properties such as slider range, slider position and slider size. Using dialog, you can change these properties.

You can see a coded example in the chapters Tutorial - Creating a Sample Screenset and Tutorial - Using the Sample Screenset. For information on defining a scroll bar, see the topic Objects and Properties in the Help.

5.1.8 Group Boxes

A group box is a graphic frame used to outline a control or group of controls purely for the visual convenience of the user. This encourages the use of several controls to be understood as a group. Figure 5-11 shows an example of a group box.

Group boxes
Figure 5-11: Typical Group Box

Like a text control, no events or functions are associated with a group box.

For information on defining a group box, see the topic Objects and Properties in the Help.

5.1.9 Tab Controls

A tab control enables related information to be organized in a way that is intuitive and easy to use. Figure 5-12 shows an example of a tab control.

Tab controls
Figure 5-12: Typical Tab Control

A tab control is made up of individual pages. These are combined into a single control with each page represented as a tab along one edge (usually the top) of the control. Selecting a tab displays the associated page.

Tabs can contain text or bitmaps. If all the tabs do not fit on a single line, they can be displayed either with scroll arrows to move through the tabs, or the tabs can be wrapped over several lines so that they are all visible.

The visible area of the tab control is always the top page. Pages can contain any Dialog System control objects, apart from another tab control or window.

You can see a coded example in the chapter Sample Programs.

5.1.10 OLE2 Controls

An OLE2 control is a window, inside which you can display external data or objects, such as spreadsheets and bitmaps.

As an example, you can use the Paintbrush application to design and edit a picture, and then load that picture into your OLE2 window.

5.1.11 User Controls

You use a user control as a container for an object that is not paintable by the Dialog System definition software.

Events and functions on a User Control are implemented in a controlling program associated with the object. Typically the controlling program uses the class library to create and maintain the object.

You create and manipulate User Controls by generating the controlling program at definition time. The advantage of using a controlling program is that the object is completely user-definable while still having the benefits of being integrated with the Dialog System and run-time software.

Integrating user control objects with the definition software provides the following benefits:

For information on creating and manipulating user control objects, see the chapter Programming Your Own Controls.

5.1.12 ActiveX Controls

ActiveX controls are supplied by third-party vendors and can be integrated into Dialog System applications. The benefits listed above for user controls also apply to the use of ActiveX control with your screenset. Additional benefits of using ActiveX controls are that you can:

You need to purchase a development licence for any controls you may wish to use in your application. You are also bound by the vendor's licence agreement for the production and distribution of that control.

5.2 Grouping Controls

When controls, such as entry fields, radio buttons, and push buttons appear in a window or dialog box at run time, the user can move the keyboard input focus around them by pressing Tab.

Sometimes, several controls form a logical group (for example, a set of radio buttons) and either the user is interested in all the controls in the group or none of them. Therefore, it is convenient for successive presses of Tab to move the focus onto the group and then away to the next control or group. You can use the cursor keys to move around controls in a group. (Again, this is the default action, which you can change if you choose.)

You can achieve this behavior by putting the controls into a control group.

You must put a group of radio buttons into a control group so that they have the characteristic behavior that only one radio button in the group can be selected at a time. When one is selected, all the others in the same group are unselected.

Usually, you want the focus to start on the control or control group that the user is most likely to operate, and move around them in a convenient order with successive presses of Tab. The order of controls within each group also needs to be specified so the focus lands on the first control when Tab is used, and the cursor keys move the focus around the group's controls in a convenient order.


Note: You cannot Tab into a control group when the first item of the group is disabled.


You can specify the order of controls and groups in each window or dialog box. The procedure for doing this is explained in the topic Dialog System Overview in the Help.

5.3 Aligning Controls

Dialog System provides an alignment mechanism that makes it easy to align graphical objects when moving or sizing in a graphical environment.

Most of the alignment functions are available on the Alignment toolbar, which is available on the Alignment tab page. See the topic Dialog System Overview in the Help for a description of the Alignment toolbar.

The alignment options mean that you don't have to position controls exactly when you define them. You can quickly add the controls you need in rough form and then use the Alignment toolbar buttons to set the spacing and sizing.

Most alignment operations will require a combination of the alignment functions. For example, you might want to place a set of four push buttons near the bottom of the window. The steps you might follow are:

  1. Position the push buttons roughly in the area you want them to appear.

  2. Choose Select area on the Edit menu or use the select area toolbar option to enclose the objects. This enables the objects to be treated as a group.

  3. Select the Align to bottom button.

  4. Select the Equalize objects' width button.

  5. Select the Equalize objects' height button.

If the spacing is not ideal, there is an alternative way to align the buttons:

  1. Select Tile horizontally.

    This effectively gives no spacing.

  2. Size the group by:

    • Selecting Size on the Edit menu.

      -or-

    • Using the sizing handles on the selected controls.

    This increases the spacing between the controls.

Suppose now that the four push buttons are not in the correct order. You can rearrange them by using the Shuffle button. For example, the four push buttons might be labelled OK, Insert, Cancel and Help respectively and you want to change the order to Help, Cancel, Insert, and OK.

To rearrange the buttons, first select them in the order you want them. To do this:

  1. Click on the Help push button.

  2. Hold down the Ctrl key and click on the Cancel push button.

    Repeat this step for the Insert and OK push buttons.

  3. Click Reorder objects on the Alignment toolbar.

    The order becomes Help, Cancel, Insert and OK.

Each button has been swapped with another in the group into the order in which you selected them. The default order of swapping is left to right. That is, in this example, the OK button is the first to swap, Insert the second, Cancel the third and Help the fourth.

With all the alignment functions, you can undo the last operation by selecting Undo on the Edit menu.

The following steps describe how to space the four push buttons vertically down the right-hand side of the window:

  1. Select the controls as a group in the same way as described previously.

  2. Move the group towards the top of the window.

  3. Click Tile vertically.

  4. Click Align to right.

  5. Select Size on the Edit menu to stretch the spacing between the controls.

    You can now move the controls to their ideal position on the window and use Reorder objects to rearrange the order if necessary.

5.4 Sample Program

You can see examples of the Dialog System Control objects by running the Objects sample program supplied in your installation DialogSystem\demo\objects directory.

5.5 Using Bitmaps

This section explains how to use bitmap graphics with your Dialog System interface. Dialog System enables you to choose the bitmaps you want to use in your user interface for the following objects:

Bitmap object A decorated object the user can select.
Icon A small bitmap that represents the window or dialog box when it is minimized. See the section Attaching an Icon in the chapter Window Objects.
Mouse pointer A bitmap is used to indicate the mouse pointer, and indicate the different states of the mouse or the system. See the chapter Tutorial - Using Bitmaps to Change the Mouse Pointer.
Push buttons A bitmap is used to decorate the button or show the button in different states.

Dialog System includes bitmaps for the objects it uses and some standard bitmaps for the environment you are working under. You can also add your own bitmaps, icons and mouse pointers to use in a screenset. For more information, see the topic Bitmaps, Icons and Mouse Pointers in the Help.

5.5.1 Defining Bitmaps

Bitmaps can be placed anywhere within a window or dialog box. Their purpose is mainly for decoration, to draw attention to buttons or to place items such as logos in a window or dialog box. A mouse click over a bitmap causes a BITMAP-EVENT to occur, which places the bitmap's object handle in the $EVENT-DATA register. You can also define dialog to react to the MOUSE-OVER event for a bitmap.

You can assign a Master field to a bitmap from its Properties dialog box. This enables the displayed bitmap image to be changed dynamically at run time. For more information on this, see the topics Using Controls and Bitmaps, Icons and Mouse Pointers in the Help.

To place a bitmap in a window or dialog box:

  1. Select Bitmap on the Object menu in the main window.
    -or-
    Click the bitmap icon in the Objects toolbar.

    The Select Bitmap dialog box shown in Figure 5-13 is displayed.

    Select bitmap
    Figure 5-13: Select Bitmap Dialog Box

  2. Specify the bitmap name in Name
    -or-
    Select it from Available images.

  3. Click OK when you have made a choice.

    The Select Bitmap dialog box disappears and the outline shape of the bitmap appears in the window or dialog box.

  4. Use the mouse to position the bitmap and click.

    The bitmap now appears.

You can use Controls on the Edit menu to put other controls after the bitmap in the list. Controls has no effect on the display until the window is hidden and reshown.

5.6 Bitmapped Push Buttons

Dialog System provides default appearances for push buttons. You can use bitmapped push buttons to change the appearance of a push button.

For example, when you want a button to convey a graphic symbol, or you want to make the push button appearance vary depending on its state.

To associate bitmaps with a button:

  1. Double-click on the button.
    -or-
    Select the button then choose Properties on the Edit menu in the main window.

    The Push Button Properties dialog box, shown in Figure 5-14 is displayed.

    Push button properties
    Figure 5-14: Push Button Properties Dialog Box

  2. Click the Options tab.

    You see the options available, as in Figure 5-15.

    Push button properties - options
    Figure 5-15: Push Button Properties Dialog Box - Options

  3. Select Bitmapped.

    This option becomes marked and the Button State Bitmaps options become available. There are three choices:

    • Normal

    • Depressed

    • Disabled

  4. Select the bitmap file you require from the Button state bitmap dropdown lists.

    This bitmap file name is displayed as the selected bitmap file.

  5. Click OK to return to the main window.

When creating a window toolbar, you may want to tailor your own version of the toolbar control program to implement a native Win32 toolbar.


Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousWindow Objects Using DialogNext