In all the syntax descriptions below, the token or parent arguments designate the unique token which was returned when a view was initially created (either with the [hiview create] or the [hiview root] commands).
This command is used to insert one or several subviews in another view designated by its token as the parent argument. This can be undone later using the [hiview remove] command.
This command returns the list of all the child subviews of the token view. The child-parent relationship is established using the [hiview add] command.
Possible options and values are described in the Hiview options section below.
The type argument specifies the kind of control you want to create. The possible values are indicated in the first column of the types table above. In order to create a root window or dialog, one must use the [hiview root] command instead.
The [hiview create] command returns a token which uniquely identifies the new object and can be used in other commands.
The -parent argument lets you optionnally specify the parent for the newly created view. The parent can also be set later using the [hiview add] command. By default, an hiview object created with the [hiview create] command is initially visible. Visibility of hiviews is controlled by the -visibility option: this option can be specified on creation with the [hiview create] command or later with the [hiview configure] command.
Many other options can be specified. The following table indicates which creation options are applicable for a particular control.
This command can be used to close a window created with [hiview root] or to dispose of a particular view created with [hiview create]. This automatically disposes of the object it is applied to and of ''all its children''. The token will not be valid anymore, as well as the tokens of all the subviews.
This command can take three forms
The first form lets you specify a view to set the focus on inside some root window. The value of the root argument is the token of a root window and the value of the token argument is the token of the view which should be focused.
The second form returns the token of the currently focused view inside the root window designated by the root argument. The value of this argument should be the token of a root window.
The third form clears focus from the currently focused control in the root window given by the root argument. The window will be left such that no control is focused within it.
This command lets you hide a root window or a subview. It just makes it invisible. The opposite action is achieved with the [hiview show] command. In the case of a sheet or a drawer window, this command has the effect of sliding the window back inside the edge of the parent window it is attached to. Note that it is not possible to hide a dialog window: this raises an error. The built dialog is invisible until the [hivew show] command is invoked, then it is displayed as a movable modal dialog which blocks the execution until it is dismissed with [hivew delete].
This command is useful only for identification purpose. If no option is specified, it returns either "root" or "view" depending on the object represented by the token argument. In the case of a subview, the -class or -type options have the following meaning:
The possible values are given in the third and fourth columns of the types table above. In the case of a root view, the -class or -type options are synonym. If any of them is specified, the command returns the class number of the window. It is an integer number (known as the Window Class by the Window Manager) whose possible values are indicated in the following table:
This command returns a list of the current objects:
In order to get a list of the subviews included in a particular object, use the [hiview children] command instead.
Moves a view by a certain distance, relative to its current location. This affects a view's frame, but not its dimensions.
This command can be applied to root windows created with [hiview root] or to simple views created with [hiview create]. When a view is moved, all the subviews it contains are also moved.
If this command is invoked with the -view option, it returns the token of the parent view of the view specified by the token argument, or it raises an error if the view currently has no parent. The parent view, if it exists, could be another view or a root window. If this command is invoked with the -root option, it returns the token of the root window containing the view specified by the token argument, or it raises an error if the view is not currently installed in a root window. Invoking the command with no option is equivalent to using the -view option.
This command marks the view specified by the token argument as needing to be completely redrawn.
This command is the opposite of the [hiview add] command. It removes one or several views from their superview.
The kind argument can have one of the following values: dialog, document, drawer, float, help, overlay, plain, sheet, simple, toolbar, utility. The [hiview root] command returns a token which uniquely identifies the new object and can be used in other commands. The Roots description section below provides detailed information about the characteristics of the different kinds of root views and the specific options they support. It is important to note that a root window created with [hiview root] is initially invisible. You must explicitely invoke the [hiview show] command to display the window. Typically you would do this after you have installed all the hiview controls in your window. Visibility of root windows is controlled by the the [hiview show] and [hiview hide] commands. The following table recapitulates the options supported by the different root views on creation:
This command lets you show a root window or a subview. It just makes it visible. By default, the root views (created with the [hiview root] command) are initially visible, whereas the subviews (created with the [hiview create] command) are initially visible. The -parent and -w options concern the root windows of type sheet or drawer. They let you specifiy a parent window for the sheet or the drawer:
If no option is specified, the sheet or drawer window is attached to the current window (the topmost editing window).
The opposite action is achieved with the [hiview hide] command. When applied to a dialog window, this command runs the dialog: it blocks the execution of the Tcl script until the dialog is dismissed.
This command returns the token of a particular subview or a count of subviews. The view relative to which you want to find a particular subview is specified by the token argument. The last argument indicates exactly what you want to find. The possible values for this argument are:
token view. The first object is at index 0.
If there is no subview corresponding to the specified argument, the command raises an error. Caveat: the order of the children in a view is the reverse of the order in which they have been embedded in their parent: in other words, the first item in the list of chidren is the child that was last added. The notions of previous and next item refer to this order.
Views support two kinds of options:
If an option does not apply to a particular kind of view, it is just ignored by the [hiview create] or [hiview configure] commands. The next section gives information about common options which apply to most of the views. Some views also support additional options (either creation or configuration options) which are explained separately in the Views description section below.
Here are the common options which can be specified with any kind of subview using the [hiview create] command and can be modified later using the [hiview configure] command. These common options (except for the -parent and -constraints options) also apply to root views created with the [hiview root] command.
its parent's local coordinate system'' in the case of a subview, in screen coordinates in the case of a root view. Applying the -bounds option effectively moves a subview within its parent. The value is a four-element Tcl list containing the top, left, bottom, right coordinates of the bounding box.
root view or with a subview. This proc is executed when the root view or the subview receives a mouse click: in the case of an editable view (combo box, edit field, or search field) the proc is not invoked on a mouse click but rather when the user confirms the text that was entered in the view by pressing the Enter or the Return key. In the case of a text view, the command is triggered when the text has changed and the view looses the focus (for instance by clicking in another part of the window). When the proc declared with the -command option is invoked, the token of the corresponding view is passed as argument. You can specify an empty string in the -command option used with the [hiview configure] command in order to remove the command attached to a view.
four sides of a view. They are individually relative to the parent view's
edges. The value is a four-element Tcl list containing values 0 or 1 in
order to set a binding for the top, left, bottom, right edges
respectively. For instance, a value
possible values are 0 or 1.
associated with the view. This help text will be displayed if the mouse stays over the view for a short amount of time.
possible values are 0 or 1.
object. The parentship can also be set later using the [hiview add] command or suppressed using the [hiview remove] command. The parent of a view can be a root view or any other view. This option does not apply to root views.
title means depends on the kind of view it is applied to. Generally it designates the text accompanying the control (the name of a checkbox for instance). In the case of a root view, it designates the title of the window (if a title bar is present).
Here are common options which can be applied to any kind of subview (even if some of them make little sense for a particular view). They are named configuration options because they are manipulated with the [hiview configure] command. These options do not apply to root views.
displayed by some controls (static text, edit text, combo box and text view). The value of this option is a list of three integer numbers between 0 and 65535 corresponding to the red, green and blue components of the color. As a convenience, one can also specify the color using one of the predefined color names understood by AlphaX (''black, blue, cyan, green, magenta, red, white, yellow'').
Font option section below.
text displayed by some controls (static text, edit text, combo box and text view). The possible values are: default, left, center, right.
option is relevant for certain kinds of views such as the sliders, scrollbars, etc.
option is relevant for certain kinds of views such as the sliders, scrollbars, etc.
by some controls (static text, edit text, combo box and text view). The value for this option is the font size in points. This option does not work with edit fields and combo boxes on Mac OS X 10.4 (Tiger).
Style option section below.
This option is relevant for certain kinds of views such as the sliders, scrollbars, radio groups, etc. The value of this option is always constrained by the minimum and maximum values of the control (which can be manipulated with the -min and -max options respectively).
The -font option is supported by most of the controls. The value of this option is a constant corresponding to a system font: the text in subviews is drawn using one of these system fonts, not the fonts usually used in the text editor itself. The possible values are indicated in the first column of the table below. These constants are meta-font numbers, that is to say virtual font IDs mapped into the appropriate real font (or fonts), size, and style: this mapping is based on the system appearance (Aqua on Mac OS X), the string to be rendered, the language/script that the application is running in, and possibly other factors. It is important to note that, if you specify one of these fonts with the -font option, you won't have the possibility of setting the size with the -size option or to apply a style with the -style option.
The Views System Font is a font only used, by default, by DataBrowser controls (column views and list views).
The editable text views as well as the popup button and popup group box controls support a style option. The value for this option is an additive value made of some of the following constants:
Note that the -style option is a configuration option, not a creation option, and it does not apply to root views. This option does not work with edit fields and combo boxes on Mac OS X 10.4 (Tiger).
Additionnally there is a -variant option which is supported by many (but not all) controls and which lets you specify different variants for the size of the control. The possible values for this option (when applicable) are indicated in the first column of the table below:
Even if a control supports size variants, it does not necessarily support all of them. This can also vary among different versions of the System (10.3 or 10.4). For instance, the Check Box, Combo Box, Radio Button, Scroll Bar, Slider and Tab controls currently support the small size. The Progress Bar and Round Button controls currently support the large size. The Tab controls support the mini size. The Bevel Button control supports normal, small and large. The -variant option does not apply to root views. As of OS X 10.4, size variants are supported by the following 17 controls: bevelbutton, chasingarrows, checkbox, combobox, disclosurebutton, littlearrows, popuparrow, popupbutton, progressbar, pushbutton, radiobutton, roundbutton, scrollbar, scrollview, searchfield, slider, tabbedview
Two options are available to designate an icon or an image:
See the [Commands.ToolbarCommand] page on this wiki for a table of the main predefined codes provided by the system and the [Commands.IconrefCommand] page which documents the [iconref] command used to register custom icons in AlphaTcl.
image depends on the command it is used with. For instance, with the
[hiview create imageview] command, the file
should be a JPEG or a PNG file. Currently, the ''bevelbutton, icon, imageview, imagewell, pushiconbutton, roundbutton'' controls can have images: