• Hiview reference

• Hiview Reference

• Hiview introduction
• Hiview subcommands
• Hiview root windows
• Hiview subviews
• Hiview Rects package?

file Hiview Help.html accessible from the Help menu in AlphaX and in the following pages on the wiki:

• HiviewIntro
• HiviewSubcommands
• HiviewRoots
• HiviewSubviews
• HiviewRects?

The [hiview] command has been introduced in version 8.2b12 of AlphaX.

• each element of a dialog or window is created individually and can be manipulated independently from the others

• all the subviews can execute Tcl scripts. They all support a -command option which lets you specify a Tcl command which will be executed when the view is clicked or when an editable field is validated
• this model is not limited to dialogs: the [hiview] command allows to create various kinds of windows (dialog, document, drawer, float, help, overlay, plain, sheet, simple, toolbar, utility).

The [hiview] command is entirely documented in the file Hiview Help.html accessible from the Help menu in AlphaX.

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.

-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 second 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 (if any), the language/script that the application is running in, and possibly other factors. This means in particular that if you set one of these fonts with the -font option, you won't be able to set the size with the -size option or to apply a style with the -style option.

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.

• each element of a dialog or window is created individually and can be manipulated independently from the others

• all the subviews can execute Tcl scripts. They all support a -command option which lets you specify a Tcl command which will be executed when the view is clicked or when an editable field is validated * this model is not limited to dialogs: the [hiview] command allows to create various kinds of windows (dialog, document, drawer, float, help, overlay, plain, sheet, simple, toolbar, utility).

• control objects, also called subviews, which are created with the [hiview create] command

• if the -class option is specified, the command returns the class ID of the control. It is a string in the form of a reversed domain identifier, like, for instance, com.apple.HIBevelButton for a bevel button.
• if the -type option is specified, the command returns the type of the control. It is a four-char code like, for instance, bevl for a bevel button.

• with the roots argument, this is the list of all windows created with the [hiview root] command
• with the views argument, this is the list of all the views created with the [hiview create] command In order to get a list of the subviews included in a particular object, use the [hiview children] command instead.

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.

• the -parent option lets you specify the token of the a parent root view created with the [hiview root] command
• the -w option lets you specify an ordinary editing window opened by AlphaX.

• next returns the subview placed after the token subview in their parent. It can be used to cycle among all the views contained in the same superview.
• previous returns the subview placed before the token subview in their parent. It can be used to cycle backward among all the views contained in the same superview.
• a numeric value lets you find the index-th subview inside the token view. The first object is at index 0.
• count returns the number of subviews of the token view.

If there is no subview corresponding to the specified argument, the command raises an error.

• creation options are options which can be set at creation time, i-e with the [hiview create] command. Some of them (but not all) can be modified later using the [hiview configure] command. All the creation options have default values.
• configuration options are options which can be set using the [hiview configure] command. There are common options which apply to almost all the controls and, in some cases, extra options which make sense only for a particular one. Configuration options do not have default values.

If an option does not apply to a particular kind of view, it is just ignored by the [hiview create] or [hiview configure] commands.

Introduction

HIView is a new object-oriented view system available for implementing Carbon user interface elements. Beginning with Mac OS X 10.2, all of the standard controls can now be considered views. The conceptual presentation of HIViews can be found on the Apple's Developer Connection in the HIView Doc [http://developer.apple.com/documentation/Carbon/Conceptual/HIViewDoc/]. It explains the concepts behind the HIView model, covering the view embedding hierarchy (child-parent relationship) and composited drawing.

The model proposed in AlphaX by the [hiview] command parallels this view system. This approach is different from the one adopted by the [dialog] command. The main features are:

• each element of a dialog or window is created individually and can be

manipulated independently from the others

• the properties of a subview can be modified programmatically
• all the subviews can execute Tcl scripts. They all support a

-command option which lets you specify a Tcl command which will be executed when the view is clicked or when an editable field is validated

• this model is not limited to dialogs: the [hiview] command allows to

create various kinds of windows (dialog, document, drawer, float, help, overlay, plain, sheet, simple, toolbar, utility).

Parents and children

The [hiview] command makes a distinction between two kinds of objects:

• root objects which are created with the [hiview root] command
• control objects, also called subviews, which are created with the

[hiview create] command The root objects are basically windows and dialogs. The subviews can contain other subviews and can be embedded in some root view. When a view A is embedded inside a view B, B is said to be the parent (or superview) of A and A is a child of B. The root objects are the top of the hierarchy: subviews can exist independently from any root view but will be displayed only in some root view. It is always possible to add or remove subviews from a parent or a root view, to modify the child-parent relationship.

The coordinate system

The [hiview] command simplifies the process of placing items within a view by using a coordinate system that is always view-relative: the placement of objects within a view is done relative to that view, that is to say, the origin is in the upper left corner of the view. The coordinates of items in the view won’t change even if the view itself is moved. This relative coordinate system makes it much easier to calculate the position of views and the objects within them.

Root views of course do not use relative coordinates since they are at the top of the hierarchy and have no parent or superview: the positions for root views are given in absolute screen coordinates. In both cases, the origin is the upper left corner, the y-axis is oriented downwards, the x-axis is oriented to the right.

Several [hiview] subcommands support a -bounds option which applies both to root views and subviews: in the case of a root view, the value of the -bounds option is in global (screen) coordinates; in the case of a subview, it is in frame coordinates, i-e coordinates relative to the view's superview. This value is always a four-element list corresponding to the top, the left, the bottom and the right coordinates of the rectangular border of the view: top and left are respectively the y and the x coords of the upper left corner, bottom and right are respectively the y and the x coords of the lower right corner. For instance, one would write:

 
 	hiview configure $v -bounds [list 10 20 130 300]

to position the view $v inside its parent at the point of coords (20, 10) as a rectangle of width 280 (= 300 - 20) and height 120 (= 130 - 10).

Types of views

The following controls can be defined. The value in the left column is the keyword which must be passed as an argument to the [hiview create] command.

Some controls are available only in recent versions of the system. Here is a table of the minimum requirements:

Synopsis

