GRIDPLUS2: Widget

GRIDPLUS2 - Widget Grid

Home

Reference

Manpage

Examples

Download

License

Contact

GRIDPLUS Widget Grid

In order to simplify creation of screen layouts, GRIDPLUS provides a GRIDPLUS widget command mode.

This uses a simple syntax to create a grid of widgets. The syntax is closely based on the GRIDPLUS Grid.

GRIDPLUS Widget Specific Item Options/Functionality

See GRIDPLUS Widget Grid for a full list of item options/functionality.

&type: The type of the widget (Example: &e). Acceptable values are b (Button), c (Checkbutton), d (Dropdown "combobox"), e (Entry), l (Link), m (Menubutton), r (Radiobutton), w (Embedded Widget grid), wc (Embedded Checkbutton grid), wd (Embedded Dropdown grid), we (Embedded Entry grid), wl (Embedded Link grid), wm (Embedded Menubutton grid), wr (Embedded Radiobutton grid).
&type:style/optionset: As above but with specified style/optionset.
.name: The name of the widget (Example: .b1). If the widget type is an embedded grid (&w, &wb etc) the widget name is optional. In this case, if no name is specified, a system generated name name based on the name of the parent grid with a numeric suffix is used. This is intended to be used where it is not neccessary to reference the widgets in the grid. A system generated name is also used if the widget name "." is used. This shorthand is intended when a anchor suffix is required. For example; ".:e" to use a system generated name and have the embedded grid anchored to the east (right hand) side of its column.
.proc=parameter: The name of the widget. This is an optional way to define a widget name for buttons. Using the example: .myproc=myparameter, the widget will be called ".myproc=myparameter", the procedure called when the button is pressed will be "myproc" to which will be passed a parameter, in this case "myparameter".
:icon: The name of the icon to be used for button (button) -or node (tree) (Example: :navback16). The icon name can also be null (button), in which case the icon specified by the -icon option is used.
%group: The name of the group to which widget belongs (Example: %mygroup1).
<: Create widget with disabled state. Overrides -state option.
<group: Specifies that widgets belonging to group will have state set to "disabled" when the widget content is modified.
>: Create widget with normal state. Overrides -state option.
>group: Specifies that widgets belonging to group will have state set to "normal" when the widget content is modified.
@name: Insert specfied grid/layout/widget (Example: @myoptions).
?helptext: Specifies text to be used for button pop-up/balloon help (Example: ?Print). If the text contains spaces double quotes must be used (Example: "?Exit Application").
!name: Specifies name of validation to be used for entry (Example: !int) -or- When "!" is used alone this indicates that entry validations are to be perfomed (for the window containing the button/link/menu) prior to evaluating the callback.
|: Specifies that a vertical bar separator be created.
=: Specifies that a horizontal bar separator be created.
+value: Specifies that the widget should be created in selected mode (checkbutton/radiobutton) -or- have focus (entry) -or- the dropdown list should be set to the specified list (dropdown) -or- a "bullet" should be displayed (link). The use of value is for dropdowns where the dropdown list should be set to the specified list with the widget value set to the first item in the list -and- radiobuttons where it specifies the value of the radiobutton Grid when this radiobutton is selected.
-value: Specifies that the widget should be created in deselected mode (checkbutton/radiobutton), a separator line is displayed (menu) -or- widget is indented (link). The use of value is for radiobuttons only an dspecifies the value of the radiobutton Grid when this radiobutton is selected.
*: Specifies that the widget should display "*" for each character entered (entry).
~command: Specifies that a command is invoked when the enter key is pressed while the widget has focus (entry), that a command is invoked when a checkbutton/radiobutton is selected -or- that a command is invoked when a list item is selected (dropdown). The command name is optional. If not specified command name is based on the name of widget. This option may also be used to specify the name of the command to be invoked for buttons and menu items.
integer: Specifies a positive integer which overrides the default width for the widget.
text: Specifies text to be used as widget label. The text may also have an optional colon (":") delimited sticky indicator: n, s, e, w (Default) or c (Centre) (Example: "First Name:e").

Notes:

If the label text begins with "^" the label will be displayed with bold text.
Within a label the string "<n>" is used to specify a line-break.

Example

This section contains an example which illustrates the main GRIDPLUS widget command mode features.

The following example assumes that the reader is familiar with the contents of the Grid/Layout page. Information given on that page will not be duplicated here.

