• Internal Variables
• Cross Platform Issues
• Using Translations (Multi-Language Support)
• Using Grids
• Using HotKeys
• Using Groups
• Using TCL Procedures
• Using Colours
• Using Borders as Contianers for Display Items
• Using Multiple (Child) Windows

Internal Variables

When an Action is invoked a number of SATGUI/SATSHELL "internal" variables are set, which are particularly useful when used in conjunction with HotKeys.

:fheight	Height of window which had focus when Action invoked.
:focus	Item which had focus when Action invoked.
:fposition	Position of window which had focus when Action invoked.
:ftype	Type of item which had focus when Action invoked (Example: entry).
:fvalue	Value of item which had focus when Action invoked.
:fwidth	Width of window which had focus when Action invoked.
:height	Height of monitor screen in pixels (Monitor vertical resolution).
:theight	Height of window which contained trigger item when Action invoked.
:tposition	Position of window which contained trigger item when Action invoked.
:trigger	Name of item which invoked Action.
:ttype	Type of item which invoked Action.
:twidth	Width of window which contained trigger item when Action invoked.
:twindow	Name of window which contained trigger item when Action invoked.
:width	Width of monitor screen in pixels (Monitor horizontal resolution).

Positions indicate the location of the top-left of the window and are relative to the top-left of the screen. They are given in the same format required by newWindow and placeWindow which is:-

+XPos+YPos

Example

+200+150

NOTE: The internal variables are used in the same way as item values when specifying Actions.

Cross-Platform Issues

The differences become more obvious when many small display items are aligned close together. In some cases a compromise in the screen layout will be sufficient, others may be resolved by using the addGrid command (See Using Grids).

Using Translations (Multi-Language Support)

In order to simplify setting up the Translations the setItem command will create a safe Data item (See addData) if the name of the item begins with "@". To setup many translations the setItems command may be used.

Example:

setItems {
   {@sample_1 "Example I"}
   {@sample_2 "Example II"}
   {@sample_3 "Example III"}
}

Using the above example Translation...

addEntry {Sample_2 1,1 10,15}

...will display...

By default, the translation for a Label Item sets the text for the label title. To create a translation for the label text add a ":text" suffix to the item name...

setItems {
   {@label_1      "Label One Title"}
   {@label_1:text "Label One Text"}
}

Using Grids

Grids are created using the addGrid command. The addGrid examples page shows some simple uses of this command.

Options

Options may be defined on two levels. At the gird and/or the item level. For most purposes Options will most likely be defined at the grid level, making use of Percent Substitution to indicate which button was pressed. However, there may be a requirement to define specific options to be associated with particular buttons. To specify options at the item level, the item name and its options must be enclosed in braces ("{}").

Example:

addGrid {keypad 1,1 1 {
   {1 2 3}
   {4 5 6}
   {7 {8 red} 9}
   } {myaction %}
}

Layout

The addGrid command, as the name implies, creates a grid of (check/radio) buttons and/or labels. An additional degree of control is provided by a facility to allow a grid item to span several grid cells (Where a cell is the specified size of a grid item). A cell span is defined by specifying an integer, indicating how many cells to span, as an item option.

Example:

addGrid {test  1,1 6 {
   {!Label_1 {Button_1 2} !Label_2}
   {!Label_3 Button_2 Button_3 !Label_4}
   } {myaction %} raised
}

Check/Radio Buttons

Grids can also be used as a flexible tool to create check/radio button groups.

The plus option ("+") when used with check/radio buttons specifies which buttons are activated when the grid is created.

Check Button Example:

This example creates 10 check buttons. The check buttons are set to "Y" when selected and "N" when not selected. For example: When this grid is created run_on:monam is set to "Y" and run_on:fripm is set to "N".

addGrid {run_on 1,1 1 {
  {!   !Mon       !Tue     !Wed     !Thu     !Fri}
  {!AM {@monam +} {@tueam} {@wedam} {@thuam} {@friam}}
  {!PM {@monpm +} {@tuepm} {@wedpm} {@thupm} {@fripm}}
 } raised
}

Radio Button Example:

This example creates 10 radio buttons in two groups ("dep" and "arr"). The characters on the right of the colon indicate the value the radio buttons group will have when the button is selected. For example: the deliver:arr group will have the value mon when the arr:mon button is selected.

