GUIDO Switches
Overview
Guido switches are used to modify the default behaviour of the Guido object that they are applied to. Most switches are common to all objects or are common to either widgets or containers. The reference below describes these common switches. Switches that are specific to a particular Guido object are described in the reference for that object.
Switches Common to All Guido Objects
The following Guido switches are common to most of the available Guido objects.
| -action actionType command | The -action switch is an advanced option that is used
to set an action command/procedure to respond to a number of possible
action types. See the reference on Guido action
events and callbacks for further information and examples.
-action initial {[setupForm]}
-action valueChanged {[updateRangeValue]}
|
| -dependency expression | The -dependency switch is an advanced option that
is used to set a relationship between two objects on a form. A dependency
makes one object (either a widget or a container) dependent upon the value
of another widget on the form. The dependency takes the form of a boolean
expression. When the expression evaluates to false the object will either
appear greyed out or invisible on the form. See the reference on Guido
action events and callbacks for further information and examples.
-dependency {"[$plotNow getCurrentValue]" == "yes"}
-dependency {"[$intersectByDTM getCurrentValue]" == "true"}
|
| -disable_action actionType | The disable_action switch is an advanced option that
is used to turn a selected action event type off for an object. See the
reference on Guido action events and callbacks
for further information and examples.
-disable_action focusGained -disable_action valueChanged |
| -enable_action actionType | The -enable_action switch is an advanced option that
is used to turn a selected action event type back on for an object. See
the reference on Guido action events and callbacks
for further information and examples.
-enable_action focusGained -enable_action valueChanged |
| -remove_action actionType | The -remove_action switch is an advanced option that
is used to remove the handling of a particular action event on an object.
See the reference on Guido action events and
callbacks for further information and examples.
-remove_action focusGained -remove_action valueChanged |
| -font_style bold|italic|plain | The -font_style switch allows you to change the default
plain style for font rendering to either bold or italics.
Note that it is only the object label that will have the font style changed,
for example when applied to a GuidoField the text within a GuidoField
remains the same but the fields' label will have an altered text style.
-font_style bold -font_style italic |
| -height size | The -height switch allows you to change the default
height allocated on the form for an object. Height is measured by the
normal height of a text character. Height can/may be specified to assist
with the layout of objects on the form or to allocate size to containers
such as a GuidoScrollPane.
-height 1 -height 5 |
| -icon pathname | The -icon switch allows you to insert a gif/jpg/png
image icon into the form. Note that although this switch maybe applied
to most Guido objects it only has relevance to GuidoButtons and GuidoLabels.
The pathname is relative to the standard SSI_RESOURCES: logical (normally
set to /ssi_V?.??/share/resource/)
-icon my_icons/do_my_job.gif -icon icons/next_section.gif |
| -label text | The -label switch allows you to specify a text label
for any GuidoObject. The placement of the label depends upon the current
layout manager (Layout Managers)
but will normally be positioned to the left of the object.
For container objects like a GuidoPanel or GuidoTabbedPane by also using the -border switch in conjunction with -label, the label can actually become part of the containers border as opposed to a separate label. For a GuidoForm the label is always set into the title bar of the form. -label "Enter the location" -label "Plot now ?" |
| -next_focus fieldname | The -next_focus switch allows you to specify the next
object that is to gain focus on the form when focus leaves the object
that the switch is set on. Due to Layout
Managers or the logistics of your form, the focus order (also called
the tab order) may not be what you expect or want. With this switch you
can alter the order by specifying the next object to get focus by name.
-next_focus objectRange -next_focus plotScale |
| -position North|South|East|West|Center | The -position switch may be applied to all Guido objects
but it is ignored unless the object position on the form is under control
of the BorderLayout Manager. The
position switch indicates which section of the layout to place this object
into. It may only be North, South, East, West, or Center.
-position East -position Center |
| -tip text | The -tip switch allows you to insert field help for
any GuidoObject. Once set the field help behaves the same as it does for
standard software forms. Note that if the -tip switch is applied
to the GudioForm object then it will appear as form help. Also
consider using the -help_url switch described in GuidoForm
to provide comprehensive help on your script in the form of a html page
or pdf document.
-tip "Just some info to help the user" -tip "Enter the DTM name for sectioning" |
| -validation expression | The -validation switch is an advanced option that
is used to set a user defined validation for the Guido object which is
normally a widget. The expression is either a boolean expression
or a user defined procedure that must return a true or false value. See
the reference on Guido action events and callbacks
for further information and examples.
-validation {[$sSec getCurrentValue] < [$lSec getCurrentValue]}
-validation {[validateBoundryInputs]}
|
| -visible true|false | The -visible switch can be used to make a Guido object
invisible on the form. This is usually used in advanced form processing
to either hide fields until a certain event occurs or to provide storage
for hidden variables that are used by form procedures. See the reference
on Guido action events and callbacks for
further information and examples.
-visible true -visible false |
| -width size | The -width switch allows you to change the default
width allocated on the form for an object. Width is measured by width
of the M character as it is the widest in the alphabet. Width is
usually specified for widgets such as fields and browser fields to provide
a reasonable input region. Width may also be specified to assist with
the layout of objects on the form or to allocate size to containers such
as a GuidoScrollPane.
-width 25 -width 5 |
Switches Common to Guido Widgets
The following Guido switches are common to most Guido widgets.
| -default value | The -default switch is used to set a static default
value into a Guido widget. It can be used to set a default value for any
type of widget but care should be taken with objects like combo boxes
and button groups where there is a finite set of allowed values that the
default matches one of them.
-default "pickup" -default "A3" |
| -file_access exist|read|write | The -file_access switch is a data validation switch
that causes the form processing system to check for file access before
applying the form. The possible file access settings are:
This switch would normally be used on a GuidoFileBrowserField but can be applied to fields, combo boxes or any browser widget. -file_access exist -file_access read -file_access write |
| -format formatSpecifier | The -format switch is a data validation switch that
causes the form processing system to check that a particular value is
valid for the specified format. If the value does not validate then the
form will not apply. There are a number of formats that can be used:
-format integer -format double -format range |
| -high_bound value | The -high_bound switch is a data validation switch
that allows you to specify the upper limit of the value entered. You must
also specify a -format formatType so that the system knows what
type of data to check. Usually -high_bound is used with number
format types like double and integer but it can also be used for the other
types.
-high_bound 0.999 -high_bound 100 -high_bound "Z" When used in conjunction with the -low_bound switch it allows you to specify a valid range of values for the input field. |
| -low_bound value | The -low_bound switch is a data validation switch
that allows you to specify the lower limit of the value entered. You must
also specify a -format formatType so that the system knows what
type of data to check. Usually -low_bound is used with number format
types like double and integer but it can also be used for the other types.
-low_bound 0.001 -low_bound 0 -low_bound "A" When used in conjunction with the -high_bound switch it allows you to specify a valid range of values for the input field. |
| -input true|false | The -input switch allows you to specify if a widget
can gain keyboard focus for input. By default all widgets are set to -input
true. The -input false setting allows you to create a display
only field to convey information to the script user, for example the length
of an axis line, the extents of the data layer, etc
-input true -input false |
| -max_length value | The -max_length switch allows you to specify the maximum
number of characters that can be entered into a field. Normally there
is no need to restricted input to a certain number of characters but in
some instances you may want to ensure input is of a particular length.
-max_length 1 -max_length 50 |
| -null true|false | The -null switch is a data validation switch that
allows you to specify whether the input field can be left with no value.
It can only be applied to fields and browser widgets. A widget that is
set to -null false will not allow the form to apply unless a value
is entered. The default setting is -null true which allows the
form to apply if no value is entered into the input field.
An important behaviour to note is that if the input field allows no value to be entered (which is the default) then even if you have set other validation switches, such as -format integer, the validation will not take place unless a value is entered. -null false -null true |
| -translate upper|lower|mixed | The -translate switch sets any characters typed from
the keyboard to be converted to the nominated case, being either upper
case, lower case, or mixed (no translation). The default is for mixed
case input meaning there is no case conversion. The conversion to the
nominated case happens as characters are typed so that they appear in
the field in the correct case.
-translate upper -translate lower -translate mixed |
| -shared_list GuidoWidgetName | The -shared_list switch is used when two or more combo
boxes or browsers need to share the same list of values in memory. It
is used to save memory space and to increase performance when you have
extremely large lists of values where two or more combo boxes or browsers
on the form have the same list of values. It is more typically used with
a GuidoDatabaseColumnBrowser which
is a special implementation of a combo box that allows for all values
in a database column to be inserted into a list.
To share the list the second and subsequent combo boxes or browsers specify the name of the widget that has the original list. The example below assumes the original combo box was called firstStation -shared_list firstStation |
| -sorted_list true|false | The -sorted_list switch allows you to specify whether
the list of values is sorted in alphabetical order to help with the combo
boxes / browsers list searching techniques. By default the list is assumed
to be unsorted and a linear search technique is used. When you have extremely
large lists that are sorted, by specifying that the list is sorted you
direct the combo box / browser to use a binary search technique that is
magnitudes faster than the linear method.
The sorted_list switch is more typically used with a GuidoDatabaseColumnBrowser which is a special implementation of a combo box that allows for all values in a database column to be inserted into a list. See example 4 below for more information and also GuidoDatabaseColumnBrowser for further examples -sorted_list truePlease note the list searching facility is only available for exclusive combo boxes and browsers. |
Switches Common to Guido Containers
The following Guido switches are common to most Guido containers.
| -border borderStyle includeLabel | The -border switch allows you to draw a border around
the container object. The borderStyle determines how the border
appears on the form and can be one of the following:
-border etched true -border loweredBevel false |
| -border_title_alignment left|center|right | The -border_title_alignment switch allows you to place
the border title (label) on the left side, centre, or right side of the
border. The default is to place the title to the left side of the border.
-border_title_alignment left -border_title_alignment center -border_title_alignment right |
| -border_title_position position | The -border_title_position switch allows you control
over where the title is positioned relative to the actual border lines.
The options are:
-border_title_position above_top -border_title_position below_top -border_title_position bottom |
See Also
Guido
GuidoForm
GuidoPanel
Layout
Managers
Common guido switches