The [hiview] command uses the following formal syntax:

hiview subcommand options The subcommand argument specifies the type of action to perform: creating a view, embedding a view in a parent view, removing a view from its parent, getting or setting properties of subviews, etc.

Quick start example

Here is a simple example to give a first feeling of how things work:

 
 	# Create a root window
 	set root [hiview root document -bounds {150 150 600 450} -title "Hiview Sample" -resizable 0]

 	# Create some subviews
 	# A scroll view which will contain an image
 	set scrv [hiview create scrollview -bounds {20 20 300 280}]
 	set imgfile [file join $APPLICATION Contents Resources about.png]
 	set imgv [hiview create imageview -iconFile $imgfile]

 	# A combo box
 	set cbbox [hiview create combobox -bounds {320 60 340 190} -items [list item1 item2 item3]]

 	# A static text
 	set sttxt [hiview create statictext -bounds {360 40 380 270} -text "http://alphatcl.sourceforge.net"]
 	hiview configure $sttxt -color blue -style 4

 	# A live clock!
 	set clock [hiview create clock -bounds {380 90 400 270} -clockFlags 3 -clockType 1]

 	# A button
 	set okbut [hiview create pushbutton -bounds {417 210 437 283} -title "Click"]

 	# Embed the subviews into the window
 	hiview add $root $okbut $scrv $cbbox $sttxt $clock

 	# Embed the image into the scroll view
 	hiview add $scrv $imgv

 	# Display the window
 	hiview show $root

This example makes use of explicit bounds for each subview. It will be redefined in the HiviewRects package section at the end of this document, based on the HiviewRects procs which let you move and resize the bounds without making any explicit calculations.

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

• hiview add parent token ?token...?

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

• hiview children token

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

• hiview configure token ?option value? ?option value...?

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

hiview create

• hiview create type ?-parent token? ?option value? ?option value...?

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.

hiview delete

• hiview delete token

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

• hiview focus set root token
• hiview focus get root
• hiview focus clear root

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

• hiview hide token

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.

hiview kind

• hiview kind ?(-class|-type)? token

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:

• if the -class option is specified, the

command returns the class ID of the control. It is a string in the form of a reversed domain identifier, like, for instance, com.apple.HIBevelButton for a bevel button.

• if the -type option is specified, the

command returns the type of the control. It is a four-char code like, for instance, bevl for a bevel button. 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:

hiview list

• hiview list (roots|views)

This command returns a list of the current objects:

• with the roots argument, this is the list of all windows

created with the [hiview root] command

• with the views argument, this is the list of all the views

created with the [hiview create] command In order to get a list of the subviews included in a particular object, use the [hiview children] command instead.

hiview move

• hiview move token dx dy

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

• hiview parent ?(-root|-view)? token

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

• hiview refresh token

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

hiview remove

• hiview remove parent token ?token...?

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

hiview root

• hiview root kind ?option value? ?option value...?

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:

hiview show

• hiview show ?(-w win|-parent parentToken)? token

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:

• the -parent option lets you specify the token of the a

parent root view created with the [hiview root] command

• the -w option lets you specify an ordinary editing window

opened by AlphaX. 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.

hiview subview

• hiview subview (first|last|next|previous|index) token

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:

• first returns the first subview of the token view.
• last returns the last subview of the token view.
• next returns the subview placed after the token

subview in their parent. It can be used to cycle among all the views contained in the same superview.

• previous returns the subview placed before the token

subview in their parent. It can be used to cycle backward among all the views contained in the same superview.

• a numeric value lets you find the index-th subview inside the

token view. The first object is at index 0.

• count returns the number of subviews of the token

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 options

Views support two kinds of options:

• creation options are options which can be set at creation

time, i-e with the [hiview create] command. Some of them (but not all) can be modified later using the [hiview configure] command. All the creation options have default values.

• configuration options are options which can be set using the

[hiview configure] command. There are common options which apply to almost all the controls and, in some cases, extra options which make sense only for a particular one. Configuration options do not have default values. 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.

User pane

User panes provide a generic container for embedding other controls. They support the usual common options (''-bounds, -command, -constraints, -enable, -help, -visible'') passed in the [hiview create] command. They have no specific options.

Web view

The web view lets you display HTML pages. It has no specific creation options but supports the usual common options. The web view also accepts one extra option which can be manipulated using the [hiview configure] command:

• the -url option lets you specify an URL to load an HTML file

and display it in the web view.

Window header

Creation options:

• the -listHeader option lets you specify a boolean indicating

whether the control is to draw as a list header: if this option is set to 1, there is no bottom line. The default value is 0. The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -listHeader, -visible. The -listHeader option can later be modified with [hiview configure].

Reference table

As a reference, the following table indicates the controls supporting the various creation or configuration options.

Hiviews and bindings

How do the hiviews and the bindings fit together ? In AlphaX, bindings are key combinations which can trigger an action defined by a Tcl proc. When a root window defined with the [hiview root] command contains editable views (that is to say views which accept text input, such as a combo box, an edit field, a search field or a text view), and when one of these editable views has the focus, then only bindings containing the Command key or the Control key as a modifier are executed: other bindings associated with a simple key or involving the Option key or the Shift key are ignored so that the key combination is passed normally to the editable view. This allows keys like the Return key, the Delete key and the Tabulation key to be handled as expected by the default handlers attached to the views. If no editable view currently has the focus, then all the bindings are active (unless a modal dialog is running). This brings to another issue concerning activation. When an editable field in a document window has the focus and the user switches to another window, the focus is removed automatically. This happens with root windows of type ''document, drawer, plain, sheet and simple. But windows of type float'' and utility are different: they are always active, so if an editable view has the focus in this kind of window, one must remove it manually when it is not needed anymore: this can be done by clicking anywhere in the corresponding floating window. Clicking in another window (including the usual AlphaX editing windows) will also automatically remove the focus. Note that root windows of type help, overlay and toolbar are never activated by the Window Manager so it is useless to have an editable field in them. Focus can also be manipulated programmatically (installed or cleared) using the [hiview focus] command.

The HiviewRects package

The AlphaTcl library contains a new package HiviewRects which defines utility procs designed to easily manipulate the frame of the subviews. It is useful to specify the positions of the subviews without making any explicit calculations on the bounds and to assemble the elements of a root window or the subelements of a container. All the procs are described in the file hiviewRects.tcl located in the SystemCode directory. They usually accept, as an optional argument, the name of a variable containing the coordinates of a rectangle and return the modified coordinates. One can also declare the name of a default rectangle at the beginning of a script and then all the procs will apply, by default, to this rectangle. Here is a series of instructions to demonstrate how these procs work:

 
     «» hi::defaultRect vb
     vb
     «» hi::initRect
     0 0 0 0
     «» hi::sizeRect 150 20
     0 0 20 150
     «» hi::moveRect 10 10
     10 10 30 160
     «» hi::lf
     43 10 63 160
     «» hi::centerRect 300 0
     43 75 63 225
     «» hi::incrRect 15 10
     43 75 73 240
     «» hi::vskip 50
     93 75 123 240
     «» hi::width
     165
     «» hi::height
     30

The [hi::lf] proc is the equivalent of a line feed: it moves the rectangle vertically by the amount of its previous height, augmented by an interspace (equal to 13 pixels by default and controlled, if necessary, by the [hi::margin] proc). This proc can also be applied horizontally: [hi::lf h] would move the rectangle horizontally by the amount of its previous width, augmented by the interspace. Here is, for example, how one could redefine the example given in the Quick Start section using the HiviewRects package. The default rectangle here is named vb and it is resized or moved for each subview contained in this window. The subviews are thus positionned relatively to each other:

 
     # Window bounds rect
     hi::setRect 150 150 580 450 wb

     # View bounds rect
     hi::defaultRect vb
     hi::initRect

     # Create a root window
     set root [hiview root document -bounds [hi::rect wb] -title "Hiview Sample" -resizable 0]

     # Create some subviews
     # A scroll view which will contain an image
     hi::lf
     hi::sizeRect 280 260
     hi::centerRect [hi::width wb] 0
     set scrv [hiview create scrollview -bounds [hi::rect]]
     set imgfile [file join $APPLICATION Contents Resources about.png]
     set imgv [hiview create imageview -iconFile $imgfile]

     # A combo box
     hi::lf
     hi::sizeRect 150 20
     hi::centerRect [hi::width wb] 0
     set cbbox [hiview create combobox -bounds [hi::rect] -items [list item1 item2 item3]]

     # A static text
     hi::lf
     hi::sizeRect 250 20
     hi::moveRect -10 0
     set sttxt [hiview create statictext -bounds [hi::rect] -text "http://alphatcl.sourceforge.net"]
     hiview configure $sttxt -color blue -style 4

     # A live clock!
     hi::lf
     hi::moveRect 50 0
     set clock [hiview create clock -bounds [hi::rect] -clockFlags 3 -clockType 1]

     # A button
     set okbut [hiview create pushbutton -bounds [hi::okButtonRect $wb] -title "Click"]

     # Embed the subviews into the window
     hiview add $root $okbut $scrv $cbbox $sttxt $clock

     # Embed the image into the scroll view
     hiview add $scrv $imgv

     # Display the window
     hiview show $root

Placard

The placard view has no specific creation or configuration options. The usual common options are supported. The -bounds option should be specified to set the dimensions of the placard.

Popup arrow

A popup arrow is just a visual element similar to the little arrows displayed on some popup elements. Creation options:

• the -orientation option lets you specify the direction the arrow

is pointing to. The possible values are: 0 (east), 1 (west), 2 (north), 3 (south).

• the -variant option lets you specify the size of the control.

Popup arrow controls support two sizes: normal or small. See the -variant option section above. The following options can be specified with the [hiview create] command: -orientation, -variant, -bounds, -command, -constraints, -enable, -help, -visible. The -orientation, -variant options cannot be modified with [hiview configure].

Popup button

Creation options:

• the -menu option lets you specify the token of a menu. The value

is a token obtained with the [menuRef create] command (see the MenuRefCommand page on the wiki).

• the -titleWidth option lets you specify the width in pixels of

the popup button title. One can pass the value -1 to let the control calculate the width automatically (this is the default).

• the -variableWidth option lets you specify whether the width of

the control is allowed to vary according to the width of the selected menu item text, or should remain fixed to the original control bounds width. The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -menu, -menuValue, -title, -titleWidth, -variableWidth, -visible. The -menu, -menuValue options can be modified with [hiview configure] but the -titleWidth, -variableWidth options can't. The popup button supports extra options which can be manipulated using the [hiview configure] command:

• the -size option lets you specify a size in points for the title.
• the -style option lets you specify a style bitfield

indicating the font style of the title. The possible values are explained in the -style option section.

• the -menuValue option lets you specify the index of the

currently selected item in the menu. This index is 0-based. If no item is considered selected, the value of this option is -1. Note that the index of the currently selected item in the menu can also be obtained with the -value option: the difference is that this value is 1-based. The value is constrained by the minimum and maximum values of the control (controlled by the -min and -max options). It is thus important that the minimum value be set to 0 and the maximum value be set to the number of items in the menu: the [hiview] command takes care of setting this value properly when the menu is attached but if the number of items in the menu is modified, you have to update the maximum accordingly.

Popup group box

Creation options:

• the -menu option lets you specify the token of a menu. The value

is a token obtained with the [menuRef create] command (see the MenuRefCommand page on the wiki).

• the -primary option lets you specify whether to create a primary

or secondary group box. Possible values are 0 or 1. The default is 1.

• the -variableWidth option lets you specify whether

the popup button should have a variable-width or a fixed-width title. Possible values are 0 or 1. The default is 1.

• the -titleWidth option lets you specify the width in pixels of

the popup button title. One can pass the value -1 to let the control calculate the width automatically (this is the default). The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -menu, -menuValue, -primary, -title, -titleWidth, -variableWidth, -visible. The -menu, -menuValue options can be modified with [hiview configure] but the -primary, -titleWidth, -variableWidth options can't. The popup group box supports extra options which can be manipulated using the [hiview configure] command:

• the -size option lets you specify a size in points for the title.
• the -style option lets you specify a style bitfield

indicating the font style of the title. The possible values are explained in the -style option section.

• the -menuValue option lets you specify the index of the

currently selected item in the menu. This index is 0-based. If no item is considered selected, the value of this option is -1. The same remarks made in the Popup Button section concerning the -value option also apply to the popup group box.

Progress bar

Creation options:

• the -determinate option is used to select the progress bar's

type. The possible values are 0 (indeterminate) or 1 (determinate). In a determinate progress bar, the fill moves from left to right and should fill in completely before it is dismissed. An indeterminate progress bar displays a spinning striped cylinder to indicate an ongoing process. The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -determinate, -enable, -help, -max, -min, -value, -visible. The -determinate options can also be modified later with [hiview configure]. The progress bar control supports one extra option which can be manipulated using the [hiview configure] command:

• the -animate option lets you turn the animation on (1) or off (0).

Push button

The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -title, -visible. The push button control supports two extra options which can be manipulated using the [hiview configure] command:

• the -cancel option lets you give the button the properties of

a Cancel button. Possible values are 0 or 1.

• the -default option lets you give the button the properties of

a default button (a button whose selection is equivalent to pressing the Return key). Possible values are 0 or 1.

Push button with icon

Creation options:

• the -iconalignment option lets you specify the alignment of the

icon with respect to the text. Possible values are 0 (icon on left) or 1 (icon on right). By default the icon is displayed on the left.

• the -iconref option lets you specify a four-character code

designating a registered icon. See the Image support section above. The following options can be specified with the [hiview create] command: -iconAlignment, -iconref, -bounds, -command, -constraints, -enable, -help, -title, -variant, -visible. The -iconref option can be modified with [hiview configure] but the -iconalignment option cannot.

Radio button

Creation options:

• the -autoToggle option lets you specify whether this control

should have auto-toggle behavior. If true, the control will automatically toggle between on and off states when clicked. This parameter should be false if the control will be embedded into a radio group control; in that case, the radio group will handle setting the correct control value in response to a click. Possible values are 0 or 1. The default is 1. The following options can be specified with the [hiview create] command: -autoToggle, -bounds, -command, -constraints, -enable, -help, -title, -value, -visible. The -autoToggle options cannot be modified with [hiview configure].

Radio group

This control implements a radio group. It has no visible representation but it is an embedding control and you should only embed radio buttons within it. As radio buttons are embedded into it, the group sets up its value, min, and max to represent the number of embedded items. The current value of the control is the index of the sub-control that is the current on radio button. One can later change the currently selected button programmatically using the -value option with the [hiview configure] command.

Note: when creating radio buttons for use in a radio group control, you should not use the autoToggle version of the radio button: this means you should define the radiobuttons with an explicit -autoToggle 0 option. The radio group control will handle toggling the radio button values itself.

The radio group view has no specific creation options. The usual common options are supported. Note that the -value option has no effect on creation since the radio buttons will be embedded only after the group is created.

Relevance bar

The relevance bar view has no specific creation options. The values are set using the -max, -min, -value options with the [hiview create] or [hiview configure] commands.

Round button

Creation options:

• the -iconref option lets you specify a four-character code

designating a registered icon. In that case, the control is not drawn as a round button: instead the icon itself becomes clickable. See the Image support section above.

• the -variant option lets you specify the size of the button. Round

buttons support two sizes: normal (20 pixel diameter button) or large (25 pixel diameter button). See the -variant option section above. The following options can be specified with the [hiview create] command: -iconref, -variant, -bounds, -command, -constraints, -enable, -help, -variant, -visible. The -iconref option can be modified with [hiview configure] but the -variant option can't.

Scroll bar

Creation options:

• the -trackingProc option lets you implement live tracking and

specify a Tcl proc to execute repeatedly while the user scrolls the view.

• the -variant option lets you specify the size of the visible

area of the scroll bar content. See the ''((rf varopt )) -variant option section'' above. The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -max, -min, -trackingProc, -value, -variant, -visible. The -trackingProc option can be modified with the [hiview configure] command but the -variant option can't. When the proc declared with the -trackingProc option is invoked, the token of the corresponding view is passed as argument. So the proc should have the following prototype:

 
     proc myTrackingProc {token} {
         # do something
     }

If you do not specify a -trackingProc option, you don't get live tracking: instead, the movements of the dragged thumb are indicated by a ghost thumb. When the mouse button is released, you can retrieve the value of the scrollbar with the [hiview configure] command using the usual -value option. You can pass an empty string to the -trackingProc option in order to remove the tracking proc attached to a view. You can also attach a command to the scrollbar using the -command option. The proc declared with this option is invoked after the view has been scrolled.

Scroll view

Creation options:

• the -attributes option lets you specify which scroll bars should be

drawn (horizontal and/or vertical). Possible values are indicated in the table below. At least one scrollbar should be specified. The default value is 3: both scrollbars are drawn by default.

The following options can be specified with the [hiview create] command: -attributes, -command, -constraints, -enable, -help, -variant, -visible. The -attributes, -variant options cannot be modified with [hiview configure]. The small variant draws the view with small scrollbars. Variants large and mini are not supported and draw as normal.

Search field

Creation options:

• the -attributes option lets you specify some characteristics of

the search field. Possible values are indicated in the table below: the default value is 0.

• the -text option lets you specify the text displayed by

the control. The following options can be specified with the [hiview create] command: -attributes, -bounds, -command, -constraints, -enable, -help, -text, -visible. The -text option can be modified with [hiview configure] but the -attributes option can't. The value of the -attributes option is an additive flag composed of the following constants:

If a menu is associated with the search field, the SearchIcon attribute is implicitly set and the search icon will display with a menu disclosure badge.

Segmented view

The segmented view supports the following creation options:

• the -num option lets you specify the number of segments in the view. The default value is 1.
• the -icons option lets you specify a list of iconrefs for

each of the segments. An iconref is a four-character code designating a registered icon. See the Image support section above. The list of iconrefs should have as many elements as there are segments in the view. Specify an empty string if you want no icon for a segment.

