Using the form creation functions, it is possible to define forms at a higher level than basic Tk widgets. You can create a form, which is a top level widget, using form_init and then fill it in using other form_ functions. Most of the functions take the following arguments and not the individual function definition.
w: the widget name for the widget being created. This must be a descendant of the frame that is returned by form_init
tabdata: this is the row/column specification that is used with the grid manager. The tabdata string is of the form row column [options ...] where row and column are non-negative integers and the options can be:
-cols numcols: span this many columns
-rows numrows: span this many rows
-sticky nwes: some subset of north, west, east, south, to determine the widget alignment
activedata: this is a list of varname value ... lists that determine when the widget is active or disabled. A trace is put on each varname, and whenever the value changes it is checked to see if it matches a value in the list. If all the varnames are okay then the widget is enabled, otherwise it is disabled and grayed out. The values can be either a regular value, or !value which matches anything but the given value. If no values are given then a non-zero value is matched.
borderwidth: the width of the widget border in pixels.
relief: the relief of the widget - should be one of flat, raised, sunken, ridge, groove
form_init w title class [""] buttons [""] retcmd [""] map [1] orien [1] resize [""] dismiss_cmd [""]
Creates a new top level form, or maps the window if it has already been created. The arguments are:
w: this is the name of the top level form to create
title: the window manager title for the window
class: if non-blank, unmap all windows with this same class name
buttons: a list of button specifications for the row of gray buttons at the bottom. Each spec may be a list with a title and a command, or one of the following standard names:
accept: closes the form and returns 1 from form_wait
reset: resets all variables back to their original values
cancel: closes the form, resets the variables, and returns 0 from form_wait
done: same as accept except for the button label
dismiss: same as accept except for the button label
close: same as accept except for the button label
nl: goes to a new row of buttons
retcmd: the command to run when you press return in some field where it is not otherwise bound. The default is to activate the first button at the bottom
map: if 1, maps the window, otherwise not. If 2 then maps the window and prevents it being a transient window
orien: if 1 then the window will be oriented vertically, if 0 horizontally
The return value of form_init is a frame widget where all further form_widgets for this form should be placed. If it is an empty string it implies that the form has already been created and you should not add any more widgets.
form_side_figure w var pref [""] opts [""]
Creates an area on the side of the main form that contains a figure which is updated as needed depending on the variable. If no options are given, specify a file name instead of the variable.
form_cancel_class class except [""]
Dismisses all forms with the given class except for the one named except, if specified.
form_cancel_all except
Dismisses all forms.
form_check_visible_class class
Returns the forms in the class that are visible.
form_wait w use_grab [0]
After the form creation has been completed using form_finish, this function can be called which will do a tkwait and return only when the form has been dismissed. It returns 1 if the button has been pressed and 0 if has been pressed. If use_grab is specified as 1, then proc will prevent interaction with any other widget until interaction with this form is complete.
form_done w flag [1]
Makes the form go away (withdraws it).
form_kill w
Destroys the form if it has been created. The next time form_init is called, it will return a sub-window name so the form can be recreated from scratch.
form_finish geo [-0-0] map [1] autoraise [0]
This function should be called when the sub-windows have all been created, and the form is ready to map. The arguments are:
geo: the geometry in wm geometry format. Also bot means the lower-left hand corner and top is the upper right-hand corner.
map: if 1, then the window is to be mapped. If 0 the window is to be unmapped.
autoraise : if 1, then any time this window goes behind another it will try to jump to the front. Precautions are taken to prevent fighting between two autoraise forms.
form_colwidth w num width units [""]
Makes the width of the given column in the form as specified for width. If units is non-empty then the width will be taken to be character widths, else it will be considered pixels.
form_rowheight w num height
Makes the height of the given row in the form as specified by height.
form_canvas w geo relief borderwidth tabdata xs [1] ys [1]
Creates a canvas widget.
geo is of the form width × height and gives the size of the canvas.
If xs or ys is 1 then an X or Y scroll bar, respectively, is created.
form_table w coltitles variable relief borderwidth cellw tabdata xs [1] ys [1] nrows [1]
Creates a table widget.
form_listbox w title items click_cmd dclick_cmd geo tabdata activedata [""] call_with_index [0] d_call_with_index [0] multi_select [0] xscroll [0]
Creates a listbox widget. The arguments are:
title: a string to put at the top of the listbox
items: a list of items which go in the listbox initially
click_cmd: if non-empty, a command which is bound to a single left mouse click in the listbox. The item is appended to the command unless call_with_index is set in which case the index of the item is used instead.
dclick_cmd: if non-empty, a command which is bound to a double left mouse click in the listbox. The item is appended to the command unless d_call_with_index is set in which case the index of the item is used instead.
geo: the value is of the form width × height and gives the size of the listbox
multi_select: if this is 1, it will be possible to select more than one item at a time, and the click_cmd and dclick_cmd functions will be called with a list of items rather than just one.
form_listbox_add w item
Adds the item to the end of the listbox, unless it is already there.
form_listbox_add_dup w item
Adds the item to the end of the listbox, irrespective of whether it is there or not.
form_listbox_delete w item
Deletes the item from the listbox. This returns the item right after the deleted one or the one before it, if it was the last.
form_listbox_delete_index w pos
Deletes the item at the specified position in the listbox.
form_listbox_change w old new
Changes the item old to new.
form_listbox_select w item glob [0]
Makes the given item the selected one.
form_listbox_select_index w pos
Makes the item at the given position the selected one.
form_listbox_get_select_index w
Returns the index of the selected item.
form_listbox_get_selected w
Returns the value of the selected item.
form_listbox_set_selected w vals
Sets the value of the selected item.
form_listbox_clear w
Deletes all items from the listbox.
form_listbox_set w items resize [0]
Sets the items in the listbox to the ones in the list. If resize is 1, then make sure the listbox is wide enough to hold all the items.
form_listbox_set_index w num item
Sets the item at the given position to be item.
form_listbox_get w num [""]
Gets the item at the given position, or all items if blank.
form_listbox_size w
Returns the number of entries in the listbox.
form_listbox_scale w size
Resizes the listbox to have the given number of rows.
form_entry w var datatype tabdata activedata [""] width [8] rjust [""] save_var [""] cmd [""]
Creates an entry widget. The arguments are:
var: the variable to bind to the widget value
datatype: the data type to check the value against, if non-blank. This may be one of the following types:
float: a floating point number
float_expr: a floating point number or Tcl expression
float_var: a floating point number or $var string
float_blank: a floating point number or blank
float_cmp: a floating point number greater than 1
int: an integer
int_blank: an integer or blank
pct: a float between 0 and 100
coords: 3 floats separated by spaces
coords_float: 3 floats separated by spaces or 1 float
choice: this keyword is followed by a list of options. The value in the entry must be one of the options
choice_others: the same as choice but no verification is done
string: any string
width : the width of the widget
form_text w title var tabdata activedata [""] geo [40x10] xscroll [0] font [""]
Creates a text widget. The arguments are:
title: a string to put above the window
var: the variable to bind to the widget's value
geo: the value is of the form width × height and gives the size of the text area
Note: Unlike the entry widget, the value in the text area is only synchronized when the form is mapped and accepted.
form_text_get w
Returns the text in a text widget.
form_text_set w value
Sets the text in a text widget.
form_text_append w value
Appends to a text widget.
form_make_table rows1
Formats a table as text.
form_button w title command tabdata activedata [""]
Creates a button.
title: the string on the widget
command: the command to bind to the button
form_button_bitmap w bmap command tabdata activedata [""]
Creates a bitmap button.
bmap: the bitmap to be drawn on the button
command: the command to bind to the button
form_checkbutton w title var tabdata activedata [""] command [""] nonbool [""]
Creates a check button.
title: the string on the button
var: the boolean variable to assign to the button
command: the command to bind to the button
nonbool: (optional) accept non-boolean variables (e.g. catia v4 import) -fifi
This has special code to deal with parameters.
form_radiobutton w title var val tabdata activedata [""] command [""] allow_params [1]
Creates a radio button.
title: the string on the button
var: the variable to assign to the button
val: the value to assign to the variable when the button is selected
command: the command to bind to the button
This has special code to deal with parameters.
form_menubutton w title menu tabdata activedata [""]
Creates a menu button.
title: the string on the button
menu: the menu to bind to the button
form_menubutton_regular w title menu tabdata activedata [""]
Creates a menu button, but makes it look like a regular button.
title: the string on the button
menu: the menu to bind to the button
form_optionmenu w var opts tabdata activedata [""] changecmd [""]
Creates a menu button and menu and defines the text of the button to be the current value of the variable controlled by the menu.
var: the variable whose value is controlled by the menu
opts: a list of {value name} pairs which are added to the menu
form_optionmenu_dynamic w var func tabdata activedata [""]
Creates a menu button and menu and defines the text of the button to be the current value of the variable controlled by the menu. The list of available options is returned by a function that is called every time the menu is posted.
var: the variable whose value is controlled by the menu
opts: a list of {value name} pairs which are added to the menu
form_commandmenu w text commands tabdata activedata [""]
Creates a menu button and menu and fills it with the given commands.
form_label w title tabdata activedata [""] try_ltext [1] justify [""]
Creates a label with the given value. If try_ltext is 1 then the language-specific lookup tables will be checked.
form_label_bitmap w bitmap tabdata activedata [""]
Creates a label with a bitmap.
form_label_image w file tabdata activedata [""]
Creates a label with an image.
form_label_variable w var tabdata activedata [""]
Creates a label attached to a variable.
form_message w text tabdata activedata [""]
Creates a message widget.
text: the text to put in the widget
form_scale w var command orient min max incr tabdata activedata [""] on_release [""] width [""]
Creates a scale widget.
var: the variable whose value is controlled by the scale
command: a command to issue each time the scale moves
orient: v for vertical and h for horizontal
min: the minimum value for the scale
max: the maximum value for the scale
incr: the minimum increment in the value
on_release: a command to be executed when the scale button is released
form_frame w relief borderwidth tabdata
Creates an empty frame.
form_label_frame w label tabdata act [""]
Creates an empty frame with a label and return the inner part.
form_choiceframe w
Creates an empty frame that can be used with the form_setup_switch function.
form_underline w tabdata
Creates an underline.
form_setup_switch frame varname opts [""] cmd [""] change_size [1]
After creating a number of sub-frames using form_choiceframe, which must all be children of a single parent frame, this function sets up a trace on a variable which makes the subframe visible depend on the value of the variable. If the subframes are $d.sub.val1, $d.sub.val2, etc, and there is a variable choicevar which is maybe controlled by a set of radiobuttons elsewhere on the form, and can have the values val1, val2, etc, then form_setup_switch $d.sub choicevar would set this up. The other arguments are:
opts: extra options that can be passed through to the place command to put the subframe in the parent
cmd: a command that is executed after the switch is done
form_scroller w maxh tabdata hfixed [0] wfixed [0]
Creates a scrolled window.
maxh: the maximum height for the outside window.
hfixed: if non zero, it is the fixed height for the outside window.
wfixed: if non zero, it is the fixed width for the outside window.
The return value is a sub-frame that you can then use to put other widgets in.
form_scroller_adjust d
Due to some strange window system interactions, after calling form_finish you need to call this function for each scroller in the form, else the size will not be quite right.