Create a line in the open task window folder (see
CreateTaskWindow
and
OpenFolder) or
an open window (see
OpenWindow) and return
the id of the line line_id. All remaining arguments are optional but take
the form of a keyword followed by one or more arguments (the number is
defined for each keyword). In addition, some keywords can have subkeywords
which always begin with the minus character (e.g. the -width
subkeyword to widget).
labellabel_text ?-italic?
Write text label_text to line. The -italic option, to use italic
text, should be used sparingly: probably only in a line which introduces several
subsequent lines, and can thus act as a title/help text.
Draw the widget (menu, entry field, button etc.)
appropriate for the data type of the parameter variable_name. The data type
must have been defined in the taskname.def file.
If the widget is an entry field, the following subkeywords are possible:
-oblig
the parameter is obligatory - the field will
be highlightled in a contrast colour until the user has entered appropriate values
-width
the width of the field (number of characters),
overriding the default for the data type
-expand
expand the field to fill the line
-commandcommand_script
Provide a command script
(usually a call to a procedure), which is executed whenever the user changes
the value of the parameter
messagemessage_text
Specify the text message_text which will appear in the message
bar whenever the user moves the cursor over any widget in the line
defined after this message keyword but before the next
message keyword.
helphelp_target
The user can access on-line help by clicking the right mouse button
on a widget. The help file is defined by the preceding SetProgramHelpFile
command. The help_target is the target within that file to go to
when the user clicks on any widget in the line following this help
keyword but before the next help keyword.
formatformat_mode format_layout
Specify the format of a line. Currently the only supported value of
format_mode is template which requires the name of the
format_layout to be the name of the template defined by the
CreateLineTemplate command.
toggle_displaycontrolVar status
control_value_list
Whether the line is displayed, is dependent on the value of the parameter
called controlVar. If the value of controlVar is one of
the values in control_value_list, the line will be displayed
if status is open or hidden if status is
hide. The opposite status will be adopted if the value of
control_var is not one of those in the control_value_list.
HINTS
ERRORS
This command is fairly tolerant of bad input (e.g. mis-spelled keywords)
but is unlikely to give you a meaningful warning message. It will be obvious
there is a problem when you look at what is displayed. My most common mistake
is failure to define the variable_name associated with the
widget keyword in the taskname.def file.
MESSAGE TEXT
For the benefit of users who are used to running a program without the
interface, the message text should include the name of the program keyword
that the parameter relates to. The message text is not helpful if it repeats
what is already stated in the labels.
USING TOGGLE_DISPLAY
It is a good thing to use toggle_display to hide any lines which
are definitely not relevant to the task the user is trying to perform.
Also, a line may take two or more different forms dependent on some parameter:
to implement this it is necessary to define two or more versions of the
line and hide the version(s) which are not required.
The control variable for toggle_display is usually a menu (I
have never used anything else). The control variable should usually either
be in the protocol section of the task window, or in the same folder and
above the line to be toggled.
It is also possible to have a line which changes form dependent on some
parameter within the line. For example (in CCP4i v1.0) in the DM task interface
the first line at the top of the window is dependent on the phase combination
scheme. Look for PHASE_COMB in the file $CCP4I_top/tasks/dm.tcl to
see how this works. Note that the parameter PHASE_COMB controls not
only the form of the line that it appears in, but also another line in the
first folder.