#CONTROL (define a control template) 

Top  Previous  Next

 

 

#CONTROL( name, description )[, MULTI ] [, SINGLE ], PRIMARY( message [, flag ] ) ] [, SHOW ] [, HLP( helpid ) ]

                              [, WINDOW ] [, REPORT] [, WRAP( control ) ] [, PRIORITY( number )] [, DESCRIPTION( expression ) ]

                              [, REQ( addition [,| BEFORE| ] ) [,| FIRST | ]

                                                            | AFTER|          | LAST | ]

                               CONTROLS

                                  control statements [, #REQ ]

                               END

 

#CONTROL

Begins a code template that generates a set of controls into a window and the source code required to manipulate them into embedded source code points.

name

The label of the template (must be a valid Clarion label).

description

A string constant describing the control template.

MULTI

Specifies the #CONTROL may be used multiple times in a given window.

SINGLE

Specifies the #CONTROL may be used only once in a given procedure (or program, if the embedded source code point is global). SINGLE is the negation of the MULTI attribute.

PRIMARY

Specifies a primary file for the set of controls must be placed in the procedure's Data / Tables Pad.

message

A string constant or template symbol containing a message that appears in the Data / Tables Pad next to the #CONTROL's Primary file.

flag

Either OPTIONAL (the file is not required), OPTKEY (the key is not required), or NOKEY (the file is not required to have a key).

SHOW

Specifies the #CONTROL prompts are placed on the procedure properties window.

HLP

Specifies on-line help is available.

WINDOW

Tells the Application Generator to make the #CONTROL available in the Window Formatter. This is the default setting if both WINDOW and REPORT are omitted.

REPORT

Tells the Application Generator to make the #CONTROL available in the Report Formatter. If omitted, the #CONTROL may not be placed in a REPORT.

WRAP

Specifies the #CONTROL template is offered as an option for the control when the "Translate controls to control templates when populating" option is set in Application Options.

control

The data type of the control for which the #CONTROL is a viable alternative.

PRIORITY

Specifies the order in which the #CONTROL is generated. The lowest value generates first. If omitted, the PRIORITY is assumed to be 5000.

number

An integer constant in the range 1 to 10000.

REQ

Specifies the #CONTROL requires a previously placed #CODE, #CONTROL, or #EXTENSION before it may be used.

addition

The name of the previously placed #CODE, #CONTROL, or #EXTENSION.

BEFORE

Legacy attribute, replaced by PRIORITY.

AFTER

Legacy attribute, replaced by PRIORITY.

FIRST

Equivalent to PRIORITY(1).

LAST

Equivalent to PRIORITY(10000).

DESCRIPTION

Specifies the display description of a #CONTROL that may be used multiple times in a given application or procedure.

expression

A string constant or expression that contains the description to display.

CONTROLS

Specifies the controls for the #CONTROL, and must be terminated with an END statement. This is a "pseudo-Clarion keyword" in that, if you replace the CONTROLS statement with a WINDOW statement, you can use the Text Editor's Window Formatter to create the controls.

controls

Window control declarations that specifiy the control set belonging to the #CONTROL.

#REQ

Specifies the control is required. If deleted from the window or report, the entire #CONTROL (including all its controls) is deleted.

#CONTROL defines the beginning of a code template containing a "matched set" of controls to populate into a window or report as a group. It also generates the source code required for their correct operation into embedded source code points. A #CONTROL section may contain Template and/or target language code. The #CONTROL section is terminated by the first occurrence of a Template Code Section (#PROGRAM, #MODULE, #PROCEDURE, #CONTROL, #CODE, #EXTENSION, or #GROUP) statement, or the end of the file. Within a single Template set, separate #CONTROL sections may not be defined with the same name.

#CONTROL generates the code to operate its controls into #EMBED embedded source code points using the #AT/#ENDAT structure. #RESTRICT can restrict use of the #CONTROL based on an expression or Template language statements.

A #CONTROL section may contain #PROMPT statements to prompt for the values needed to generate proper source code. These prompts appear on the Actions window in the environment. It may also contain #EMBED statements which become active only if the #CONTROL section is used.

The x and y parameters of the AT attribute of the controls in the #CONTROL set determine the positioning of the control relative to the last control in the #CONTROL set placed on screen (or relative to the window, if first). If these parameters are omitted, the programmer is prompted for the position to place the control. This makes it simple to populate an entire set of controls without requiring the programmer to place each one individually.

The WRAP attribute specifies the #CONTROL is offered as an option to the programmer when the "Translate controls to control templates when populating" option is set in Application Options. The control parameter specifies the type of control to which the #CONTROL applies. This makes the #CONTROL a "wrapper" for the control type, such that, when the programmer populates the control in the formatter, a dialog appears offering the choice of populating either the control itself, or the #CONTROL template. For example, with the WRAP(LIST) attribute on a #CONTROL, when the programmer attempts to populate a LIST control a dialog appears offering the opportunity to use either the #CONTROL template (which generates executable code to "drive" the control) or the LIST control itself (requiring the programmer to write the "driving" code for the control).

 

Example:

#CONTROL(BrowseList,'Add Browse List controls')

 #PROMPT('Allow Inserts',CHECK),%InsertAllowed,DEFAULT(1)

 #ENABLE(%InsertAllowed)

     #PROMPT('Insert Hot Key',@s20),%InsertHotKey,DEFAULT('InsertKey')

 #ENDENABLE

 #PROMPT('Allow Changes',CHECK),%ChangeAllowed,DEFAULT(1)

 #ENABLE(%ChangeAllowed)

     #PROMPT('Change Hot Key',@s20),%ChangeHotKey,DEFAULT('CtrlEnter')

 #ENDENABLE

 #PROMPT('Allow Deletes',CHECK),%DeleteAllowed,DEFAULT(1)

 #ENABLE(%DeleteAllowed)

     #PROMPT('Delete Hot Key',@s20),%DeleteHotKey,DEFAULT('DeleteKey')

 #ENDENABLE

 #PROMPT('Update Procedure',PROCEDURE),%UpdateProc

 CONTROLS

  LIST,AT(,,270,99),USE(?List),IMM,FROM(Queue:Browse),#REQ

  BUTTON('Insert'),AT(,,40,15),USE(?Insert),MSG('Add record')

  BUTTON('Change'),AT(,,40,15),USE(?Change),DEFAULT,MSG('Change Record')

  BUTTON('Delete'),AT(,,40,15),USE(?Delete),MSG('Delete record')

 END

#!

 #AT(BeforeAccept)

   #IF(%InsertAllowed)

?Insert{PROP:Key} = %InsertHotKey

   #ENDIF

   #IF(%ChangeAllowed)

?Change{PROP:Key} = %ChangeHotKey

   #ENDIF

   #IF(%DeleteAllowed)

?Delete{PROP:Key} = %DeleteHotKey

   #ENDIF

 #ENDAT

#!

 #AT(%ControlEvent),WHERE(%ControlOriginal='?Insert' AND %ControlEvent='Accepted')

   #IF(%InsertAllowed)

Action = AddRecord

%UpdateProc

   #ENDIF

 #ENDAT

#!

 #AT(%ControlEvent),WHERE(%ControlOriginal='?Chg' AND %ControlEvent='Accepted')

   #IF(%ChangeAllowed)

Action = ChangeRecord

%UpdateProc

   #ENDIF

 #ENDAT

#!

 #AT(%ControlEvent),WHERE(%ControlOriginal='?Delete' AND %ControlEvent='Accepted')

   #IF(%DeleteAllowed)

Action = DeleteRecord

%UpdateProc

   #ENDIF

 #ENDAT

See Also:     #EMBED, #WHERE ,#RESTRICT, #AT (insert code in an embed point)