| |
|
|
|
2 USER'S GUIDE
This chapter describes how to use the panel editor which is a VLT tool to build VLT graphical user interfaces.
2.1 OVERVIEW
The VLT User interface is actually implemented into two parts:
· The Programmatic Interface, consisting of a library of general purpose procedures provided by the panel editor and a set of TK widget classes.
The TK widget classes are used by the panel editor to build user interfaces. Each widget is implemented as a incr Tcl class providing the user public configuration variables and methods to interact with the widget (for example to add element to a uifListBox).
· The Panel Editor, which is a tool to help the user design and create user interfaces. This tool allows the user to position widgets within the panel (from now on this term is used to indicate the empty working frame where to place the widget to create a user interface) and configure them.
These are GUIs which are used to control telescopes and instrumentation and should be designed using only the features provided by the panel editor: in particular the use of TCL procedures changing the panel layout should be avoided.
These are GUIs for off-line tools which perform specific tasks to assist the SW developer and are typically developed inside the SW group, such as: errEditor, ccsei, etc...
For this kind of GUIs a higher level of customization is allowed and the Panel Editor provides means to customize the behaviour of the utility.
2.1.1 The Main Panel
The panel editor utility is invoked by the command
The following windows are displayed:
· The so called "working window" where the user can add widgets and whose contents can be saved to generate a new panel.
The panel editor supports a set of basic widgets available through the "Widget" window and they are grouped into three categories:
· Basic Widgets - These are the basic widget used by the panel editor: these widgets differ from the standard Tk widgets because they have a reduced number of widget configuration options and implement additional methods in order to fulfil the VLT Look & Feel.
· Common Widgets - These widgets are typically directly implemented in itk and provide specific `high-level' funtionalities.
Who has developed a widget of common interest can submit the new widgets to the responsible of the VLT User Interface to include them into the library.
· Graphic Widgets - These are not real widgets but they are added to the canvas as "graphic elements": for the time being only the text element is supported.
Widget selection and configuration is done using the mouse, hereafter there is a short description of all operations available during the editing of the panel (see paragraph 5.2.6 on page 96 for more details).
· Set the widget insertion position - Position the cursor where you want the widget to appear and click <B1>: from now on all widgets will appear in this position, unless the previous sequence of commands is repeated.
· Create a new widget - Go with cursor on the list shown by the window "widgets" and click on the selected widget: the widget will appear in the insertion position with a standard configuration.
· Configure a widget - Go with cursor on the widget and click <B3>: the configuration panel for that widget will appear: from this panel the user can also delete the widget or move it to a different location by changing X and Y coordinates.
· Copy a widget - Creates an instance of the selected widget with the same options setup but different name.
2.1.2 Structure of the Working Window
The working window contains the panel you are building and it is made of several components, as shown in the picture below:
You can only work on one panel at a time.
The menu bar is placed at the top of the panel. In its initial configuration it contains the following standard menus "File" "Std. Options" and "Help": the user can configure it by moving the cursor on it and click <B3>
Is the area where the user can freely place all the widgets: the size of the panel can only be modified during editing.
The Command Feedback Window allows the user to see the replies got after sending commands to other processes by using the panSendCommand procedure. For each reply it shows:
The short help widget is placed at the bottom of the panel. When the cursor moves onto a widgets it provides the user on line information on the widget functionality.
- the "Database Re-connection button" which allows the user to force an update of all widgets connected to the `control system' database and it also re-attach events to the database attributes linked to the widgets in the panel.
Action buttons, appear automatically in the panel's action area and they can be moved to the final position using the mouse middle-button (as described above for the other widgets).
2.1.3 Structure of the MenuBar
The menu bar is placed at the top of the panel and can be inserted to or removed from the panel by clicking the "Menu bar" option in the "Std. Comp." menu of the main panel.
In its initial configuration it contains two menus called "File" and "Help": the user can configure it by moving the cursor on it and click the `mouse-third-button'.
The menu Bar is formed by a row of widgets called "menuButtons" which give access to the underlying menu structure.
When the menu bar appears in the panel, it can be configured by clicking on it with the mouse right-button, and the following configuration panel appear
Each menu Button or cascade menu can contain several entries which are referenced within the menu with their position. MenuButtons and cascade menus can also be addressed by the full widget path.
To know more on how to create and configure the menu bar, see the dedicated paragraph 5.6 in the reference section
2.1.4 EXAMPLE: Enable/Disable Menu entries
A set of specific procedures is available when the GUI application needs to perform some operations on the menu bar such as, for example, to enable/disable entries according to the current GUI configuration.
The procedures perform the following operations
- Get information of a menu entry: this will return the full widget name of the menu
containing the entry, the type of entry and its position in the menu.
Taking as panel reference the one shown in the above picture, some example of use for such procedures are the followings:
Get full Name of "MenuButton1"
Disable and enable menu Button "MenuButton1"
Get information on the menu entry with label "cmd1" under the menu Button "MenuButton1"
The returned values is a list specifying: full widget name of the menu containing the entry, the type of entry and its position in the menu.
Get information on the menu entry with label "Menu 3" under the menu Button "MenuButton1"
Disable and enable checkButton "checkButton2" under the menu Button "MenuButton1"
2.1.5 Getting Started
This is a simple example to show how to create and configure a widget, save a panel and re-load again its definition
The table below describes what the user should do to create the panel and properly configure the widgets.
Once the panel has been created the tool allows the user to save its definition and run it again as stand alone process.
2.1.6 How To Run a Panel
In the VLT environment a panel is seen as normal executable and is created through the VLT Makefile as specified in paragraph 2.8 on page 63.
In the previous example the panel has been save with the name example1.pan and the VLT makefile will produce an executable with the same name but without the".pan" extension: to run it independently just type:
2.1.7 Run Time Parameters
Panels are TCL scripts that can be run from a shell, just by invoking the associated command line, for example:
fileName "ccdName=newName" "imageDir=cstest:image.imageDirectory"The run-time parameters are passed with the following format: "<varName>=<newValue>"
- <varName> should specify the name of a global variable, typically one of those defined by the user in the procedure panUsrGlobalData: it is recommended to always give a default value to the variables passed as run-time parameters to avoid the presence of `undefined' variables.
- <newValue> is the run-time values assigned to <varName>. This value overrides the one previously assigned to <varName>.
There are some built-in parameters, controlling the panel functionality, as specified in the following table:
2.1.8 Miscellaneous
This section contains the description of other editing functionalities contained in the main panel.
Note that this name only gives the "title" to the panel and it is not the name of the file where the panel is stored.
Display the grid by choosing the "Grid" option. A grid is displayed to help you place the widgets on the working panel.
Using the resize borders handles in the external frame of the panel window, resize the panel to the actual size you want. Remind that panels are not resizable at run time.
Set the panel final position on the screen
Move the panel in the position on the screen where it should appear and push "Set Panel Position". This position is recorded and used to position the panel on the screen whenever it is called: in this way the user is free to move the panel during editing.
Save your panel with the "Save as..." option from the File menu and give the file name either by typing a new name or by selecting an existing filename.
Call the panel editor again, click on the "Load" option from the File menu and select the panel file name to reload the panel into the Panel Editor. The panel is displayed in the panel window.
2.2 NAMING CONVENTIONS
2.2.1 Widget Names
The panel editor gives each widget a name, but this can be changed by the user during the configuration of the widget. This allows the user to write procedures which can directly interact with the widget.
Tk graphical user interfaces are organized as hierarchy of widgets, in the same way as the Unix file system is organized with the exception that the "." is used as separator instead of "/".
Therefore the creation or the configuration of one widget requires the full path name -e.g.- the output widget "ccdRemTime" added to a panel will have the full path set to "<fileName>.top.wdg.can.ccdRemTime".
The sections of the panel where the user can add/edit widgets are the menu bar, the application area and the action area.
The menu Bar is placed at the top of the panel and consists of a row of buttons (menuButtons) which can be organized in sub-menus (cascade menus). Each menu Button or cascade menu can contain several entries which are addressed within the menu with their position in the menu.
The Application Area and the Action Area
The Application Area and the Action Area are canvases whose names is stored in the global variable "cv" and "bcv", but the following procedure allows the user to get to the name of the two canvases:
the full name of the widget is formed by concatenating the name of the canvas containing the widget and the widget name and therefore the widget path is:
The panel editor assigns a name to each widget making sure that the name does not clash with one of another panel (this is very important in the case that several panels are run under the same Tcl interpreter), with the following format:
When the panel is saved the panel editor process the name of the widgets according to the following table
2.2.2 Widget Names within a uifClass
uifClass are widgets formed by a frame and a canvas inside a frame, therefore the full path name of a a widgets within a uifClass is:
The uifClass has a public variable containing the name of the parent widget
Example: if "myInstance" is the name of the uifClass contained in a panel and "myWidget" is the name of a widget within the class, the full widget name can be obtained as follows:
2.2.3 Variables Names
Widgets of the same panel can share the same parameter (or value) by specifying the same name in the configuration parameter `Variable': this parameter tells the widgets where to store or retrieve data.
The Tcl/Tk interpreter has a unique global data area and the panel editor uses some conventions in
order to avoid name clashing, therefore the user must be aware of some constraints on the syntax of
variable names.· In menu entries these variables are defined as "global" and they can be accessed as any other global variable. The user must explicitly define the variable associated to a menu entry with the name gvar(<variable name>) to connect the entry with another "normal" widget.
· For the widgets used in the application/action areas these variables are mapped into a global array gvar.
For example if a widget uses a variable name `pan:var:scal.i1', the data hold by that variable is actually stored in a global array as gvar(pan:var:scal.i1).
where <widgetName> is name of the widget automatically generated. This is formed using the current name of the panel and when the panel is saved it is updated according to the new name.
For portability reasons it is recommended to use the naming conventions defined by the VLT Programming Rules, in particular avoid to use the following characters "-", "_".
When the panel is saved all variables whose name has the format <fileName>-<whateverstring>
are updated according to the new name of the file.
2.2.4 Mapping of run-time data.
2.3 DATABASE INTERFACE
2.3.1 Basics
Widgets can be configured to read/write values from/to the database: those values are specified using the database symbolic address.
All configuration parameters which can access the database are followed by the "DB" checkButton which specifies that the parameter supplied by the user is a DB symbolic address.
If the user specifies a database address but does not set the corresponding `DB' checkButton, that parameter is regarded as a local variable.
The user can specify the so called "Current Working Point" (CWP) which sets the database searching path at the beginning of a specific database point -i.e.- symbolic addresses are resolved inside a database sub-tree.
By default the CWP is set to the database root point (":"), but the user can change it by specifying the new value in the panel command line.
2.3.2 Access to a remote database
Databases of remote environments are accessible by specifying the environment name at the beginning of the database attribute's name -e.g.- "@wte16:PARAMS:SCALARS.scalar_int32".
The name of the local environment is defined by the RTAPENV environment variable.
Each configuration panel provides a field used to specify the environment name and that name applies to all the DB parameters of the widget.
The fields can have the following values:
· Specific Environment, in this case the DB symbolic address is `fixed' and do not change according to the current CWP value. In the example above the `variable' final DB symbolic address will be "@wte67<relative>SCALARS.scalar_int32"
The string representing the variable name must start with a "$" and if the variable does not exist, the local environment is assigned to the variable.
The value assigned to the variable can also contain the CWP to be set fro the specific environment, for example, if userLcu is the name of the variable.
For example the value lte50:PARAMS defines the environment name to be "lte50" and the CWP for this environment is ":PARAMS".
The table below shows some possible setting of the environment name and what happens when calling the panel. This example assumes that the environment variable RTAPENV is set to wte671
2.3.3 EXAMPLE : Dynamic configuration of env. names
Sometime the name of the environment where to access the data from is not fixed but depends, for example, on some configuration parameters or must be formed from some database values.
As example the `active optics' GUI read the data from the LCU whose name depends on which telescope focus is used -e.g.- Nasmith A, Nasmith B, Cassegrein.
If you save the panel as it is, the widget will read the value from the `local' environment and taking as Current Working Point the one defined for the panel.
Next step now is to make the widget access the same attribute from another environment: this can be done in two ways
The value specifies both the new environment name and the current working point for that environment.
It is recommended to always define a default value in the <xxx>GlobalData procedure of the panel. While if the true environment name is derived from some database values, the definition must be included in the <xxx>InitData procedure.
2.3.4 Store database values
Values used in input widgets can be stored to the associated database attribute. On the other hand by design we have choose not to have this done automatically as the user modifies the widget value, but with a separate command.
Let's assume to create an input panel containing also the following parameters:
Sometimes there is the need to update (or refresh) the current value of the `input' widgets of the whole panel, therefore one can use the following procedure:
2.3.5 Update Panel Data
Two mechanisms are provided to keep the data displayed in the panel up to date:
Output widgets are kept up to date by reading the corresponding database values at the rate specified by variable "pollRate" (By default this value is set to 3 seconds): the polling rate can be specified in the command line giving the following instruction: "pollRate=<sec>"
If an error occurs during the updating of a DB attribute, a message appears on the screen and the polling of such element is disabled.
During the polling the panel check if any of the remote environments are active and polling of database attributes read from a not active environment is stopped.
Data associated to `output' widgets can be kept up to date by registering to the database event manager. The database reacts by sending to the registering application the database attribute new value.
· The condition for which the database should react, also called filter. The filter specifies conditions such as "at any write", "the new value is different from the old one", etc..
The panel editor (in EDITING Mode) issues a debugging message each time an event is enabled or disabled.
The panel editor provides a standard routine called "panEvtDbUpdate" which process the incoming events, a typical call of this procedure looks like:
where %A, %T, %D and %Q are special specifiers used to pass to the procedure well specific parameters. This routine is automatically set by clicking "Set Default Script".
The declaration of the event script can contain special characters which will be substituted at execution time to provide the handler procedure standard information.
The table shows the ones related to the database events (more details can be found in the man page of seq_evtAttach procedure)
BAD QUALITY : Data having the `bad quality' flag set are shown in the panel with a different background (a darker grey). The background is automatically set to the original value as soon as the data turn to be valid again.
A proper log is also generated whenever a change in the `Data Quality' occurs.
2.3.6 Template of procedure for database events
The panel editor provides a standard routine called "panEvtDbUpdate" which process the incoming database events and takes the following arguments:
Here follows the source code that can be used as template for the user to define his own event handle procedure.
proc panEvtDbUpdate { wdgName attr attrType data { quality "" } } {
global panDbSymbAddr panWidget i_type panDEBUG
if {[info exists panWidget($wdgName)] == 0} { return }
if {[cequal $attrType SCALAR]} {
panUpdateLocalVar $wdgName [lindex $panWidget($wdgName) $i_type] [lindex $data 2]
if { [cequal $quality ""] } { return }
if { ![cequal [lindex $quality 1] "OK"] } {
} elseif { [cequal $attrType VECTOR] } {
# extract attribute specification in the format :
# vector(r1:r2) r1,r2 element range
if {[regexp {\(([0-9a-zA-Z:,]+)\)} $panDbSymbAddr($wdgName) all rec]} {
if { ![panCheckOnRange $rec [lindex $data 0] [lindex $data 1] ]} {
.... Read the current database value
panUpdateLocalVar $wdgName [lindex $panWidget($wdgName) $i_type] $newValue
} elseif { [cequal $attrType TABLE] } {
# extract attribute specification in the format :
# table(r1:r2,f1:f2) r1,r2 record range f1,f2 field range
.... Read the current database value
panUpdateLocalVar $wdgName [lindex $panWidget($wdgName) $i_type] $newValue
2.3.7 EXAMPLE : Panel reading database values
The table below describes what the user should do to create the panel and properly configure the widgets.
Now you can use the ccseiDb utility to change the values of the database attributes and verify if the widgets are correctly updated.
The database attributes associated to the widgets are now specified by their absolute symbolic address. It is also possible to specify the database attributes through their "relative" symbolic address and set the database searching path with the so called "Current Working Point" (for details see paragraph 2.3 on page 29).
When saved the panel definition will also record the value of the Current Working Point: this can be set also as run time parameter when the panel is called (see paragraph 2.4.2 on page 40)
2.3.8 EXAMPLE: Panel with user's defined event procedure
This example shows how to use an event procedure different from the default one.
The purpose of the new procedure is to read a database value and display that value in another unit, for example, it converts degree in radians.
First of all we write the procedure, assuming that the database attribute is of type scalar.
proc userEvtDbUpdate { wdgName attr attrType data { quality "" } } {
global panDbSymbAddr panWidget i_type panDEBUG
if {[info exists panWidget($wdgName)] == 0} { return }
# Convert the database value from degree to radians
set degreeValue [lindex $data 2]
set radValue [expr ($degreeValue * 3.14 )/360]
panUpdateLocalVar $wdgName [lindex $panWidget($wdgName) $i_type] $radValue
if { [cequal $quality ""] } { return }
if { ![cequal [lindex $quality 1] "OK"] } {
The table below describes what the user should do to create the panel and properly configure the widgets.
Now you can use the ccseiDb utility to change the values of the database attributes and verify if the widgets are correctly updated.
2.3.9 EXAMPLE : Panel writing values into the database
The table below describes what the user should do to create the panel and properly configure the widgets.
The widgets are now configured to access database attributes, but their values are not automatically written into the database: for this the user must explicitly give a command.
These operations are typical for the kind of actions to be added to the "action area" and therefore we must add some "Action Buttons" at the bottom of the panel.
2.4 COMMAND INTERFACE
This section presents the kind of statements that can be assigned to the "TCLCommand" field of the configuration panels, of course the same applies to statement used in a normal tcl procedure.
2.4.1 Syntax for tcl/tk commands
Some widgets can be used to trigger actions: an action is a sequence of tcl/tk statements, being the statements separated by a semicolon (;) such as:
The followings are examples of specific TCL statements :
2.4.2 Calling Other Panels
The panel editor supports two ways to call another panel.
In this case the new panel is "sourced" by the calling panel and the two panel share the same Tcl interpreter and the same data space: the procedure panImportPanel supports this functionality.
This means that if the two contain widgets acting on the same variable name, whenever a change is done in one, this is automatically reflected to the other.
The calling panel and the new one are treated as two different processes with their own data space: the procedure panCallPanel supports this functionality.
The same apply in the case one wants to use panImportPanel in place of panCallPanel.
2.4.3 Send a Message to a Process
The library of the panel editor provides the procedure panSendCommand to send messages to other processes (see man pages for details).
The <parameter list> can contain fixed values and widget names. In the latter case the name of the widget is internally replaced by the value stored in the widget.
The procedure returns "FAILURE" in case the command could not be delivered: an example of use is the following:
The procedure automatically calls a dialogue box to warn the user and stops the execution for the user's acknowledgment when :
2.4.4 Command Feedback Window
This widgets is one of the panel's "standard component" and it is used to convey to the user information on the messages sent to other processes.
Each row contains a reply which contains the following information :
Here is an example of the output produced by invoking panSendCommand to send the command OBJFIX to the process trkwsControl.
The user is notified that the command OBJFIX was invoked.
10:38:16 OBJFIX cmd0 trkwsControl > INVOKED
10:38:16 OBJFIX cmd0 trkwsControl > REPLY/ L OK
If the command cannot be sent, the following message appears :
10:44:05 INIT > INVOKED Failure sending the command
There is also the possibility to display some text to comment, for example, the purpose of a set of commands such as :
10:34:41 > *** Search Guide Star ***
2.4.5 Interface to The Command Feedback Window
For the user who wants to develop its own procedures (based on the seq_msgSendCommand procedure) to send commands, a set of procedures to interact with the Command Feedback Window is available.
The user has the possibility to add a comment giving more details of what the current action does , for example :
10:39:11 INIT > INVOKED Send Command to alttrkServer
Let the user display a description of the current action or status. This can be used to give the user high level description on the ongoing activities, for example at the beginning of a group of commands.
This an example of use of these functions in a very simple case :
if {[catch {seq_msgSendCommand $cmdCheck $envName $procName $cmd $parList} ret] } {
panDisplayCommand $cmd $procName "Failure sending the command"
panDisplayCommand $cmd $procName "text describing the action" $cmdId
set ret [catch {seq_msgRecvReply $flags $cmdId errFlag lastReply -${timeout}
panDisplayReply $cmd $cmdId $procName $errFlag $lastReply $idx $ret
Hereafter is reported an example of messages taken from the TCS user interface :
10:35:08 > *** Search Guide Star ***
10:35:08 SRCGS agwsControl > INVOKED
10:35:08 SRCGS agwsControl > REPLY/ L OK
10:37:07 > *** Configuring to Error Minimum: 0.0 frequency: 0.1 ***
10:38:16 OBJFIX trkwsControl > INVOKED
10:38:16 OBJFIX trkwsControl > REPLY/ L OK
10:38:01 OBJFIX trkwsControl > REPLY/ L OK, superseded by valid equivalent command
2.4.6 EXAMPLE : Panel sending command to another process
The panel editor library provides a procedure (panSendCommand) to send commands to a process running either in the local environment or in a remote one : the procedure returns the reply of the message or a FAILURE ( see the corresponding man page for more details).
The panel editor provides a standard widget where all replies returned by a given command are displayed.
The table below describes what the user should do to create the panel and properly configure the widgets.
In case of errors the user will be notified with a dialog box reporting the reason of the error.
2.5 USER'S DEFINED PROCEDURES
During the GUI development some widgets can invoke TCL commands - e.g. - button widgets, then the user has two alternatives :
· Invoke a TCL procedure . This latter solution is advisable when several TCl statements and in particular conditional statements are involved.
User's defined procedures can be :
The user has to specify the name of the library where the panel (during execution) can find the procedure. (see paragraph 2.8 for naming conventions on TCL libraries)
The library can be "linked" to the panel by using the selection "Register User Library" under the "Options" menu and the search path for the library follows the normal VLT conventions.
Very often there is the need not only to send a command but also to verify the returned state, therefore the characteristic of those procedures are :
· The body of those procedures is simple and small. This help prevent syntax mistakes which can make impossible to load later the panel again.
2.5.1 Standard procedures
Each panel ha assigned three special local procedures which allow the user to customize the GUI and which are executed at specific moments during the creation of the panel : all procedures used in the following procedures must be stored in a library
They are <fileName>GlobalData, <fileName>InitData, <fileName>Init, <fileName>Exit
This procedure is executed at the very beginning and it is used to define constants or default values. These values can be overwritten during run time by re-defining the new value in the command line during the invocation of the panel.
This routine is executed after having registered the panel as CCS application but before defining the widgets. This is the place where to define variables and any other type of data requiring to interact with the CCS environments to be defines, for example read the database or send a command to a process.
set attr @${tcsEnv}:Appl_data:TCS:msw:foc.currentFocus
if {[cequal [panDbRead $attr currentFocus] FAILURE]} {
panDisplayComment "Cannot Read Current Focus from $attr"
2 { set myLcu lt$env(TCSID)ada}
3 { set myLcu lt$env(TCSID)adb}
4 { set myLcu lt$env(TCSID)adc}
panDisplayComment "WARNING : Undefined Focus"
This routine is executed as last statement of the initialization procedure, here the user can insert code for specific initialization, for example, to re-configure widgets.
2.5.2 Set Defaults or Constants
Users can define default values for variables or constants which are used in the procedures but these variables must be declared as `global'.
The standard procedure <filename>GlobalData must be used to define those default values, which can be overwritten by passing the new value in the command line (see paragraph 2.4.2 on page 40 ).
· Click on "Set Global Var." : the template for the procedure <filename>GlobalData will appear in the text widget, ready to be edited to add the user definitions.
· Click on "Register Proc" when ready, to register the procedure definition. If that procedure has been already defined, it is accessible as any other from the "Edit proc ..." menu.
Example : This example of <filename>GlobalData procedure the user defines some database attributes which will be accessed by other procedure being part of the GUI.
2.5.3 Editing Local Procedures
The panel editor provides the GUI developer with an editing tool to browse through the "local" procedures of a panel.
Syntax errors found in the procedure definition are detected only at run-time, therefore they can make the panel editor unable to load the panel definition again.
In order to avoid such mistakes it is recommended to :
- The procedure is known by the TCL interpreter and can be executed if assigned to a widget. Any other previous definition is replaced with the new one.
Edit the procedure definition according to the modifications to be done and when ready click on "Register Proc".
Once the panel is loaded, the panel editor keeps track of the procedures included in the panel definition.
The button "Edit proc ..." is a menu listing the procedures included in the current panel definition : the selection of one of those entries will make the procedure definition appear in the text widget and ready to be modified.
The procedure disappears from the list and its definition is cancelled, therefore it is not saved with the panel definition.
Caution : The user must take care of deleting the calls to a `deleted procedure' because the TCL interpreter will not be able to execute it.
2.5.4 Application Defaults
A X resource file can be associated to each panel and it is read before any widget declaration.
The name of this file is "X<filename>" without the .pan extension : for example testAllWidgets.pan looks for the resource file XtestAllWidgets.
2.6 USAGE OF "Mega-Widgets"
The term "Mega-Widget" identifies a group of widgets that can be considered as a single entity.
At higher level GUI application there is the need for widgets implementing `application-specific' functionality and therefore the Panel Editor supports the development of GUI using an "object oriented" approach
The advantages in using `mega-widgets'.
· Re-usability : Mega-Widgets used in early phases or for engineering interface can be also used for real control panels
· Ease GUI Development : Development of large panels can be split up in the creation of smaller panels that can be integrated together.
· Extension of VLT Look & Feel Concept : Telescope and Instruments can use the same components for the development of GUI applications.
The panel editor itself can create special kind of widgets called "uifClass-widget" : in this context we will use the term "class" as a synonym for "Mega-Widget".
2.6.1 Import a "Mega-Widget"
The panel editor allows the user to add a "Mega-Widget" or a "uifClass-widget" to the panel.
The procedure is valid for both kinds of widgets
A class browser allows the user to select a class. On top of the class browser there are radio buttons allowing the user to set the search directory to : Module, INTROOT, VLTROOT, VLTDATA, TCLTK_ROOT or Other.
The class browser is automatically positioned to the corresponding lib directory, when the user selects the VLT standard search paths
2.6.2 Panel Editor "uifClass-Widget"
The panel editor itself can create special kind of Mega-Widgets called "UIF Class" : in this context we will use the term "class" as a synonym for "Mega-Widget".
The uifClass has been introduced to add the concept of re-usable `sub-panel' to be associated to DB classes. These classes have a set of pre-defined methods and public variables and the panel editor does not provide means to add new methods/public variables.
Therefore all DB attributes should be specified with a `relative' symbolic address and in particular the user should identify a `common' root point.
The user can define a point of the database to be used to resolve the DB `relative' addresses : this point is called Current Working Point (CWP) and can be specified in the command line calling the panel (we refer to this to as `panel CWP').
A uif-class is meant to provide a GUI for the data stored under a specific DB sub-tree, therefore each instance of the class has an additional CWP. This additional CWP allows the user to configure the different instances of the class to get the data from different DB sub-trees.
If the class CWP is defined as `relative' address, the class DB attributes will refer to a resulting CWP obtained from the concatenation of the `panel CWP' (:p1:p2:p3) and the `class CWP' (p4:p5) ; in our example this results in ":p1:p2:p3:p4:p5".
This example shows how to configure the DB addresses in a class : the example uses the definition of the class showing the CCD clock pattern.
The panel using this class is invoked by specifying the "panel CWP" and possibly the environment where to access the data: some examples are the followings :
The table below shows what will be the run-time complete DB symbolic address of one of the above DB attributes with different setting of the panel and class CWP.
Example of "embedded" uifClass
This is taken from the panels used for testing and shows an example of use of "embedded" classes and how to configure them to access database values ; in particular how panel CWP and class CWP work together.
What follows is the structure of the database used by the above panel .
· Design the class layout as a normal panel : use "relative" DB symbolic addresses common to a single point of the database.
The name of the file is converted into <fileName>_uifClass.tcl , for example, if the user specifies only "ccdClock", this is converted into "ccsClock_uifClass.tcl".
NOTE : The menubar and the short help, if present, are automatically taken away when the panel is saved as `class'.
· To make the class ready to be imported into other panels it must be included into a library.Once the class is created and the name added to the Makefile do : make all install.
The configuration of a uifClass is limited to a few parameters. To configure the instance of the "uifClass-widget", move the cursor onto the widget, click <B3> and the one of the following configuration panel will appear.
· The class is created surrounded by a default frame, but the user can select one of the following possibilities : flat, raised, groove and ridge.
· The class "working point" is used to resolve the `relative' DB addresses of the widgets used in the different instances of the class : for details see paragraphs 2.6.2 and .
Assign to class instances always different names to avoid clashes in the naming space of array gvar(). In particular this is possible when one wants to create two classes which are importing a common class.
The layout of an existing uifClass-widget can be edited by loading its definition through the command "Load Class" and the new layout can be saved by using "Save Class" or "Save Class as ...".
2.6.3 Public Domain "Mega-Widget"
These widgets are implemented in straight itcl (incremental Tcl) or itk (incremental Tk) : this allows the user to implement widget with very specific and more flexible functionality.
These widgets must be stored in a directory with a tclIndex file to be able to use them in the panel editor.
· To make the class ready to be imported into other panels it must be included into a library.Once the class is created and the name added to the Makefile do : make all install.
When the panel editor imports the Mega-Widget, it assigns a default names to the instance of the Mega-Widget and the instance is created with the `default' configuration parameters.
To configure the instance of the "Mega-Widget", move the cursor onto the widget, click <B3> and the one of the following configuration panel will appear.
The user has access to all widget's options (public variables) and can configure the widget as follows :
- Select the parameter to configure from the list box : name and current value of the selected parameter will appear in the corresponding entry widgets.
2.6.4 Panel Editor "Mega-Widgets"
There is a set of itk-implemented mega-widgets provided by the panel editor.
They are stored in the uifCommon library and are available by selecting "Common" in the widgets window of the panel editor ( see paragraph 3.4 on page 73 ).
2.6.5 Link to Widget's Libraries
Sometimes a class library is based on the use of another class library and when the user attempts to `import it', he gets the following message :
The message show that it is not possible to create an instance of the current class because there is no link to the library containing <class name>.
In this case do the following :
· Add the name of the library containing the missing class. The library is searched using the VLT searching path : Module, INTROOT, VLTROOT.
2.7 DEBUGGING COMMANDS
2.7.1 Description of "DEBUG" menu
This section describes the debugging commands available when developing panels.
· User Level : This is the recommended mode which logs on the screen information such as : Current Working Point, results of event's attach/detach operations, failure on reading DB values, etc ..
· Develop Level : more specific information is logged on the screen, such as : specific logs on uifClass.
The sequencer can also print on the screen, for debugging purposes, some information regarding the parameters a given procedures has been called with and some other completion status.
The panel editor provides an interactive interface to enable/disable the printing of this information for a given subset of these functions.
Events are automatically activated as soon as a widget is configured. If the debug level is set, a short message is logged also on the screen providing information on : widget name, script associated to the event, event identifier and DB attribute, for example :
This command pops up a window containing the list of all widgets of the panel under editing. At the top there is a summary of the number and type of widgets in the panel, in particular :
Widgets are described by their main configuration parameters, such as :
When the user select an entry of the list, the corresponding widget in the panel is highlighted by changing its background color.
· Update Widget List. Updates the list of widgets when a new panel has been loaded or after new widgets have been added to the panel.
2.7.2 Activate Run-Time DEBUG Flags
The debug information can be obtained also for running panels by specifying the value of variable panDEBUG in the command line as specified in the following table, for example :
The sequencer debugging flags can be enabled/disabled by setting the element of the seq_debug global array which corresponds to a given procedure.
For example "seq_debug(seq_dbReadSymbolic)=1" enables to print debugging information for the seq_dbReadSymbolic procedure.
2.8 BUILDING PANELS IN THE VLT ENVIRONMENT
2.8.1 Makefile
To develop panel files that are compatible with the VLT Standards:
In the directory the panels are stored as "fileName.pan" and are installed in the bin directory as any other script without the `.pan' extension.
In the Makefile the variable PANELS or PANELS_L contains the list of panels (without the `.pan' extension )
TCL libraries are formed by files with `.tcl' extension and for each library the file tclIndex contains the list of all files belonging to the library. This file is automatically generated.
The name of the directory has the following format lib<name of the library>.tcl, for example if the name of the library is `uifClass', the corresponding directory will be libuifClass.tcl.
For each library one has to specify its `objects' or members. Each member is the name of a file without `.tcl' extension, for example :
2.8.2 File naming
To allow portability, the panel editor uses special search rules to locate files (other panels, bitmaps, etc). Each file must be specified using the filename and the subdirectory branch of the VLT structure :where it should be located, e.g., bitmaps/xyz.xbm.
The procedure findVLTFile must be used to locate files in the VLT file system structure : for example if the current directory is ~user/development/mymod/src, and the file to be searched is bitmaps/ntt.xbm, then the procedure will look for the following files :
2.8.3 Example of Makefile
Here follows an example of Makefile summarizing the rules mentioned in the previous paragraph.
This example of makefile shows only the parts strictly related with TCL.
2.9 CAVEATS
This section describe some common problems and the possible causes.
2.9.1 LOAD Operation Fails
The load operation is based on the `source' of the panel's definition file , that is, the definition file is interpreted by the Tcl/Tk interprets as it were a `single statement'.
As soon as an error occurs the `source' operation exits, therefore parts of the definition can be lost : this is typically the case of the user's procedures defined at the end of the file.
2.9.2 SAVE Operation Fails
At the beginning of the operation the file is saved in a `backup' copy : the backup copy of the file contains the character "~" after the file names' s extension.
The operation "Save as ..." check if there is already a file having the new name and makes a backup copy.
· Typically this fails for a syntax error in a user's defined procedure. To avoid this risk it is better to execute the procedure as soon as it is created.
2.9.3 Widget already exists
A dialog box appears on the screen and wait for user's acknowledgment before proceeding.
· When a new widget is created : the panel editor attempts to automatically rename the widget with a new valid name.
2.9.4 Set CWP Fails
A dialog box appears on the screen and wait for user's acknowledgment.
· Environment not active : Check the value of RTAPENV environment variable and verify if the Rtap environment is running.
2.10 HOW TO REPORT A PROBLEM
Tcl/Tk is an interpreter and some time errors are discovered only at run time.
In case of run-time errors Tcl/Tk calls a dialog box containing the error stack.
This information is very important to trace the error back to where it happened and can be "Cut & Paste" into a file : the stack contains all the sequence of all the called Tcl/Tk procedures.
To "Cut & Paste" the stack do the following :
WARNING : The stack cannot trace procedures associated to widget binding.
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|
