Using Controls

To properly use the GUI TOOLKiT, you should be familiar with the concept of controls. Controls are named Windows objects, contained in HostAccess's memory. Some controls are actions on other controls (for example, HIDE).

Within HostAccess you can place these controls on to the terminal screen as you would display characters. This means that the terminal screen can have Windows controls feeding data to the Host.

The following areas describe how to create controls with individual subroutines:

Subject Area:

Buttons

String Lists

Combo Boxes

List Boxes

Edit Boxes

Static Labels

Displaying images

Creating controls

To create and display Windows controls, simply load them into HostAccess's memory:

  • Via a single master subroutine, PIX.GUI.CONTROL.LOAD. All of the control details can thus be loaded via one subroutine rather than the programmer having to call each subroutine individually for each control.

  • Via individual subroutines, one for each type of control. For example, the subroutine PIX.GUI.LOAD.RADIOBUTTON will load a radio button.

To get any interaction with the Host system you will need to load the events for each control, and read the values from each control using different subroutines.

Control IDs

When you create controls you reference the control by a name, for ease of use.

The name can be a numeric or alphabetic name, and can be used as a label for reference throughout your host program.

This name is passed as the Control ID parameter in PICK BASIC subroutines.

Loading all types of controls

To load controls into HostAccess's memory all at once, call the following subroutine:

CALL PIX.GUI.CONTROL.LOAD(GUI.APP.NAME, CONTROL.DETAILS, CONTROL.VALUE, ERROR)

Where:

GUI.APP.NAME

This variable is useful to run GUI programs from within GUI programs, i.e. if you "EXECUTE" or "PERFORM" GUI programs from within GUI programs. The variable is prefixed automatically to all control names.
If you intend not to do this then you can pass a null. i.e. CALL PIX.GUI.READ.CONTROL.VALUE("",...).

CONTROL.DETAILS

A dynamic array containing sets of parameters describing each control to be loaded.

CONTROL.VALUE

Not used at present.

ERROR

Set to 1 if Error (for future use).

CONTROL.DETAILS

Each parameter in CONTROL.DETAILS is separated by a comma. The first seven parameters must be in the correct order.

  • Parameter 1 = the Control ID (its name).

  • Parameter 2 = the control type (for example, RADIO).

  • Parameters 3 - 7 depend on the control type.

  • Parameters 8+ are keywords, and can be in any order.

If all 7 primary parameters are not required, you can truncate the string when required but they must be in the order specified. Keywords are only accepted in position eight onwards. For example:

NAME,TYPE,xxx,yyy
NAME,TYPE,xxx,yyy,,,,Key1,...Keyn

The parameters passed to PIX.GUI.CONTROL.LOAD are similar to those passed to each individual subroutine, except that this routine will loop through a dynamic array of controls, calling the relevant subroutine for each control. The control details passed to this subroutine for each control will be the same as those passed to each individual control subroutine.

Loading Controls Individually

You can load single controls with single subroutines.

Each individual subroutine you call takes the following three parameters:

GUI.APP.NAME

This variable is useful to run GUI programs from within GUI programs, i.e. if you "EXECUTE" or "PERFORM" GUI programs from within GUI programs. The variable is prefixed automatically to all control names.
If you intend not to do this then you can pass a null. i.e. CALL PIX.GUI.READ.CONTROL.VALUE("",...).

CONTROL.DETAILS

When loading controls into HostAccess's memory, you need to pass a set of parameters as CONTROL.DETAILS. See individual control loading routines for descriptions of these parameters.

STRING

Set to  'O' if you require output string (AiF) to be formatted and sent back to the calling program. The calling program will need to send this command to HostAccess.

Loading Text Button Example

To load a text push-button use the following:

CALL PIX.GUI.LOAD.TEXTBUTTON(GUI.APP.NAME, CONTROL.DETAILS, STRING)