|
|
Эта страница руководства для версии 10.9 Mac OS XЕсли Вы выполняете различную версию Mac OS X, просматриваете документацию локально:
Читать страницы руководстваСтраницы руководства предназначаются как справочник для людей, уже понимающих технологию.
|
tepam::argument_dialogbox(n) Tcl^s Enhanced Procedure and Argument Manager tepam::argument_dialogbox(n)
____________________________________________________________________________________________________________
NAME
tepam::argument_dialogbox - TEPAM argument_dialogbox, reference manual
SYNOPSIS
package require Tcl 8.3
package require Tk 8.3
package require tepam ?0.1?
tepam::argument_dialogbox item_name item_attributes ?item_name item_attributes? ?...?
tepam::argument_dialogbox {item_name item_attributes ?item_name item_attributes? ?...?}
____________________________________________________________________________________________________________
DESCRIPTION
ARGUMENT DIALOGBOX CALL
TEPAM's argument_dialogbox is a flexible and easily usable entry form generator. Each entry element
of a form is defined via a data entry item that can be provided to argument_dialogbox in two formats:
tepam::argument_dialogbox item_name item_attributes ?item_name item_attributes? ?...?
Using this first format, each data entry item is defined via a named argument. The item name
defines thereby the entry element type that has to be used in the form. The item data, called
item attributes, defines the variable which is attributed to the data entry element as well as
eventual formatting and context information.
The argument_dialogbox returns ok if the entered data have been acknowledged (via the OK but-ton) button)
ton) and validated by a data checker. If the entered data have been rejected (via the Cancel
button) the argument_dialogbox returns cancel.
A small example is the simplest way to illustrate how the argument_dialogbox can be employed:
set DialogResult [tepam::argument_dialogbox \
-title "Itinerary selection" \
-file {-label "Itinerary report" -variable report_file} \
-frame {-label "Itinerary start"} \
-comment {-text "Specify your itinerary start location"} \
-entry {-label "City" -variable start_city -type string} \
-entry {-label "Street" -variable start_street -type string -optional 1} \
-entry {-label "Street number" -variable start_street_nbr -type integer -optional 1} \
-frame {-label "Itinerary destination"} \
-comment {-text "Specify your itinerary destination"} \
-entry {-label "City" -variable dest_city -type string} \
-entry {-label "Street" -variable dest_street -type string -optional 1} \
-entry {-label "Street number" -variable dest_street_nbr -type integer -optional 1} \
-frame {} \
-checkbutton {-label "Don't use highways" -variable no_highway}]
This example opens a dialog box that has the title Itinerary selection. A first entry element
in this box allows selecting a report file. It follows two frames to define respectively an
itinerary start and end location. Each of these locations, that is described with a comment,
has three entry elements to specify respectively the city, street and the street number. Bel-low Bellow
low the second frame there is a checkbutton that allows specifying if eventual highways should
be ignored.
tepam::argument_dialogbox {item_name item_attributes ?item_name item_attributes? ?...?}
Sometimes it is simpler to provide all the data entry item definitions in form of a single
list to argument_dialogbox, and not as individual arguments. The second format that is sup-ported supported
ported by argument_dialogbox corresponds exactly to the first one, except that all item defi-nitions definitions
nitions are packed into a single list that is provided to argument_dialogbox. The previous
example can therefore also be written in the following way:
set DialogResult [tepam::argument_dialogbox {
-title "Itinerary selection"
-file {-label "Itinerary report" -variable report_file}
...
-checkbutton {-label "Don't use highways" -variable no_highway} }]
The commands argument_dialogbox as well as procedure are exported from the namespace tepam. To use
these commands without the tepam:: namespace prefix, it is sufficient to import them into the main
namespace:
namespace import tepam::*
set DialogResult [argument_dialogbox \
-title "Itinerary selection"
...
The following subsections explain the different items that are accepted by the argument_dialogbox,
classified into three groups. The first data entry item definition format will be used in the remain-ing remaining
ing document, knowing that this format can always be transformed into the second format by putting
all arguments into a single list that is then provided to argument_dialogbox.
CONTEXT DEFINITION ITEMS
The first item group allows specifying some context aspects of an argument dialog box. These items
are taking a simple character string as item data:
tepam::argument_dialogbox \
-<argument_name> string \
...
The following items are classified into this group:
-title string
The dialog box window's title which is by default Dialog can be changed with the -title item:
tepam::argument_dialogbox \
-title "System configuration" \
...
-window string
The argument dialog box uses by default .dialog as dialog top level window. This path can be
changed with the -window item:
tepam::argument_dialogbox \
-window .dialog \
...
-parent string
By defining a parent window, the argument dialog box will be displayed beside this one. With-out Without
out explicit parent window definition, the top-level window will be considered as parent win-dow. window.
dow.
tepam::argument_dialogbox \
-parent .my_appl \
...
-context string
The dialog box's state, e.g. the entered data as well as the window size and position, is
saved and restored the next time the argument dialog box is called if a context is defined.
The assignment of a context allows saving the dialog box' state in its context to distinguish
between different usages of the argument dialog box.
tepam::argument_dialogbox \
-context destination_definitions \
...
FORMATTING ITEMS
Especially for big, complex forms it becomes important that the different data entry widgets are
graphically well organized and commented to provide an immediate and clear overview to the user. A
couple of items allow structuring and commenting the dialog boxes.
The items of this classification group require as item data an attribute definition list. The
attribute definition list contains itself attribute name and data pairs:
tepam::argument_dialogbox \
...
-<argument_name> {
?-<attribute_name> <attribute_data>?
?-<attribute_name> <attribute_data>?
?...?
}
...
The following items are classified into this group:
-frame list
The -frame item allows packing all following entry widgets into a labeled frame, until a next
frame item is defined or until the last entry widgets. It recognizes the following attributes
inside the item data list:
-label string
An optional frame label can be specified with the -label statement.
Example:
tepam::argument_dialogbox \
...
-frame {-label "Destination address"}
...
To close an open frame without opening a new one, an empty list has to be provided to the -frame
statement.
tepam::argument_dialogbox \
...
-frame {}
...
-sep [const {{}}]
Entry widgets can be separated with the -sep statement which doesn't require additional defi-nitions. definitions.
nitions. The related definition list has to exist, but its content is ignored.
tepam::argument_dialogbox \
...
-sep {}
...
-comment string
Comments and descriptions can be added with the -text attribute of the -comment item. Please
note that each entry widget itself can also contain a -text attribute for comments and
descriptions. But the -comment item allows for example adding a description between two
frames.
tepam::argument_dialogbox \
...
-comment {-text "Specify bellow the destination address"}
...
DATA ENTRY WIDGET ITEMS
Data entry widgets are created with the widget items. These items require as the formatting items an
attribute definition list as item data:
tepam::argument_dialogbox \
...
-<argument_name> {
?-<attribute_name> <attribute_data>?
?-<attribute_name> <attribute_data>?
?...?
}
...
The attribute list can contain various attributes to describe and comment an entry widget and to con-strain constrain
strain its entered data. All entry widgets are accepting a common set of attributes that are
described in the section Entry Widget Item Attributes.
TEPAM defines a rich set of entry widgets. If necessary, this set can be extended with additional
application specific entry widgets (see APPLICATION SPECIFIC ENTRY WIDGETS):
-entry list
The -entry item generates the simplest but most universal data entry widget. It allows enter-ing entering
ing any kind of data.
tepam::argument_dialogbox \
-entry {-label Name -variable Entry}
-checkbox list
A group of check boxes is created with the -checkbox item. The number of check boxes and their
option values are specified with a list assigned to the -choices attribute or via a variable
declared with the -choicevariable attribute:
tepam::argument_dialogbox \
-checkbox {-label "Font sytle" -variable FontStyle \
-choices {bold italic underline} -default italic}
If the check boxes' texts should differ from the option values, they can be defined with the
-choicelabels attribute:
tepam::argument_dialogbox \
-checkbox {-label "Font sytle" -variable FontStyle \
-choices {bold italic underline} \
-choicelabels {Bold Italic Underline} \
-default italic}
In contrast to a radio box group, a check box group allows selecting simultaneously several
choice options. The selection is stored for this reason inside the defined variable in form of
a list, even if only one choice option has been selected.
-radiobox list
A group of radio boxes is created with the -radiobox item. The number of radio boxes and their
option values are specified with a list assigned to the -choices attribute or via a variable
declared with the -choicevariable attribute.
In contrast to a check box group, a radio box group allows selecting simultaneously only one
choice option. The selected option value is stored directly, and not in form of a list, inside
the defined variable.
tepam::argument_dialogbox \
-radiobox {-label "Text adjustment" -variable Adjustment \
-choices {left center right} -default left}
If the radio boxes' texts should differ from the option values, they can be defined with the
-choicelabels attribute:
tepam::argument_dialogbox \
-radiobox {-label "Text adjustment" -variable Adjustment \
-choices {left center right} \
-choicelabels {Left Center Right} -default left}
-checkbutton list
The -checkbutton entry widget allows activating or deactivating a single choice option. The
result written into the variable will either be 0 when the check button was not activated or 1
if it was activated. An eventually provided default value has also to be either 0 or 1.
tepam::argument_dialogbox \
-checkbutton {-label Capitalize -variable Capitalize -default 1}
Several types of list and combo boxes are available to handle selection lists.
-combobox list
The combobox is a combination of a normal entry widget together with a drop-down list box. The
combobox allows selecting from this drop-down list box a single element. The list of the
available elements can be provided either as a list to the -choices attribute, or via a vari-able variable
able that is specified with the -choicevariable attribute.
tepam::argument_dialogbox \
-combobox {-label "Text size" -variable Size -choices {8 9 10 12 15 18} -default 12}
And here is an example of using a variable to define the selection list:
set TextSizes {8 9 10 12 15 18}
tepam::argument_dialogbox \
-combobox {-label "Text size" -variable Size -choicevariable TextSizes -default 12}
-listbox list
In contrast to the combo box, the list box is always displayed by the listbox entry widget.
Only one element is selectable unless the -multiple_selection attribute is set. The list box
height can be selected with the -height attribute. If the height is not explicitly defined,
the list box height is automatically adapted to the argument dialog box' size. The first
example uses a variable to define the available choices:
set set AvailableSizes
for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [expr 1<<$k]}
tepam::argument_dialogbox \
-listbox {-label "Distance" -variable Distance \
-choicevariable AvailableSizes -default 6 -height 5}
Here is a multi element selection example. Please note that also the default selection can
contain multiple elements:
tepam::argument_dialogbox \
-listbox {-label "Text styles" -variable Styles \
-choices {bold italic underline overstrike} \
-choicelabels {Bold Italic Underline Overstrike} \
-default {bold underline} -multiple_selection 1 \
-height 3}
-disjointlistbox list
A disjoint list box has to be used instead of a normal list box if the selection order is
important. The disjoint list box entry widget is in fact displaying two list boxes, one for
the selected elements and one for the unselected elements.
Disjoint listboxes allow always selecting multiple elements. With the exception of the -multi-
ple_selection attribute, disjointed list boxes are accepting the same attributes as the normal
listbox, e.g. -height, -choices, -choicevariable, -default.
tepam::argument_dialogbox \
-disjointlistbox {-label "Preferred scripting languages" -variable Languages \
-comment "Please select your preferred languanges in the order" \
-choices {JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl} \
-default {Tcl Perl Python}}
The file and directory selectors are building a next group of entry widgets. A paragraph of section
Entry Widget Item Attributes explains the dedicated attributes of these widgets to specify the tar-geted targeted
geted file types, active directory etc.
-file list
The item -file creates a group composed by an entry widget together with a button that allows
opening a file browser. The data type file is automatically selected for this entry if no data
type has been explicitly defined with the -type attribute.
tepam::argument_dialogbox \
-file {-label "Image file" -variable ImageF \
-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
-initialfile "picture.gif"}
-existingfile list
The item -existingfile creates a group composed by an entry widget together with a button that
allows opening a browser to select an existing file. The data type existingfile is automati-cally automatically
cally selected for this entry if no data type has been explicitly defined with the -type
attribute.
tepam::argument_dialogbox \
-existingfile {-label "Image file" -variable ImageF \
-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
-initialfile "picture.gif"}
-directory list
The item -directory creates a group composed by an entry widget together with a button that
allows opening a directory browser. The data type directory is automatically selected for this
entry if no data type has been explicitly defined with the -type attribute.
tepam::argument_dialogbox \
-directory {-label "Report directory" -variable ReportDir}
-existingdirectory list
The item -existingdirectory creates a group composed by an entry widget together with a button
that allows opening a browser to select an existing directory. The data type existingdirectory
is automatically selected for this entry if no data type has been explicitly defined with the
-type attribute.
tepam::argument_dialogbox \
-existingdirectory {-label "Report directory" -variable ReportDir}
Finally, there is a last group of some other special entry widgets.
-color list
The color selector is composed by an entry widget together with a button that allows opening a
color browser. The data type color is automatically selected for this entry widget type if no
data type has been explicitly defined with the -type attribute.
tepam::argument_dialogbox \
-color {-label "Background color" -variable Color -default red}
-font list
The font selector is composed by an entry widget together with a button that allows opening a
font browser. The data type font is automatically selected for this entry widget type if no
data type has been explicitly defined with the -type attribute. The entry widget displays an
example text using the selected font.
The font browser allows selecting by default the font families provided by the font families
command as well as a reasonable set of different font sizes between 6 points and 40 points.
Different sets of font families and font sizes can be specified respectively via the
-font_families or -font_sizes attributes.
If no default font is provided via the -default attribute, the font of the label widget to
display the selected font will be used as default selected font. If the font family of this
label widget is not part of the available families the first available family is used as
default. If the font size of this label widget is not part of the available sizes the next
close available size is selected as default.
tepam::argument_dialogbox \
-font {-label "Font" -variable Font \
-font_sizes {8 10 12 16} \
-default {Arial 20 italic}}
ENTRY WIDGET ITEM ATTRIBUTES
All the entry widget items are accepting the following attributes:
-text string
Eventual descriptions and comments specified with the -text attribute are displayed above the
entry widget.
tepam::argument_dialogbox \
-entry {-text "Please enter your name bellow" -variable Name}
-label string
The label attribute creates left to the entry widget a label using the provided string as
label text:
tepam::argument_dialogbox \
-entry {-label Name -variable Name}
-variable string
All entry widgets require a specified variable. After accepting the entered information with
the OK button, the entry widget's data are stored inside the defined variables.
tepam::argument_dialogbox \
-existingdirectory {-label "Report directory" -variable ReportDir}
-default string
Eventual default data for the entry widgets can be provided via the -default attribute. The
default value is overridden when an argument dialog box with a defined context is called
another time. The data acknowledged in a previous call will be used in this case as default
data.
tepam::argument_dialogbox \
-checkbox {-label "Font sytle" -variable FontStyle \
-choices {bold italic underline} -default italic}
-optional 0|1
Data can be specified as optional or mandatory with the -optional attribute that requires
either 0 (mandatory) or 1 (optional) as attribute data.
In case an entry is optional and no data has been entered, e.g. the entry contains an empty
character string, the entry will be considered as undefined and the assigned variable will not
be defined.
tepam::argument_dialogbox \
-entry {-label "City" -variable start_city -type string} \
-entry {-label "Street" -variable start_street -type string -optional 0} \
-entry {-label "Street number" -variable start_street_nbr -type integer -optional 1} \
-type string
If the data type is defined with the -type attribute the argument dialog box will automati-cally automatically
cally perform a data type check after acknowledging the entered data and before the dialog box
is closed. If a type incompatible data is found an error message box appears and the user can
correct the data.
The argument dialog box accepts all types that have been specified by the TEPAM package and
that are also used by tepam::procedure (see the tepam::procedure reference manual).
Some entry widgets like the file and directory widgets, as well as the color and font widgets
are specifying automatically a default data type if no type has been specified explicitly with
the -type attribute.
tepam::argument_dialogbox \
-entry {-label "Street number" -variable start_street_nbr -type integer} \
-range string
Data can be constrained with the -range attribute. The valid range is defined with a list con-taining containing
taining the minimum valid value and a maximum valid value.
The -range attribute has to be used only for numerical arguments, like integers and doubles.
tepam::argument_dialogbox \
-entry {-label Month -variable Month -type integer -range {1 12}}
-validatecommand string
More complex argument data validations than type checks can be performed via specific valida-tion validation
tion commands that are declared via the -validatecommand attribute. The provided validation
command can be a complete script in which the pattern %P is replaced by the argument data that
has to be validated.
tepam::argument_dialogbox \
-entry {-label "Your comment" -variable YourCom \
-validatecommand "IllegalWordDetector %P"} ]
Some other attributes are supported by the list and combo boxes as well as by the radio and check
buttons.
-choices string
Choice lists can directly be defined with the -choices attribute. This way to define choice
lists is especially adapted for smaller, fixed selection lists.
tepam::argument_dialogbox \
-listbox {-label "Text styles" -variable Styles \
-choices {bold italic underline} -default underline
-choicelabels string (only check and radio buttons)
If the check and radio boxes' texts should differ from the option values, they can be defined
with the -choicelabels attribute:
tepam::argument_dialogbox \
-checkbox {-label "Font sytle" -variable FontStyle \
-choices {bold italic underline} \
-choicelabels {Bold Italic Underline}
-choicevariable string
Another way to define the choice lists is using the -choicevariable attribute. This way to
define choice lists is especially adapted for huge and eventually variable lists.
set TextSizes {8 9 10 12 15 18}
tepam::argument_dialogbox \
-combobox {-label "Text size" -variable Size -choicevariable TextSizes}
-multiple_selection 0|1
The list box item (-listbox) allows by default selecting only one list element. By setting the
-multiple_selection attribute to 1, multiple elements can be selected.
tepam::argument_dialogbox \
-listbox {-label "Text styles" -variable Styles \
-choices {bold italic underline} -default underline \
-multiple_selection 1 -height 3}
Some additional attributes are supported by the file and directory selection widgets.
-filetypes string
The file type attribute is used by the -file and -existingfile items to define the file end-ings endings
ings that are searched by the file browser.
tepam::argument_dialogbox \
-file {-label "Image file" -variable ImageF \
-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}}}
-initialfile string
The initial file used by the file browsers of the -file and -existingfile widgets are by
default the file defined with the -default attribute, unless a file is specified with the
-initialfile attribute.
tepam::argument_dialogbox \
-file {-variable ImageF -initialfile "picture.gif"}
-activedir string
The -activedir attribute will override the default active search directory used by the file
browsers of all file and directory entry widgets. The default active search directory is
defined by the directory of a specified initial file (-initialfile) if defined, and otherwise
by the directory of the default file/directory, specified with the -default attribute.
tepam::argument_dialogbox \
-file "-variable ImageF -activedir $pwd"
Finally, there is a last attribute supported by some widgets:
-height string
All widgets containing a selection list (-listbox, -disjointlistbox, -font) are accepting the
-height attribute that defines the number of displayed rows of the selection lists.
tepam::argument_dialogbox \
-listbox {-label "Text size" -variable Size \
-choices {8 9 10 12 15 18} -default 12 -height 3}
If the no height has been explicitly specified the height of the widget will be adapted to the
argument dialog box' size.
APPLICATION SPECIFIC ENTRY WIDGETS
An application specific entry widget can be made available to the argument dialog box by adding a
dedicated procedure to the tepam namespace. This procedure has three arguments; the first one is the
widget path, the second one a subcommand and the third argument has various purposes:
proc tepam::ad_form(<WidgetName>) {W Command {Par ""}} {
upvar Option Option; # if required
variable argument_dialogbox; # if required
switch $Command {
"create" <CreateCommandSequence>
"set_choice" <SetChoiceCommandSequence>
"set" <SetCommandv>
"get" <GetCommandSequence>
}
}
Argument_dialogbox takes care about the -label and -text attributes for all entry widgets. For the
entry widget it creates a frame into which the entry widget components can be placed. The path to
this frame is provided via the W argument. The entry widget procedure has to support 3 mandatory and
an optional command, defined via the Command argument:
create The entry widget is called a first time with the command create to build the entry widget.
The frames that are made available by argument_dialogbox for the entry widgets are by default
only extendable in the X direction. To make them also extendable in the Y direction, for exam-ple example
ple for extendable list boxes, the command ad_form(make_expandable) $W has to be executed when
an entry widget is built.
set_choice
The entry widget procedure is only called with the set_choice command when the -choices or
-choicevariable has been specified. The command is therefore only relevant for list and combo
boxes.
The available selection list, either specified with the -choices or -choicevariable attribute
is provided via the Par argument to the entry widget procedure which can initialize the selec-tion selection
tion list with this data.
set If a default value is either defined via the -default attribute or via a preceding call the
entry widget procedure is called with the set command. The argument Par contains in this case
the value to which the entry widget has to be initialized.
get The entry widget procedure's command get has to return the actual value of the entry widget.
Eventually specified entry widget item attributes are available via the Option array variable of the
calling procedure. This variable becomes accessible inside the entry widget procedure via the upvar
command.
There may be a need to store some information in a variable. The array variable argument_dialogbox
has to be used for this purpose together with array indexes starting with "$W,", e.g. argu-ment_dialogbox($W,values). argument_dialogbox($W,values).
ment_dialogbox($W,values).
Examples of entry widget procedures are directly provided by the TEPAM package source file that spec-ifies specifies
ifies the standard entry widget procedures. The simplest procedure is certainly the one for the basic
entry widget:
proc tepam::ad_form(entry) {W Command {Par ""}} {
switch $Command {
"create" {pack [entry \$W.entry] -fill x \
-expand yes -pady 4 -side left}
"set" {\$W.entry insert 0 $Par}
"get" {return [\$W.entry get]}
}
}
It is also possible to relay on an existing entry widget procedure to create a new, more specific
one. The radiobox widget is used for example, to create a new entry widget that allows selecting
either the option left, center or right. The original radiobox widget is called with the set_choice
command immediately after the create command, to define the fixed list of selection options.
proc tepam::ad_form(rcl) {W Command {Par ""}} {
set Res [ad_form(radiobox) $W $Command $Par]
if {$Command=="create"} {
ad_form(radiobox) $W set_choice {left center right}
}
return $Res
}
Please consult the TEPAM package source file to find additional and more complex examples of entry
widget procedures.
VARIABLES
The argument_dialogbox is using two variables inside the ::tepam namespace:
argument_dialogbox
Application specific entry widget procedures can use this array variable to store their own
data, using as index the widget path provided to the procedure, e.g. argument_dialog-box($W,<sub_index>). argument_dialogbox($W,<sub_index>).
box($W,<sub_index>).
last_parameters
This array variable is only used by an argument dialog box when its context has been specified
via the -context attribute. The argument dialog box' position and size as well as its entered
data are stored inside this variable when the data are acknowledged and the form is closed.
This allows the form to restore its previous state once it is called another time.
To reuse the saved parameters not just in the actual application session but also in another
one, it is sufficient to store the last_parameter variable array in a configuration file which
is loaded the next time an application is launched.
SEE ALSO
tepam_introduction(n), tepam_procedure(n)
KEYWORDS
entry mask, parameter entry form
CATEGORY
Argument entry form, mega widget
COPYRIGHT
Copyright (c) 2009/2010, Andreas Drollinger
tepam 0.1.0 tepam::argument_dialogbox(n)
|
Сообщение о проблемах
Способ сообщить о проблеме с этой страницей руководства зависит от типа проблемы:
- Ошибки содержания
- Ошибки отчета в содержании этой документации к проекту Tcl.
- Отчеты об ошибках
- Сообщите об ошибках в функциональности описанного инструмента или API к Apple через Генератор отчетов Ошибки и к проекту Tcl через их страницу создания отчетов ошибки.
- Форматирование проблем
- Отчет, форматирующий ошибки в интерактивной версии этих страниц со ссылками на отзыв ниже.