• the -labels option lets you specify a list of labels for

each of the segments. The list of labels should have as many elements as there are segments in the view. The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -num, -icons, -labels, -variant, -visible. The -num, -icons, -labels options cannot be modified with [hiview configure]. The segmented view can be considered as a set of buttons with the same behavior as a group of radio buttons. The value of the segmented view is the index of the currently selected segment: it can be manipulated with the [hiview configure] command using the -value option. Labels and icons are mutually exclusive: in case both have been specified, labels have precedence over icons. Note that the number of segments is stored in the maximum value of the control and can be manipulated with the [hiview configure] command using the -max option.

Separator

The separator view has no specific creation options. The usual common options are supported. The -bounds option should be specified to set the dimensions of the separator. It is possible to draw a vertical separator: separator lines determine their orientation (horizontal or vertical) automatically based on the relative height and width of their rectangle.

Slider

Creation options:

• the -num option lets you specify the number of tick

marks to draw along the slider. This value can't be modifeid after the control is created. The control rectangle must be large enough to accomodate the tick marks.

• the -orientation option lets you specify the orientation of the

thumb. The possible values are 0 (points down or right), 1 (points up or left) or 2 (does not point).

• the -trackingProc option lets you implement live tracking and

specify a Tcl proc to execute repeatedly while the user moves the slider. The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -max, -min, -num, -orientation, -trackingProc, -value, -visible. The -trackingProc option can be modified with the [hiview configure] command but the -num, -orientation options can't. When the proc declared with the -trackingProc option is invoked, the token of the corresponding view is passed as argument. So the proc should have the following prototype:

 
     proc myTrackingProc {token} {
         # do something
     }

If you do not specify a -trackingProc option, you don't get live tracking: instead, the movements of the dragged thumb are indicated by a ghost thumb. When the mouse button is released, you can retrieve the value of the scrollbar with the [hiview configure] command using the usual -value option. You can pass an empty string to the -trackingProc option in order to remove the tracking proc attached to a view. You can also attach a command to the slider using the -command option. The proc declared with this option is invoked after the slider has been moved.

Static text

Creation options:

• the -text option lets you specify the text displayed by the control.

The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -text, -visible. The -text options cannot be modified with [hiview configure]. The static text control supports two extra options which can be manipulated using the [hiview configure] command:

• the -multiLine option lets you specify whether the control draws

its text in multiple lines if the text is too wide for the control bounds. Possible values are 0 or 1. If the value is 0, then the control always draws the text in a single line.

• the -truncate option is used to get or set the control's text

truncation style. The possible values are: 0 (no truncation, the text is just clipped to the dimensions of the rectangle), 1 (truncation at the end), or 2 (truncation in the middle). This option makes sense only if -multiLine is set to 0. One must set the truncation value before specifying the text. Static text controls also support the text style options ''-color, -justify, -size, -style which are described in the Common configuration options'' section.

Tabbed view

Creation options:

• the -direction option lets you specify the edge along which the

tabs are displayed. Possible values are: 0 (top), 1 (bottom), 2 (right), 3 (left).

• the -num option lets you specify the number of tabs. The

default value is 1.

• the -icons option lets you specify a list of iconrefs for

each of the tabs. An iconref is a four-character code designating a registered icon. See the Image support section above. The list of iconrefs should have as many elements as there are tabs in the view. Specify an empty string if you want no icon for a tab.

• the -labels option lets you specify a list of labels for

each of the tabs. The list of labels should have as many elements as there are tabs in the view. The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -direction, -enable, -help, -num, -icons, -labels, -variant, -visible. The -direction, -num, -icons, -labels, -variant options cannot be modified with [hiview configure]. Tabbed views support three sizes: normal, small and mini. The large size is identical with the normal one. See the -variant option section above. The tabbed view can be considered as a set of buttons with the same behavior as a group of radio buttons. The value of the tabbed view is the index of the currently selected segment: it can be manipulated with the [hiview configure] command using the -value option. Labels and icons are not exclusive: one can have both a label and an icon in a tab. If no icon and no label have been specified, the tab receives a default name "Tab #i" where "#i" is the index of the tab. The first tab has index 1. Note that the number of tabs is stored in the maximum value of the control and can be manipulated with the [hiview configure] command using the -max option.

Text view

The text view is a MLTE (Multilingual Text Engine) view that can be embedded in the HIView hierarchy. The view can be embedded in a scroll view if scroll bars are desired. The text view has one specific creation option:

• the -attributes option lets you specify some characteristics of

the text view. It is an additive value made of the flags indicated in the table below.

The following options can be specified with the [hiview create] command: -attributes, -bounds, -command, -constraints, -enable, -help, -visible. The -attributes option cannot be modified with [hiview configure]. The text view control supports three extra options which can be manipulated using the [hiview configure] command:

• the -readOnly option lets you turn the read-only mode on (1) or off (0).
• the -selection option is used to get or set the selection in the

text. The value is a two-elements list containing the start and the end positions of the selection. Note that the text view must have the focus in order to hilite the selection.

• the -text option lets you specify the text displayed in the

view. Text views also support the text style options ''-color, -justify, -size, -style which are described in the Common configuration options'' section.

Combo box

Creation options:

• the -attributes option lets you specify some characteristics of

the combo box. Possible values are indicated in the table below: the default value is 11 (AutoCompletion, AutoDisclosure and AutoSizeList).

• the -text option lets you specify the string displayed by the combo box.

The following options can be specified with the [hiview create] command: -attributes, -bounds, -command, -constraints, -enable, -help, -text, -visible. The -text option can be modified with [hiview configure] but the -attributes option can't. The value of the -attributes option is an additive flag composed of the following constants:

The AutoSizeList property (attribute = 8) is necessary if you attach a menu to the combo box: if it is not used, the "size" of the items list will be 0, i-e no menu will be opened. As explained above, if no -attributes option is specified in the [hiview create] command, the AutoCompletion, AutoDisclosure and AutoSizeList properties are set by default. The combo box control supports an extra option:

