From AlphaWiki

Commands: HiviewSubcommands

Syntax of subcommands

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

hiview add

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.

hiview children

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.

hiview configure

Possible options and values are described in the Hiview options section below.

hiview create

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.

ViewOptions
bevelbutton-behavior, -bounds, -command, -constraints, -enable, -help, -iconref, -items, -menu, -menuPlacement, -multiValue, -parent, -title, -variant, -visible
chasingarrows-bounds, -command, -constraints, -enable, -help, -parent, -title, -variant, -visible
checkbox-autoToggle, -bounds, -command, -constraints, -enable, -help, -parent, -title, -value, -variant, -visible
checkgroupbox-autoToggle, -bounds, -command, -constraints, -enable, -help, -parent, -primary, -title, -value, -visible
clock-bounds, -clockFlags, -clockType, -command, -constraints, -enable, -help, -parent, -title, -visible
columnview-bounds, -command, -constraints, -enable, -help, -multiValue, -parent, -title, -visible
combobox-attributes, -bounds, -command, -constraints, -enable, -help, -items, -parent, -text, -title, -variant, -visible
disclosurebutton-autoToggle, -bounds, -command, -constraints, -enable, -help, -parent, -title, -value, -variant, -visible
disclosuretriangle-autoToggle, -bounds, -command, -constraints, -drawTitle, -enable, -help, -orientation, -parent, -title, -value, -visible
edittext-bounds, -command, -constraints, -enable, -help, -parent, -password, -text, -title, -visible
groupbox-bounds, -command, -constraints, -enable, -help, -parent, -primary, -title, -visible
icon-bounds, -command, -constraints, -enable, -help, -iconref, -parent, -title, -visible
imageview-bounds, -command, -constraints, -enable, -help, -iconFile, -parent, -title, -visible
imagewell-bounds, -command, -constraints, -enable, -help, -iconref, -parent, -title, -visible
listview-attributes, -bounds, -command, -constraints, -enable, -help, -multiValue, -num, -parent, -labels, -title, -visible
littlearrows-bounds, -command, -constraints, -enable, -help, -increment, -max, -min, -parent, -title, -value, -variant, -visible
placard-bounds, -command, -constraints, -enable, -help, -parent, -title, -visible
popuparrow-bounds, -command, -constraints, -enable, -help, -orientation, -parent, -title, -variant, -visible
popupbutton-bounds, -command, -constraints, -enable, -help, -items, -menu, -parent, -title, -titleWidth, -variableWidth, -variant, -visible
popupgroupbox-bounds, -command, -constraints, -enable, -help, -items, -menu, -parent, -primary, -title, -titleWidth, -variableWidth, -visible
progressbar-bounds, -command, -constraints, -determinate, -enable, -help, -max, -min, -parent, -title, -value, -variant, -visible
pushbutton-bounds, -command, -constraints, -enable, -help, -parent, -title, -variant, -visible
pushiconbutton-bounds, -command, -constraints, -enable, -help, -iconAlignment, -iconref, -parent, -title, -visible
radiobutton-autoToggle, -bounds, -command, -constraints, -enable, -help, -parent, -title, -value, -variant, -visible
radiogroup-bounds, -command, -constraints, -enable, -help, -parent, -title, -visible
relevancebar-bounds, -command, -constraints, -enable, -help, -max, -min, -parent, -title, -value, -visible
roundbutton-bounds, -command, -constraints, -enable, -help, -iconref, -parent, -title, -variant, -visible
scrollbar-bounds, -command, -constraints, -enable, -help, -trackingProc, -max, -min, -parent, -title, -value, -variant, -visible
scrollview-attributes, -bounds, -command, -constraints, -enable, -help, -parent, -title, -variant, -visible
searchfield-bounds, -command, -constraints, -enable, -help, -parent, -menu, -text, -title, -variant, -visible
segmentedview-bounds, -command, -constraints, -enable, -help, -num, -parent, -icons, -labels, -title, -visible
separator-bounds, -command, -constraints, -enable, -help, -parent, -title, -visible
slider-bounds, -command, -constraints, -enable, -help, -max, -min, -num, -orientation, -parent, -title, -trackingProc, -value, -variant, -visible
statictext-bounds, -command, -constraints, -enable, -help, -parent, -text, -title, -visible
tabbedview-bounds, -command, -constraints, -direction, -enable, -help, -num, -parent, -icons, -labels, -title, -variant, -visible
textview-attributes, -bounds, -command, -constraints, -enable, -help, -parent, -title, -visible
userpane-bounds, -command, -constraints, -enable, -help, -parent, -title, -visible
webview-bounds, -command, -constraints, -enable, -help, -parent, -title, -visible
windowheader-bounds, -command, -constraints, -enable, -help, -listHeader, -parent, -title, -visible

