CCP4i: Graphical User Interface
	Documentation for Programmers
	CreateLine

NAME

CreateLine - create a line in an interface window

SYNOPSIS

CreateLine line_id ?keywords?

Keywords:

label label_text
widget variable_name
message message_text
help help_target
format format_mode format_layout
toggle_display controlVar status control_value_list
bitmap_button bitmap_name
button button_text

DESCRIPTION

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).

label label_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.

widget variable_name ?-oblig -width -expand -command command_script -toggleon?

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 highlighted in a contrasting 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

-command command_script

Provide a command script (usually a call to a procedure), which is executed whenever the user changes the value of the parameter

If the widget is a logical (checkbutton), the followin subkeyword is possible:

-toggleon

if the user changes the values of the other parameters on the same line as the checkbutton, then it will automatically turn the checkbutton `on'.

message message_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.

help help_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.

format format_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_display controlVar 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. misspelled 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.

KEYWORDS