SATGUI Display Language (SAT/DL) Commands |
Syntax: |
action {name ?parameters?} |
---|---|
Parameters: |
name=item_name parameters=parameters |
Options: | None. | Return: | None. |
Example: | action {addname "Adrian" "Davis"} |
The action command is used to initiate an action from a SAT server-side action process.
Syntax: |
addBorder {name position size ?options?} |
---|---|
Parameters: |
name=item_name position=xpos,ypos size=widthxheight options=groove|raised|sunken|title |
Options: |
groove=Set relief style to "groove". raised=Set relief style to "raised". sunken=Set relief style to "sunken". title=Display title at top left of border. |
Return: | None. |
Example: | addBorder {address 2,10 40x12} more |
The addBorder command is used to create a border item.
If an option is specified which is not matched to one of the literal options it is ignored.
Borders should be created before the items which are to be created within them. The border is not transparent, so creating it on top of existing items will obscure them. This effect could be used to temporarily "remove" items from the screen, as they can be made visible again by removing the border.
If the height is set to zero a horizontal line is displayed. A width of zero will display a vertical line.
The default relief style is "groove". The default can be set to another style using setRelief.
If the title option is specified a title derived from the name will be displayed at the top left of the border. This option is best used with the groove relief style.
Syntax: |
addButton {name position size ?options?} |
---|---|
Parameters: |
name=item_name position=xpos,ypos size=width options=disabled|exit|noborder|normal|outline|validate|action |
Options: |
disabled=Disable button. exit=Set action to cause application to exit. noborder=Set border to 0 (default 2). normal=Enable button. outline=Display outline around button. validate=Perform all entry validations when actioned. validate(?prefix?)=Perform entry validations of prefix items when actioned. action=If not literal then assume option is action. |
Return: | None. |
Example: | addButton {Exit 2,10 6 exit} more |
The addButton command is used to create a button item.
If an option is specified which is not matched to one of the literal options it is assumed to be an action.
Although buttons can be created without an action, this is not particularly useful.
The Button name may have a prefix, "+" is equivalent to the normal option and "-" to disabled.
Syntax: |
addButtons {position size ?pad? buttondata} |
---|---|
Parameters: |
position=xpos,ypos size=width pad=characters buttondata=buttons |
Options: | None. | Return: | None. |
Example: | addButtons {2,10 6 {Save save_customer} {Exit exit}} more |
The addButtons command is used to create a row of button items.
If the pad parameter is specified this value is used as the number of characters padding between buttons when a null buttondata item is found, the default is 2.
All button item options can be used for each item in buttondata.
Syntax: |
addCheckButtons {name position labels ?options?} |
---|---|
Parameters: |
name=item_name position=xpos,ypos labels=labels options=disabled|horizontal|normal|outline|title |
Options: |
disabled=Disable check buttons. horizontal=Arrange check buttons horizontal (default vertical). normal=Enable check buttons. outline=Display outline around check buttons. title=Display title at top left of check buttons. |
Return: | name:label (For each button label. Set to "Y" if selected, otherwise "N"). |
Example: | addCheckButtons {attributes 2,10 {+Bold Italic Underline}} more |
The addCheckButtons command is used to create a Check-Buttons Item.
Active check buttons can be set by prefixing the appropriate labels with "+".
If the title option is specified a title derived from the name will be displayed at the top left of the check buttons. This option is best used with the groove relief style outline.
The Check-Buttons name may have a prefix, "+" is equivalent to the normal option and "-" to disabled.
Syntax: |
addData {name value ?options?} |
---|---|
Parameters: |
name=item_name value=value options=safe |
Options: |
safe=Create "safe" data item. |
Return: | None. |
Example: | addData {customer "VC001"} |
The addData command is used to create a data item.
Both clear and remove can be used to delete non-safe data items. Safe data items can only be deleted using remove.
Syntax: |
addEntries {position ?pad? columdata} |
---|---|
Parameters: |
position=xpos,ypos pad=characters columndata=columns |
Return: | None. |
Example: | addEntries {2,10 {10,25 {First_Name} {Last_Name} {Age 4}}} more |
The addEntries command is used to create a column/row (grid) pattern of Entry Items.
If the pad parameter is specified this value is used as the number of characters padding between columns, the default is 5.
All entry item options can be used for each item in columndata.
Syntax: |
addEntry {name position size ?options?} |
---|---|
Parameters: |
name=item_name position=xpos,ypos size=label,entry options=center|disabled|focus|normal|outline|right|secret|validate|action|validation |
Options: |
center=Align label text in center of label area (default is left). disabled=Disallow entry update via keyboard. focus=Give this entry focus. normal=Allow entry update via keyboard. outline=Display outline around entry. right=Align label text to right of label area (default is left). secret=Display "*" instead of actual character entered. validate=Perform all entry validations when actioned. validate(?prefix?)=Perform entry validations of prefix items when actioned. action=If not literal or validation then assume option is action. validation=If not literal assume option is validation. |
Return: | name (Value of entry text). |
Example: | addEntry {First_Name 2,10 8,20} more |
The addEntry command is used to create a labeled entry item.
If an option is specified which is not matched to one of the literal options, it is first tested to see if there is a validation with that name. If there is a validation it is associated with the item such that the validation is invoked when the cursor moves away from the entry. If there is no matching validation the option is assumed to be an action. The action is activated by pressing the [enter] key when the cursor is in the entry.
The Entry name may have a prefix, "+" is equivalent to the normal option and "-" to disabled.
Syntax: |
addLabel {name position size text ?options?} |
---|---|
Parameters: |
name=item_name position=xpos,ypos size=width options=blue|center|outline|noborder|red|right |
Options: |
blue=Set label text colour to "blue". center=Algin label text in centre of label area (default is left). outline=Display outline around label. noborder=Do not add border padding around label. red=Set label text colour to "red". right=Align label text to right of label area (default is left). |
Return: | None. |
Example: | addLabel {address 2,10 20 "This is label text"} more |
The addLabel command is used to create a label item.
If an option is specified which is not matched to one of the literal options it is ignored.
Syntax: |
addMenu {{menu {item ?options?} {...}} {menu {item ?options?} {...}}} |
---|---|
Parameters: |
menu=menu item=item options=disabled|exit|group|normal|validate|action |
Options: |
disabled=Disable menu item. exit=Set action to cause application to exit. group(groups)=Set list of groups which enable this menu item. normal=Enable menu item. validate=Perform all entry validations when actioned. validate(?prefix?)=Perform entry validations of prefix items when actioned. action=If not literal then assume option is action. |
Return: | None. |
Example: | addMenu {{File {Save {save file}} {Delete {delete file}}}} more |
The addMenu command is used to create a menubar.
On Windows and Unix systems the menubar will be created at the top of the application screen.
If an option is specified which is not matched to one of the literal options it is assumed to be an action.
The menu/item name may have a prefix, "+" is equivalent to the normal option and "-" to disabled.
A null item displays a separator bar.
The menu options obey the state. Each menu option can override the state and forced to be either normal or disabled. In addition, the state of menu options can be controlled using Groups.
If a menubar already exists this command will have no effect. In order to add a new menubar the existing one must first be deleted.
Syntax: |
addMultiList {name position size columns ?options?} |
---|---|
Parameters: |
name=item_name position=xpos,ypos columndata=columns size=lines options=copy|outline|yscroll|validate|action |
Options: |
copy(data_items)=Copy columns from selected line to data_items. outline=Display outline around list. validate=Perform all entry validations when actioned. validate(?prefix?)=Perform entry validations of prefix items when actioned. yscroll=Add "Y" direction (vertical) scrollbar. action=If not literal then assume option is action. |
Return: | name (Value of selected line text). |
Example: | addMultiList {result 2,10 10 {Name,30 Age,4 Pay,10,numeric}} more |
The addMultiList command is used to create a multi column listbox item.
If an option is specified which is not matched to one of the literal options, it is assumed to be an action. The action is activated by double clicking on the required line in the list.
Syntax: |
addRadioButtons {name position labels ?options?} |
---|---|
Parameters: |
name=item_name position=xpos,ypos labels=labels options=disabled|horizontal|normal|outline|title |
Options: |
disabled=Disable radio buttons. horizontal=Arrange radio buttons horizontal (default vertical). normal=Enable radio buttons. outline=Display outline around radio buttons. title=Display title at top left of radio buttons. |
Return: | name (Label of selected button). |
Example: | addRadioButtons {start_at 2,10 {+begin middle end}} more |
The addRadioButtons command is used to create a Radio-Buttons Item.
An active radio button can be set by prefixing the appropriate label with "+". If more than one active radio button is specified, then the last only is used.
If the title option is specified a title derived from the name will be displayed at the top left of the radio buttons. This option is best used with the groove relief style outline.
The Radio-Buttons name may have a prefix, "+" is equivalent to the normal option and "-" to disabled.
Syntax: |
addValidation {name pattern} |
---|---|
Parameters: |
name=item_name pattern=regular_expression |
Options: | None. | Return: | None. |
Example: | addValidation {customer_id "^[A-Z][0-9]{6}$"} |
The addValidation command is used to create a new entry item validation.
The pattern must be a regular expression in a form acceptable to TCL.
Syntax: |
clear |
---|---|
Parameters: | None. |
Options: | None. | Return: | None. |
Example: | clear |
The clear command is used to delete all display and non-safe data items.
Safe data items and user defined validations are not affected by this command.
Syntax: |
newScreen {{title} ?options?} |
---|---|
Parameters: |
title=Title data in same format used by setTitle options=size|group |
Options: |
size=widthxheight group=Name of menubar Group. |
Return: | None. |
Example: | newScreen {{"Add Customer"} 80x24 customer} |
The newScreen command is used to initailise the application screen.
If an option does not match the pattern of a screen size it is assumed to be a group.
This command deletes all display and non-safe data items, sets the window title text, clears the message line, optionally sets the screen size/Group and refreshes the menu (if one exists).
Therefore the above example is eqivalent to:-
clear setTitle {"Add Customer"} setMessage {} setSize 80x24 setGroup customerThe default window title is set in the application configuration file. The default action for newScreen is to append the title text to the window title with a dash separator. The title replace option causes the window title to be replaced with the title text. To restore the default title use newScreen with a null title value.
Syntax: |
remove name |
---|---|
Parameters: |
name=menu|item_name |
Options: | None. | Return: | None. |
Example: | remove address |
The remove command is used to delete a display, data item or menu.
To remove a menubar use the name menu.
Safe data items can be deleted using this command.
Syntax: |
setAction name action |
---|---|
Parameters: |
name=item_name action=action |
Options: |
None. |
Return: | None. |
Example: | setAction save {save_customer cust_id} |
The setAction command is used to set/change the action for the item identified by name.
Syntax: |
setDateFormat date_format |
---|---|
Parameters: |
date_format=date_format |
Options: |
None. |
Return: | None. |
Example: | setDateFormat dd/mm/yyyy |
The setDateFormat command is used to set the date format used for entry date validations.
By default mm/dd/yy and mm/dd/yyyy formatted dates will be accepted by date validations.
Syntax: |
setGroup group |
---|---|
Parameters: |
group=group |
Options: | None. | Return: | None. |
Example: | setGroup customer |
The setGroup command is used to set the name of the menu group.
This command causes the menubar options to be updated so that, where options are group specific, they are only enabled for the specified group.
Syntax: |
setItem {name value ...} |
---|---|
Parameters: |
name=item_name value=value |
Options: |
None. |
Return: | None. |
Example: | setItem {first_name "Adrian"} more |
The setItem command is used to set the value of button, check-button, data, entry, label, multi-list and radio-button items.
The format of the value parameter depends on the type of item for which the value is to be set. For multi-list items a list of values (one for each item in the list) may be given.
Syntax: |
setItems {{name value} {name value} ...} |
---|---|
Parameters: |
name=item_name value=value |
Options: |
None. |
Return: | None. |
Example: | setItems {{first_name "Adrian"} {last_name "Davis"}} |
The setItems command is used to set the value of button, check-button, data, entry, label and radio-button items. This command cannot be used to set multi-list items.
The format of the value parameter depends on the type of item for which the value is to be set.
Syntax: |
setMessage {text ?options?} |
---|---|
Parameters: |
text=text options=blue|red |
Options: |
blue=Set label text colour to "blue". red=Set label text colour to "red". |
Return: | None. |
Example: | setMessage {"Record not found" red} |
The setMessage command is used to set the message line text.
Syntax: |
setRelief option |
---|---|
Parameters: |
option=groove|raised|sunken |
Options: |
groove=Set relief style to "groove". raised=Set relief style to "raised". sunken=Set relief style to "sunken". |
Return: | None. |
Example: | setRelief raised |
The setRelief command is used to set the default relief style.
The default relief style is "groove".
Syntax: |
setSize size |
---|---|
Parameters: |
size=widthxheight |
Options: | None. | Return: | None. |
Example: | setSize 80x20 |
The setSize command is used to set the size of the application screen.
Syntax: |
setState option |
---|---|
Parameters: |
option=disabled|normal |
Options: |
disabled=Disable items. normal=Enable items. |
Return: | None. |
Example: | setState disabled |
The setState command is used to set the default item state.
The default state depends on the access level assigned to the user. For users with "full" access the default state is "normal", for "read only" the default state is "disabled".
Syntax: |
setTitle {text ?options?} |
---|---|
Parameters: |
text=text options=replace |
Options: |
replace=Replace window title with text. |
Return: | None. |
Example: | setTitle {"Add Customer"} more |
The setTitle command is used to set the window title text.
The default window title is set in the application configuration file. The default action for setTitle is to append the text to the window title with a dash separator. The replace option causes the window title to be replaced with text. To restore the default title use setTitle with a null text value.
Syntax: |
unlock |
---|---|
Parameters: | None. |
Options: | None. | Return: | None. |
Example: | unlock |
The unlock command is used explicitly unlock the display.
This is intended to be used for screens without an associated process.