hiview delete

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.

hiview focus

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.

hiview hide

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

hiview kind

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:

ClassWindow
4Dialog Window
5Floating Window
6Document Window
8Utility Window
10Help Window
11Sheet Window
12Toolbar Window
13Plain Window
14Overlay Window
18Simple Window
20Drawer Window

hiview list

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.

hiview move

Moves a view by a certain distance, relative to its current location. This affects a view's frame, but not its dimensions.

dx
is the horizontal distance to move the view. Negative values move the view to the left, positive values to the right.
dy
is the vertical distance to move the view. Negative values move the view upward, positive values downward.

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.

hiview parent

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.

hiview refresh

This command marks the view specified by the token argument as needing to be completely redrawn.

hiview remove

This command is the opposite of the [hiview add] command. It removes one or several views from their superview.

hiview root

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:

dialogdocumentdrawerfloathelpoverlayplainsheetsimpletoolbarutility
-alpha***********
-bounds***********
-closeBox***
-collapseBox***
-command***********
-direction*
-help***********
-metal**
-resizable*****
-sidebar**
-title***********
-visible***********
-zoomBox***

hiview show

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.

hiview subview

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.

hiview valid

This command indicates if an hiroot or hiview token is still valid. It returns 1 if the token is valid, 0 otherwise.

Hiview options

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.

Common creation options

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.

-bounds
the -bounds option corresponds the bounds of a view ''relative to

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.

-command
the -command option lets you specify a Tcl proc to associate with a

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.

-constraints
the -constraints option lets you specify layout bindings for all

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 {0 1 0 1} means that the left and right edges of the view are bound to the left and right edges of the superview, and the top and bottom edges are not bound to the top and bottom edges of the superview. In this case, if the superview is resized, the left and right edges will move accordingly while the top and bottom ones will remain unchanged.

-enable
the -enable option is used to enable or disable an item. The

possible values are 0 or 1.

-help
the -help option lets you specify the text of a short help tag

associated with the view. This help text will be displayed if the mouse stays over the view for a short amount of time.

-hilite
the -hilite option is used to hilite or unhilite an item. The

possible values are 0 or 1.

-parent
the -parent option lets you specify a parent for the newly created

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
the -title option lets you specify the title of a view. What

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

-visible
the -visible option is used to show or hide an item. The

possible values are 0 or 1. The default value is 1 in the case of subviews, 0 in the case of root views.

Common configuration options

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.

-color
the -color option can be used to set the color of the text

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
the -font option is discussed in the

Font option section below.

-justify
the -justify option can be used to set the justification of the

text displayed by some controls (static text, edit text, combo box and text view). The possible values are: default, left, center, right.

-max
the -max option lets you specify the maximum value of a view. This

option is relevant for certain kinds of views such as the sliders, scrollbars, etc.

-min
the -min option lets you specify the minimum value of a view. This

option is relevant for certain kinds of views such as the sliders, scrollbars, etc.

-size
the -size option can be used to set the size of the text displayed

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
the -style option is discussed in the

Style option section below.

-value
the -value option lets you specify the current value of a view.

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

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.

ValueDescription
-1Big System Font
-2Small System Font
-3Small Bold System Font
-4View System Font
-5Mini System Font

The Views System Font is a font only used, by default, by DataBrowser controls (column views and list views).

The -style option

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:

ValueDescription
0normal
1bold
2italic
4underline
32condense
64extend

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

The -variant option

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:

ValueDescription
normaldefault drawing variant
largelarge drawing variant
smallsmall drawing variant
miniminiature drawing variant

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

Image support options

Two options are available to designate an icon or an image:

-iconref type
this option expects a registered four-character type designating an icon.

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.

-iconFile filename
this option expects an absolute path to an image file. The format of the

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:

Retrieved from http://alphatcl.sourceforge.net/wiki/pmwiki.php/Commands/HiviewSubcommands
Page last modified on September 30, 2009, at 08:55 AM