Field Equate Labels

Top  Previous  Next

Control Numbering

In WINDOW structures, every control (field) with a USE attribute is assigned a number by the compiler. By default, these field numbers begin with one (1) and are assigned to controls in the order they appear in the WINDOW structure code (the window itself is numbered zero). The actual assigned numbers can be overridden in the second parameter of the control's USE attribute.

The order of appearance in the WINDOW structure code determines the "natural" selection order of controls (which may be altered during program execution with the SELECT statement). The order of appearance in the WINDOW structure code is independent of the control's placement on the screen. Therefore, there is not necessarily any correlation between a control's position on screen and the field number assigned by the compiler.

In APPLICATION structures, every menu selection in the MENUBAR, and every control with a USE attribute placed in the TOOLBAR, is assigned a number by the compiler. By default, these numbers begin with negative one (-1) and are decremented by one (1) in the order the menu selections and controls appear in the APPLICATION structure code.

Equates for Control Numbers

There are a number of statements that use these compiler-assigned field numbers as parameters to indicate which controls are affected by the statement. It would be very tedious to "hard code" these numbers in order to use these statements. Therefore, Clarion provides a mechanism to address this problem: Field Equate Labels.

Field Equate Labels always begin with a question mark (?) followed by the label of the variable named in the control's USE attribute. The leading question mark indicates to the compiler a Field Equate Label. Field Equate Labels are very similar to normal EQUATE compiler directives. The compiler substitutes the field number for the Field Equate Label at compile time. This makes it unnecessary to know field numbers in advance.

Two or more controls with exactly the same USE variable in one WINDOW or APPLICATION structure would attempt to create the same Field Equate Label for all (each referencing a different field number). Therefore, when the compiler encounters this condition, all the Field Equate Labels for that USE variable are discarded. This makes it impossible to reference any of these controls in executable code, preventing confusion about which control you really want to reference. You can eliminate this problem by explicitly specifying the Field Equate Label for use by each control in the third parameter to the controls' USE attribute.

Array and Complex Structure Field Equates

Field Equate Labels for USE variables which are array elements always begin with a question mark ( ? ) followed by the name of the USE variable followed by an underscore and the array element number. For example, the field equate for USE(ArrayField[1]) would be ?ArrayField_1. Multi-dimensioned arrays are treated similarly (?ArrayField_1_1, ?ArrayField_1_2, ...). You can override this default by explicitly specifying the Field Equate Label for use by each control in the third parameter to the controls' USE attribute.

Field Equate Labels for USE variables which are elements of a complex data structure always begin with a question mark ( ? ) followed by the name of the USE variable with colons (:) replacing the periods (.). For example, the field equate for USE(Phones.Rec.Name) would be ?Phones:Rec:Name. This is done because Clarion labels may contain colons, but not periods, and a field equate is a label.

Using Field Equate Labels

Some controls' have USE attributes that can only be Field Equate Labels (a unique label with a leading question mark). This simply provides a way of referencing these fields in code or property assignment statements.

In executable code, there are many statements which use the field equate label to reference the control to affect (such as the DISPLAY statement). In all these statements, using a question mark (?) alone, without the USE variable name appended), always indicates performing the action on the current control that has input focus.

Example:

Window WINDOW('Dialog Window'),SYSTEM,MAX,STATUS

       TEXT,HVSCROLL,USE(Pre:Field)          !FEQ = ?Pre:Field

       ENTRY(@N3),HVSCROLL,USE(Pre:Array[1]) !FEQ = ?Pre:Array_1

       ENTRY(@N3),HVSCROLL,USE(File.MyField) !FEQ = ?File:MyField

       IMAGE(ICON:Exclamation),USE(?Image)   !USE attribute is a Field Equate Label

       BUTTON('&OK'),USE(?Ok)                !USE attribute is a Field Equate Label

      END

CODE

OPEN(Window)

?Ok{PROP:DEFAULT} = TRUE          !Field Equates used in property assignments

?Image{PROP:Text} = 'MyImage.GIF'

ACCEPT

 DISPLAY(?)                       !Re-Display control with current input focus

END