Note: The example assumes that the GRIDPLUS package has already been "required" and the commands imported.

Widget Example 1

Window:

Source Code:

gridplus widget .mygrid1 -title "My Grid 1" {
  {&b "Label1" .1} {&e "Label2" .2}
  {&e "Label3" .3} {&d "Label4" .4}
  {&d "Label5" .5} {&b "Label6" .6}
}

gridplus widget .mygrid2 -title "My Grid 2" {
  {&b .1 "Label1"}
  {&c .2 "Label2"}
  {&l .3 "Label3"}
  {&m .4 "Label4"}
}

gridplus widget .mygrid3 -widget radiobutton -title "My Grid 3" {
  {}         {"Label A:c"}  {"Label B:c"}
  {"Label1"} {.1:c +myval1} {&c .5:c}
  {"Label2"} {.2:c -myval2} {&c .6:c}
  {"Label3"} {.3:c -myval3} {&c .7:c}
  {"Label4"} {.4:c -myval4} {&c .8:c}
}

gridplus layout .main -wtitle "Widget Example" {
   .mygrid1:ew  -
   .mygrid2:ns  .mygrid3:ew
}

pack .main

Comments:

When using the GRIDPLUS widget command mode the "label" defines the text that will appear as a label to the associated widget. The cell item begining with a dot is the widget ID. The widgets are created with names based on the name of the containing Grid and the widget ID. By default label widgets will be created.

For example: The for the ".mygrid1" cell defined by "{&e "Label2" .2}" an entry widget is created with the name ".mygrid1,2". Please note that the widget name does contain a comma - this is not a misprint!!

In ".mygrid2" the widget IDs are to the left of the label text. Where appropriate (checkbutton, entry, radiobutton) - This will create widgets which are to the left of the label text.

In ".mygrid3" the -widget option is used to set the default widget type to "radiobutton". This has exactly the same effect as creating a radiobutton grid. Some of the cells simply contain labels. The widgets under "Label A", as no widget type is specified, will be created as radiobuttons. The widgets under "Label B" will be created as checkbuttons as the widget type "&c" is specified.

The column labels ("Label A" and "Label B"), and the widgets in those columns, have a :c suffix - This causes the labels/widgets to be centred in the containing cell.

Widget Example 2

Window:

Source Code:

gridplus widget .person -wtitle "Widget Example" {
   {&d "Title"       .title "+Mr Mrs Miss Ms" 4}
   {&e "First Name " .first_name 20}
   {&e "Last Name"   .last_name 20}
   {{&wr {.male "Male" +male} {.female "Female" -female}} "Gender" .gender}
   =
   {{&wb {"Save" .save} {"Exit" .exit}} .action:ew}
}

pack .person

Comments:

This example uses "&wr" and "&wb" to include radiobutton and button grids into the ".person" widget grid. This method is used because it is required that these elements have different column layouts and alignments.

As with other widgets, the widget grid type is specfied when the first element in a column specification begins with "&". For a radiobutton widget grid this will be "&wr". For a widget grid type, the whole of the element begining with "&wr" is considered to identify the widget type. In the above example this is "{&wr {.male "Male" +male} {.female "Female" -female}}". The text "Gender" will be used as a label for this widget grid. The grid will be named ".gender". As the label appears to the left of the widget name, the label will be to the left of the widget. This is the equivalent embedding a grid created thus:-

gridplus radiobutton .gender {
  {.male "Male" +male} {.female "Female" -female}
}

For the widget grid type, the widget name is actually optional. By default a name will be assigned based on that of the parent grid with an integer suffix added (incremented for each embedded widget grid). For example: If the above example did not specify the widget name ".gender", this widget grid will have been assigned the name ".person-1". For most purposes it makes sense to specify a name explicitly as this allows more sensible widget names to be used. But where the embedded widget grid simply contains text -or- is used as a container for other widgets the automatic default name will probably be acceptable.

The "=" column item will create a horizontal line.

Two buttons are created using an embedded button grid ("{&wb {"Save" .save} {"Exit" .exit}}"). The ".action:ew" item specifies that the embedded button grid will be called ".action" and will be anchored to the east and west of the containing grid cell (":ew").

Reading and Setting GRIDPLUS Entry Values

The values of the GRIDPLUS widgets are stored in a global array with a null name.

For Example:

global {}