addGrid {deliver 1,1 1 {
  {!        !Mon         !Tue       !Wed       !Thu       !Fri}
  {!Depart {%dep:mon +} {%dep:tue} {%dep:wed} {%dep:thu} {%dep:fri}}
  {!Arrive {%arr:mon +} {%arr:tue} {%arr:wed} {%arr:thu} {%arr:fri}}
 } raised
}

Percent Substitution

There are two Percent Substitution options available when using addGrid:-

%	Replaced with name of grid item.
%%	Replaced with default -or- grid item literal.

Examples:

addGrid {keypad 1,1 1 {
   {1 2 3}
   {4 5 6}
   {7 8 9}
   } {myaction %}
}

addGrid {keypad 1,1 1 {
   {1 2 3}
   {4 {5 'myitem'} 6}
   {7 8 9}
   } {myaction % %%} 'myglobal'
}

Hans Harder has produced SATUTILS, which currently consists of a couple of very useful "pop-up" style utilities created using the addGrid command (See Contributed Software).

SATDATE	SATCALC

Using HotKeys

HotKeys allow for the use of Alt/Control/Function keys to invoke Actions (See addHotKey).

HotKeys simply invoke an Action. However, by using internal variables it is possible to write Actions which behave differently depending, For example, on which item had focus when the Action was invoked.

Example:

addHotKey {F1 {myaction :focus :fvalue}}

...will invoke the myaction Action when the F1 key is pressed. The name and value of the item which had focus are passed as parameters to the Action.

For a HotKey to function some part of the application screen must have focus. Focus may be set to either the application screen as a whole -or- to a specific entry item. The addEntry command can be used to set the focus of an entry item when it is created. The setFocus command can be used to set the focus to the application screen -or- an entry item at any time. The newScreen command will set the focus to the application screen.

Using Groups

Sometimes it is necessary to enable/disable groups of display items and menu options. The group option which is available for menu options and most display items can be used to simplify this process.

When a group is set for a menu option -or- display item, the option/item is enabled only when the current group matches the group specified for it. There are two ways to set the current group:-

• newScreen
• setGroup

NOTE: A menu option -or- display item may belong to more than one group by specifying a comma demilited list of groups.

Examples:

addButton {Save 10,1 8 group(updated) {savefile filename}}

In this example the "Save" button is active only when the current group is set to updated.

addButton {Save 10,1 8 group(created,updated) {savefile filename}}

In this example the "Save" button is active when the current group is set to either created or updated.

Using TCL Procedures

It is possible to define TCL procedures and call them as actions. For the present this facility is not fully documented. If you are interested in TCL programming TCL Developer Xchange is a good place to start.

To call a TCL procedure -or- a SAT/DL procedure directly as an action, use the name of the procedure with a colon (":") prefix as the action (See the Notebook example).

Using Colours

The following colours are available for use with the color(color) and color(foreground/background) parameters:-

snow ghostwhite whitesmoke gainsboro floralwhite oldlace linen antiquewhite papayawhip blanchedalmond bisque peachpuff navajowhite moccasin cornsilk ivory lemonchiffon seashell honeydew mintcream azure aliceblue lavender lavenderblush mistyrose white black darkslategray dimgray slategray lightslategray gray lightgrey midnightblue navy cornflowerblue darkslateblue slateblue mediumslateblue lightslateblue mediumblue royalblue blue dodgerblue deepskyblue skyblue lightskyblue steelblue lightsteelblue lightblue powderblue paleturquoise darkturquoise mediumturquoise turquoise cyan lightcyan cadetblue mediumaquamarine aquamarine darkgreen darkolivegreen darkseagreen seagreen mediumseagreen lightseagreen palegreen springgreen lawngreen green chartreuse mediumspringgreen greenyellow limegreen yellowgreen forestgreen olivedrab darkkhaki khaki palegoldenrod lightgoldenrodyellow lightyellow yellow gold lightgoldenrod goldenrod darkgoldenrod rosybrown indianred saddlebrown sienna peru burlywood beige wheat sandybrown tan chocolate firebrick brown darksalmon salmon lightsalmon orange darkorange coral lightcoral tomato orangered red hotpink deeppink pink lightpink palevioletred maroon mediumvioletred violetred magenta violet plum orchid mediumorchid darkorchid darkviolet blueviolet purple mediumpurple