Clarion Community Help

Navigation: Templates > Template Language Reference > Complete Alpha Listing >====== #CONTROL (define a control template) ======

#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