LLOOP TCL-TK Forms

This page describes the TCL/TK entry forms generated by LLOOP and explains how to use them.

Overview

TCL/TK forms can be generated from the definitions of command line options in gsp files.

The generated forms can also be used as general-purpose data forms not only intended for entering option values, provided that data are represented and specified the same way as described below for command line options.

These forms allow to enter option values through graphical interface. They offer the following ergonomic features:

Entry fields tailored to the types of value to enter. Eg. when the value is a file path, there will be a button for browsing the file system. Eg. when there is no value, it is a check box.
Forms can be organised in cascade, by defining subsets of options within a set of options
Forms can feature different ergonomic patterns with regard to look & feeland entry control
Undo (CTRL-Z), with full history and awareness of hierachical relationship between forms
Contextual help
Cross-platform: forms are implemented in the cross-platform TCL/TK language

The forms are supported by a set of functions (TCL) which allow seamless integration with the final application, among which:

A function that builds the command line from the entered values
A function that saves the entered values into a file
A function that fills the form from a file

The generated forms rely on an extension of the TCL standard functions which are defined in TCL files to be used along the generated code. Further information can be found at the end of this page.

Cascade Forms

A child form is created for each option subset defined within another set of options. The child form is opened through a button which replaces a conventional entry field.

There is no limit with regard to the hierarchy level child forms can be defined in, and there can be a random number of child forms at a given level.

The GSP Language Reference explains how to create option sets and option subsets.

Entry Fields

The following table describes the types of entry field generated according to the passed option values. Most time, a type of entry field is tied to a predefined token of the standard GSP library:

Option value / Token	Type of Entry
text	Multi-line Entry
existingfile, existingdir, dir, forcedir, existingimage	Line entry when option can be specified once only. Multi-line entry when option can be specified several times. Push button to browse file or directory.
uint, int	Spinbox entry. Values are separated with comas when option can be specified several times.
Option with no value	Check box
Option with value (default)	Line entry Values are separated with comas when option can be specified several times.
Option Set	Push button

Visual Ergonomic Patterns

Outline

It is possible to configure the look & feel of the form to match different representation and entry philosophy:

Standard forms
Panel forms

Standard Forms

These forms have the following characteristics:

Grey background
At the left, the labels of the entry fields. Grey background, Black foreground
At the right, the entry fields. White background, Black foreground
Contextual help shown/hidden when clicking on entry field label

Example:

Note: the function that creates the window and the OK, Cancel buttons is not generated, but generic and predefined in the required TCL extension.

Panel Forms

These forms have the following characteristics:

Panel look & feel
At the left, the labels of the entry fields. White background, Black foreground
At the right, the entry fields. Yellow background, Black foreground
Highlighting of current selected field, for both label and field
Contextual help forwarded to a callback function on field selection

Example:

Generic Predefined Functions

The following table describes useful generic TCL functions which are predefined in the required TCL extension:

Function Purpose

proc Application_subControlPanel { parent panelName panelTitle {createOnly 0}} Creates a window with a standard form, and a OK and Cancel buttons. The Cancel button allows to cancel all changes, inclusive all sub-forms.
parent gives the parent widget.
panelName gives the namespace where the form is defined: it is the name of the gsp file without extension.
panelTitle gives the title for the form window.
createOnly used internal to create the windows at start-up. Shall not be specified.

Generated Forms Functions

The TCL code generated from a gsp file defines its own TCL namespace which is the same as the C++ namespace defined for the generated parse code.

The following table describes the generated TCL functions, defined in that namespace, which allow to create the TK forms and manage the entry data:

Function	Purpose
`proc namespace::ControlPanel { panel }`	Creates a panel form taking `panel` as parent widget.
`proc namespace::SimpleControlPanel { parent onModificationCallbackProc onHelpCallbackProc }`	Same as `ControlPanel`, and additionally: - shows the titles `Property` and `Values` for the labels and the entry fields - when a field is modified, executes the `onModificationCallbackProc` callback function, passing a boolean telling whether the value changed - when a field is selected, executes the `onHelpCallbackProc` callback function, passing the help text to the function call
`proc namespace::MDIControlPanel { parent onModificationCallbackProc onHelpCallbackProc }`	Same as `SimpleControlPanel`, and additionally: - puts the panel into an incrusted MDI window. The title of the window is `Option Values`
`proc namespace::ControlPanel_save { fd }`	Saves the entered field values (inclusive all those of sub-forms) using the `fd` file descriptor. `fd` must have been opened with the tcl `open` function. The values are saved as TCL code.
`proc namespace::ControlPanel_saveToOptionFile { file {append 0}}`	Saves the entered field values (inclusive all those of sub-forms) into the specified file `file`. `append` tells whether to append the values the files or to overwrite it. Calls internally `ControlPanel_save`.
`proc namespace::ControlPanel_readFromOptionFile { file }`	Reads the field values (inclusive all those of sub-forms) from the specified file `file`. Updates the form accordingly.
`proc namespace::ControlPanel_getCommandLine { executablePath }`	Builds the command line. This line starts with the passed executable name `executablePath` followed by all entry field values and the appropriate option switches.
`proc namespace::ControlPanel_isModified { }`	Tells whether the form or any of its sub-forms is modified.
`proc namespace::ControlPanel_resetOptionValues { }`	Empties all entry fields (inclusive all those of sub-forms).
`proc namespace::ControlPanel_backupCurrentOptionValues { }`	Adds the entry values into the change history.
`proc namespace::ControlPanel_undoOptionValues { }`	Undo last change by taking the last value added to the change history with `ControlPanel_backupCurrentOptionValues`.
`proc namespace::ControlPanel_backupOptionValues { }`	Make a backup of current value. The new backup overwrites the previous backup done with this function.
`proc namespace::ControlPanel_restoreOptionValues { }`	Restores a backup make with `ControlPanel_backupOptionValues`

The generated forms and the generic GFE applications rely on a set of functions which are defined in the TCL files listed below. All sources are licensed under the GNU license terms and available below the gfe_source directory of the release package.

apptools.tcl: functions for managing generic application
app__ControlPanel.tcl: entry panel for configuring generic application
widgettools.tcl: advanced widget functions
projecttools.tcl: generic functions for managing documents/projects within an application

It is possible to create Graphical Front End Applications (GFE) for controlling command line programs, without any programming. A GFE is created based on:

a GUI application template which has to be configured the first time it is run

the forms generated from the option specification for the command line program

The TCL source file gfe.tcl defines the set of required functions to set up generic GUI applications. It requires the TCL extensions mentioned above.

The TCL source file gfe_cfg.tcl is a configuration file created and managed by the generic application itself. It contains all the configuration parameters for the application, among which user-written functions used to customise the application.

All TCL sources can be integrated into a single executable file using FreeWrap v6.1.