• the -selection option is used to get or set the selection in the

text string. The value is a two-elements list containing the start and the end positions of the selection. Note that the edit field must have the focus in order to hilite the selection. It also supports the text style options ''-color, -justify, -size, -style which are described in the Common configuration options'' section.

Disclosure button

Creation options:

• the -autoToggle option lets you specify a boolean value indicating whether its value should change automatically after tracking the mouse. Possible values are 0 or 1. The default is 1.

The following options can be specified with the [hiview create] command: -autoToggle, -bounds, -command, -constraints, -enable, -help, -value, -visible. The -autoToggle option cannot be modified with [hiview configure]. The value of a disclosure button can be 0 or 1: 0 means closed (arrow pointing downwards), 1 means disclosed (arrow pointing upwards). The initial minimum of the Disclosure button will be 0, and the maximum will be 1.

Disclosure triangle

This control can be used as either left or right facing. It can also handle its own tracking: when the autoToggle variant is used, if the user clicks the control, its state will change automatically from open to closed and vice-versa depending on its initial state. You can just check the current value to see what state it was switched to. Creation options:

• the -autoToggle option lets you specify a boolean indicating

whether the Disclosure triangle should change its own value (from "open" to "closed" and vice-versa) automatically when it is clicked on. Possible values are 0 or 1. The default is 1.

• the -drawTitle option lets you specify a boolean indicating

whether the Disclosure triangle should draw its title next to the widget.

• the -orientation option lets you specify the direction the

Disclosure triangle should point when it is closed. The possible values are 0 (the default, points right on a left-to-right script system), 1 (points right), or 2 (points left). The following options can be specified with the [hiview create] command: -autoToggle, -drawTitle, -orientation, -bounds, -command, -constraints, -enable, -help, -title, -value, -visible. The -autoToggle, -drawTitle, -orientation options cannot be modified with [hiview configure].

Edit text

Creation options:

• the -password option lets you specify whether this field is a

password field or not. Possible values are 0 or 1.

• the -text option is used to get or set the content of the

edit text field. The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -password, -text, -visible. The -password, -text options cannot be modified with [hiview configure]. The edittext control supports three extra options:

• the -lock option lets you specify whether the edit field is

editable or not. Possible values are 0 or 1. Locking disables editability.

• the -multiLine option is used to indicate whether the

control should always be single-line or not. Possible values are 0 or 1.

• the -selection option is used to get or set the selection in the

text string. The value is a two-elements list containing the start and the end positions of the selection. Note that the edit field must have the focus in order to hilite the selection. It also supports the text style options ''-color, -justify, -size, -style which are described in the Common configuration options'' section.

Group box

Creation options:

• the -primary option lets you specify whether to create a primary or secondary group box. Possible values are 0 or 1. The default is 1.

The following options can be specified with the [hiview create] command: -primary, -bounds, -command, -constraints, -enable, -help, -title, -visible. The -primary options cannot be modified with [hiview configure].

Icon

Creation options:

• the -iconref option lets you specify a four-character code

designating a registered icon. See the Image support section above. The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -iconref, -visible. The -iconref option can also be modified with [hiview configure].

Image view

Creation options:

• the -iconFile option lets you specify the path of the file

containing the image data. Currently JPEG and PNG image formats are supported. In the case of JPEG, the file name is expected to have a .jpeg or .jpg extension; in the case of PNG, a .png extension. This is case insensitive. The following options can be specified with the [hiview create] command: -iconFile, -command, -constraints, -enable, -help, -visible. The -iconFile options cannot be modified with [hiview configure]. One can specify three extra options using the [hiview configure] command:

• the -alpha option lets you specify a floating point number

representing the alpha channel (from 0.0 through 1.0). An alpha of 1.0 is fully opaque, and 0.0 is fully transparent. The default alpha for an image is 1.0.

• the -opaque option lets you specify a boolean indicating whether

the image is opaque or not. If this is set to true, the image view can make certain optimizations for compositing and scrolling. The alpha value is rendered useless if opacity it set to true. An image view, when created, is transparent by default.

• the -scale option lets you specify a boolean indicating whether

the image should be scaled to fit the view bounds (1) or merely clipped to the view bounds (0). The default value is 0.

Image well

Creation options:

• the -iconref option lets you specify a four-character code

designating a registered icon. See the Image support section above. The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -iconref, -visible. The -iconref option can also be modified with [hiview configure].

List view

The list view supports the following creation options:

• the -multiValue option lets you specify whether multiple

selections are allowed or not. The default value is 0 (single item selection).

• the -num option lets you specify the number of columns in the view. The default value is 1.
• the -labels option lets you specify a list of labels for

each of the column headers. The list of labels should have as many elements as there are columns in the view. The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -multiValue, -num, -labels, -variant, -visible. The -multiValue, -num, -labels options cannot be modified with [hiview configure]. The list view control supports two extra options:

• the -items option lets you specify the contents of the list

view. If the list view has only one column, the value of the -items option is a simple list of items. Otherwise the value of this option should be a list of sublists representing the rows. Each sublist should contain as many elements as there are columns (as specified with the -num option). If a sublist has less elements than expected the missing ones will be considered empty. If it has more elements than expected, the extra items are ignored.

• the -selection option lets you retrieve the list of the

indices of the currently selected items. If the -multiValue option has been set to 1, there can be several selected items, otherwise there can be at most one selected item.

Little arrows

This control implements little up and down arrows used to adjust a value. The initial values are set using the -max, -min, -value options with the [hiview create] or [hiview configure] commands.

• the -increment option lets you specify the increment value of the

control. The default increment value is 1. The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -increment, -max, -min, -value, -visible. The -increment options cannot be modified with [hiview configure]. In order for the little arrows to be clickable, it is necessary that the min and max values be different. Clicking on the up arrow will add the amount of the increment to the current value. Similarly clicking on the down arrow will substract the amount of the increment from the current value. The increment can be negative.

Chasing arrows

The chasing arrows view has no specific creation options. It will automatically animate via an event loop timer. You should just pass the -bounds option in the [hiview create] command. It supports one extra option which can be manipulated using the [hiview configure] command:

