| **Navigation:**  [[templates.htm|Templates]] > [[tlrcontents.htm|Template Language Reference]] > Complete Alpha Listing >====== #CONTROL (define a control template) {{c6h0068.jpg|C6H0068.jpg}} ====== | [[ context  set template code generation context .htm|{{btn_prev_n.gif|Previous page}}]][[tlrcontents.htm|{{btn_home_n.gif|Return to chapter overview}}]][[ create  create source file .htm|{{btn_next_n.gif|Next page}}]] |
|  ||

| **#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** |

{{blk2blue.jpg|blk2blue.jpg}}

| **#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  define embedded source point .htm|#EMBED]], [[ where  define  code embed point availability .htm|#WHERE]] ,[[ restrict  define section use constraints .htm|#RESTRICT]], [[ at  insert code in an embed point .htm|#AT (insert code in an embed point)]]