Guido Overview
The Guido (Graphical user interface design objects) toolkit provides you with a rich set of commands to interact with the user and retrieve input for use in your scripts. The Guido commands are Surpac extensions to the Tcl interpreter but they are run on the client process (the user interface) rather than the server process as are the normal Scl extension commands.
The various Guido tools are provided so you can write forms to interact with the user in order to get information to use in your script. The base Guido object is the GuidoForm that may contain a number of Guido widget and container objects. A Guido container is an object that contains other Guido objects that may be containers or widgets. A container object is used to organise the layout and appearance of your form. A Guido widget is an object that is used to retrieve information from a user. All Guido objects accept switches that are used to modify the default behaviour and/or appearance of the object.
Creating and Activating a Guido Form
Surpac and related GEOVIA Software products use a client / server architecture where the main data processing functions occur on the server and the user interface elements such as graphics, menus, toolbars, forms, etc take place on the client. A Tcl/Scl script when invoked is run on the server process. If a script wishes to interact with a user to collect inputs it makes use of the Guido toolkit to communicate to the client process to display forms.
All Guido commands are in fact dispatched to the client and processed in a separate Tcl interpreter there. In order for a Tcl/Scl script to dispatch a Guido form to the client, it must read the form definition (text) to create a Guido form and then dispatch and run the form on the client. The commands below describe how to define, create, and run a form.
| GuidoForm | SclCreateGuidoForm | SclRun |
| Setting form default values | Retrieving values from a form |
Basic Guido Widgets
Guido commands are classified as either widgets or containers. A Guido container is an object that ‘contains’ other Guido objects which may be widgets or subsequent containers. A container object is used to organise the layout and appearance of your form. A Guido widget is an object that is used to retrieve information from a user.
There are several Guido widgets that you can use in your forms. The basic widgets below are the ones you will normally use.
| GuidoButton | GuidoButtonGroupPanel | GuidoCheckBox | GuidoComboBox | GuidoField |
| GuidoLabel | GuidoPasswordField | GuidoRadioButton |
Specialised Guido Browsers
Guido browser commands are similar to combo boxes except that they provide access to a special purpose browser (chooser) popup via the triangle selection icon. The most common example is a ‘File Browser’ popup that allows a filename to be chosen by navigating folders (directories) on your disk or network. Other specialised Guido browsers are listed below.
Advanced Guido Widgets
A number of advanced Guido commands are available to be used for particular purposes where the display of information on a form may require a more intricate widget. These widgets are more complex than the basic widgets and generally require greater setup and implementation of call-back procedures.
| GuidoChart | GuidoFileChooser | GuidoHtmlPane | GuidoSlider | GuidoTextArea |
| GuidoToggleButton | GuidoTree | GuidoTreeBranch | GuidoTreeLeaf |
Guido Containers
Guido containers are used to organise the positioning of widgets and subsequent containers on your form. Some Guido containers have special purpose layout features such as tabs on a tabbed pane, or sliders on a scroll pane. The most common container you will use is a panel on which you can apply different layout managers to produce very structured form layouts.
| GuidoFiller | GuidoForm | GuidoPanel | GuidoScrollPane | GuidoSplitPane |
| GuidoTabbedPane | GuidoTable | Layout Managers |
Guido Menus and Toolbars
Guido provides a number of objects for the creation of menus and toolbars. Usually you will use the Menu/Toolbar editor for this function but these items can be hand coded using the following commands
| GuidoMenuItem | GuidoCheckBoxMenuItem | GuidoRadioButtonMenuItem | GuidoButtonGroup | GuidoSeparator |
| GuidoMenu | GuidoPopupMenu | GuidoMenuBar |
Guido Utility Functions
A number of miscellaneous Guido commands are provided to mainly assist with communication between the client and server process.
| GuidoFunction | GuidoMessage | GuidoResource | GuidoScript | GuidoSSIOption |
Guido Switches
A Guido switch is an option that can be applied to any Guido command to modify its default behaviour and/or appearance on your form. Each Guido command that you code will normally have a number of switches applied to it. For example the label switch is used to set a text label for any Guido object and the width switch is used to set the display size of an object on a form.
Most switches are common to all Guido objects but certain Guido commands will have switches that are only of relevance to that command. These switches are discussed in the relevant commands.
Switches common to all Guido Objects
| -icon | -label | -font_style | -width | -height |
| -hidden | -next_focus | -position | -tip | -visible |
| -action | -disable_action | -enable_action | -remove_action | -dependency |
| -validation |
Switches common to most Guido Widgets
| -file_access | -format | -high_bound | -low_bound | -input |
| -max_length | -null | -translate | -shared_list | -sorted_list |
| -default |
Switches common to most Guido Containers
| -border | -border_title_alignment | -border_title_position |
Guido Events and Callbacks
The Guido processing engine allows for certain events to be caught and registered callback procedures to be invoked when that event occurs while the form is displayed on the client process. Coding of callback procedures requires knowledge of Tcl procedures and is intended for advanced uses only.
There are three types of Guido callbacks that can be registered. Most call-backs will require the use of Guido object methods to access and set data to / from Guido widgets and containers.
| Overview | Action Call-backs | Dependency Call-backs | Validation Call-backs | Object Methods |