• the -animate option lets you turn the animation on (1) or off (0).

Check box

Creation options:

• the -autoToggle option lets you specify whether this control should have auto-toggle behavior. If true,

the control will automatically toggle between on and off states when clicked. Possible values are 0 or 1. The default is 1. The following options can be specified with the [hiview create] command: -autoToggle, -bounds, -command, -constraints, -enable, -help, -title, -value, -visible. The -autoToggle option cannot be modified with [hiview configure]. Use the -value option to set the mark of the check box: 0 (off), 1 (on), or 2 (mixed). The control is automatically given a minimum value of 0 and a maximum value of 2.

Check group box

A check group box is a group rectangle equipped with a check box (and optionnally a title) on its top edge. Creation options:

• the -autoToggle option lets you specify whether to create an auto-toggling check box. Possible values are 0 or 1. The default is 1.
• the -primary option lets you specify whether to create a primary or secondary group box. Possible values are 0 or 1. The default is 1.

The following options can be specified with the [hiview create] command: -autoToggle, -primary, -bounds, -command, -constraints, -enable, -help, -title, -value, -visible. The -autoToggle, -primary options cannot be modified with [hiview configure]. Use the -value option to set the mark of the check box: 0 (off), 1 (on), or 2 (mixed).

Clock

Creation options:

• the -clockFlags option lets you specify some flags as shown in

the table below

• the -clockType option lets you specify the type of the clock

according to the values shown in the table below. Possible values for the -clockFlags option:

Possible values for the -clockType option:

The following options can be specified with the [hiview create] command: -clockFlags, -clockType, -bounds, -command, -constraints, -enable, -help, -visible. The -clockFlags, -clockType options cannot be modified with [hiview configure]. The clock control supports two extra options:

• the -animate option lets you turn the automatic update on (1)

or off (0). It applies only to clock controls views with a -clockFlags option containing the value 2.

• the -date option is used to get or set the clock's date. It

concerns exclusively clock views displaying a date, not a time. The date is expressed as the number of seconds since the Macintosh era (1st of January 1904).

Column view

The column view supports the following creation options:

• the -multiValue option lets you specify whether multiple

selections are allowed or not. The default value is 0 (single item selection). The following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -multiValue, -visible. The -multiValue option cannot be modified with [hiview configure]. The column view control supports three extra options:

• the -items option lets you specify the contents of the column

view. The value of this option should be a hierarchical list, that is to say a list whose items are either one-element or two-element sublists. A one-element sublist represents a simple item. A two-element sublist represents a container: its first item is the name of the container and the second one is a hierarchical list describing the contents of the container. See the example below. If the hierarchical is not correctly formatted, the command will raise an error.

• the -path option lets you retrieve the path representing the

currently opened container. The returned value is a list of the hierarchy of containers leading to the currently opened one.

• the -selection option lets you retrieve the list of the

currently selected items. If the -multiValue option has been set to 1, there can be several selected items (which can be either simple items or containers). If the -multiValue option has been set to 0, there can be at most one selected item. In order to know which container these items are located in, use the -path option. Here is an example of a hierarchic list:

 
     file1 file2 {dir1 {{dir11 {file111 file112}} file11 file12}} {dir2 {{dir21 file211} file21}} 

It corresponds to the following hierarchy:

 
     ---
        |--- file1
        |--- file2
        |--- dir1
        |   |--- dir11
        |   |   |--- file111
        |   |   |--- file112
        |   |--- file11
        |   |--- file12
        |--- dir2
            |--- dir21
            |   |--- file211
            |--- file21

Note that the -path and -selection options can not currently be set with the [hiview configure] command: you can only get the current path or selection. On the contrary, the -items option can only be used to set the contents on the column view.

The following table indicates the various options supported by the root views:

Dialog window

The dialog kind creates a movable modal window: the user cannot switch to another window in the application while the dialog is displayed. Root views of type dialog accept the following creation options: -alpha, -bounds, -command, -help, -resizable, -title, -visible.

Document window

The document kind creates a document window and is used for normal application document windows. AlphaX's editing windows belong to this category. These windows have a title bar with three buttons (close, collapse and zoom buttons) and a title. Root views of type document accept the following creation options: -alpha, -bounds, -closeBox, -collapseBox, -command, -help, -metal, -resizable, -title, -visible, -zoomBox.

Drawer window

The drawer kind creates a drawer window sliding out from underneath a document window. In order to attach a drawer window to another window, you must first create it with the [hiview root] command, then use the '''[hiview show]' command with a -parent or -w'' option to specify the parent window. In order to close a drawer window, you can invoke either the '''[hiview close] command or the [hiview delete]''' command. In the first case, you drawer window will slide back into its parent window and will remain available and ready to be displayed again later. Otherwise it will be deleted. Root views of type drawer accept the following creation options: -alpha, -bounds, -command, -direction, -help, -title, -visible. The -direction option can take one of the following values:

Floating window

The float kind creates a floating window. A floating window is layered above all application windows except for alert and modal windows. It is commonly used for palette windows, inspectors, and other accessory (non-document) windows. Root views of type float accept the following creation options: -alpha, -bounds, -closeBox, -collapseBox, -command, -help, -metal, -resizable, -sidebar, -title, -visible, -zoomBox.

Help window

The help kind creates a floating window. A help window is used to display help tags. It has no window frame. Root views of type help accept the following creation options: -alpha, -bounds, -command, -help, -title, -visible. Help windows are never activated so they should be used only for contents which do not change based on activation (like tooltip windows).

Overlay window

The help kind creates an overlay window. An overlay window is a completely transparent window positioned above all other windows. Overlay windows are intended as a replacement for the pre-Carbon practice of drawing directly into the window manager port; by creating a full-screen overlay window and drawing into it, you can draw over any window in any application without disturbing the contents of the windows underneath your drawing. Root views of type overlay accept the following creation options: -alpha, -bounds, -command, -help, -title, -visible. Overlay windows are never activated so they should be used only for contents which do not change based on activation.

Plain window

The plain kind creates a simple window, with a one pixel frame. A plain window does not display a title bar and behaves basically like a document window. Plain windows are placed in the document window group. Root views of type plain accept the following creation options: -alpha, -bounds, -command, -help, -title, -visible.

Sheet window

The sheet kind creates a sheet window. A sheet window is used to display a dialog that is attached directly to its parent window, rather than being an independent window. A sheet dialog only prevents interaction with its parent window; the user may still interact with other windows in the same application. In order to attach a sheet window to another window, you must first create it with the [hiview root] command, then use the '''[hiview show]' command with a -parent or -w'' option to specify the parent window. In order to close a sheet window, you can invoke either the '''[hiview close] command or the [hiview delete]''' command. In the first case, you sheet window will slide back into the top edge of its parent window and still be available and ready to be displayed again later. Otherwise it will be deleted. Root views of type sheet accept the following creation options: -alpha, -bounds, -command, -help, -resizable, -title, -visible.

Simple window

The simple kind creates a simple window. This is the simplest possible window; it has no window frame and its entire content is drawn by the application. Simple windows are placed in the document window group. Root views of type simple accept the following creation options: -alpha, -bounds, -command, -help, -title, -visible.

Toolbar window

The toolbar kind creates a toolbar window. Toolbar windows are used to display a palette of controls. They are similar to a floating windows: they are layered above all application windows except for alert and modal windows, but are layered beneath floating windows. This type of root windows should not be confused with the toolbars displayed at the top of AlphaX's editing windows (and created or manipulated with the [toolbar] command). Root views of type toolbar accept the following creation options: -alpha, -bounds, -command, -help, -title, -visible. Toolbar windows are never activated so they should be used only for contents which do not change based on activation.

Utility window

The utility kind creates a window similar to a floating window, but it floats above the windows of all applications rather than just above the windows of the application that creates it. Root views of type utility accept the following creation options: -alpha, -bounds, -closeBox, -collapseBox, -command, -help, -resizable, -sidebar, -title, -visible, -zoomBox.

Views description

The following sections give detailed information about the different views which can be created in a hiview hierarchy and provide a description of all the specific options available for each view. One can get the current value of an option with the [hiview configure token option-name] command. All the subviews support the common options (''-bounds, -command, -enable, -help, -hilite, -parent, -title, -visible'') so they are not mentionned here. The term "creation options" used in the sections below means any option other than the common options which can be declared in the [hiview create] command for a particular kind of subview. The documentation always indicates which creation options can be modified later using the [hiview configure] command. Then the extra options (if any) are described: extra options are additional options which can be specified only via the [hiview configure] command (they cannot be specified during the creation of the item).

Bevel button

Creation options:

• the -behavior option lets you specify the way the button behaves

on a click. Possible values are: push, toggle, sticky. The default is push.

• the -iconref option lets you specify a four-character code

designating a registered icon. See the Image support section above. If this option is not specified, the bevel button will only contain text.

• the -menu option lets you specify the token of a menu. If

this option is missing, the bevel button will not have a menu. The value is a token obtained with the [menuRef create] command (see the MenuRefCommand page on the wiki).

• the -menuPlacement option lets you specify the position of the

menu wrt the button. Possible values are 0 (menu on bottom) or 4 (menu on right). The default is 0.

• the -multiValue option lets you specify whether the associated

menu is a multi-value menu or not. This only makes sense when a menu is attached. Possible values are 0 or 1. The default is 0.

• the -variant option lets you specify the size of the control.

Bevel button controls support three sizes: normal, small or large. See the -variant option section above. The following options can be specified with the [hiview create] command: -behavior, -bounds, -command, -constraints, -enable, -help, -iconref, -menu, -menuPlacement, -multiValue, -title, -variant, -visible. The -menu, -iconref options can be modified with [hiview configure] but the -behavior, -menuPlacement, -multiValue, -variant options can't. One can also specify three extra options using the [hiview configure] command:

• the -iconAlignment option lets you specify the position of the graphic in

case the button contains an icon.

• the -menuValue option is used get or set the index of the

current menu item. Bevel buttons with menus actually have two values. The value of the button (on/off), and the value of the menu. The index of the current menu item can be manipulated with this option. Note that the indices are 0-based: the first item is at index 0, following the same convention as with the [menuItem] command. This option does not make sense and will raise an error if no menu is attached to the button.

• the -textPlace option lets you specify the position of the text

wrt the graphic in case the button contains an icon. Possible values for the -iconAlignment option:

Possible values for the -textPlace option:

• Introduction
  • Parents and children
  • The coordinate system
  • Types of views
• Synopsis
• Quick start example
• Syntax of subcommands
  • hiview add
  • hiview children
  • hiview configure
  • hiview create
  • hiview delete
  • hiview focus
  • hiview hide
  • hiview kind
  • hiview list
  • hiview move
  • hiview parent
  • hiview refresh
  • hiview remove
  • hiview root
  • hiview show
  • hiview subview
• Hiview options
  • Common creation options
  • Common configuration options
  • The -font option
  • The -style option
  • The -variant option
  • Image support options
• Roots description
  • Dialog window
  • Document window
  • Drawer window
  • Floating window
  • Help window
  • Overlay window
  • Plain window
  • Sheet window
  • Simple window
  • Toolbar window
  • Utility window
• Views description
  • Bevel button
  • Chasing arrows
  • Check box
  • Check group box
  • Clock
  • Column view
  • Combo box
  • Disclosure button
  • Disclosure triangle
  • Edit text
  • Group box
  • Icon
  • Image view
  • Image well
  • List view
  • Little arrows
  • Placard
  • Popup arrow
  • Popup button
  • Popup group box
  • Progress bar
  • Push button
  • Push button with icon
  • Radio button
  • Radio group
  • Relevance bar
  • Round button
  • Scroll bar
  • Scroll view
  • Search field
  • Segmented view
  • Separator
  • Slider
  • Static text
  • Tabbed view
  • Text view
  • User pane
  • Web view
  • Window header
• Reference table
• Hiviews and bindings
• The HiviewRects package

This file documents the [hiview] command introduced in version 8.2b12 of AlphaX.