Recent Changes - Search:

WikiDoc

Categories

HiviewCommand

Commands.HiviewCommand History

Hide minor edits - Show changes to markup

May 11, 2009, at 02:05 PM by bd -
Changed line 26 from:
to:
May 11, 2009, at 02:02 PM by bd - Ref
Changed line 26 from:
to:
May 11, 2009, at 01:47 PM by bd - Links to hiview subpages
Deleted line 0:
Changed lines 22-26 from:
to:
May 11, 2009, at 01:43 PM by bd - Links to hiview subpages
Added line 1:
Deleted line 3:
Changed lines 21-27 from:

file Hiview Help.html accessible from the Help menu in AlphaX.

to:

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

May 07, 2009, at 07:45 AM by bd - hiview short doc
Changed lines 1-89 from:
to:

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

Changed line 15 from:
  • each element of a dialog or window is created individually and can be manipulated independently from the others
to:
  • each element of a dialog or window is created individually and can be manipulated independently from the others
Changed lines 17-522 from:
to:
  • 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.

May 07, 2009, at 05:57 AM by bd - The [hiview] command3
Added lines 561-608:

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.

May 07, 2009, at 05:55 AM by bd - The [hiview] command2
Deleted line 0:
Added lines 505-560:

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.

May 07, 2009, at 05:29 AM by bd - The [hiview] command
May 07, 2009, at 05:26 AM by bd - The [hiview] command
Changed lines 102-103 from:
  • each element of a dialog or window is created individually and can be

manipulated independently from the others

to:
  • each element of a dialog or window is created individually and can be manipulated independently from the others
Changed lines 104-108 from:
  • 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).

to:
  • 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).
Changed lines 108-109 from:
  • control objects, also called subviews, which are created with the

[hiview create] command

to:
  • control objects, also called subviews, which are created with the [hiview create] command
Changed lines 374-380 from:
  • 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.

to:
  • 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.
Changed lines 399-404 from:
  • 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.

to:
  • 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.
Changed lines 405-408 from:
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.

to:
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.
Changed lines 471-475 from:
  • 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.

to:
  • 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.
Changed lines 485-496 from:
  • 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.

to:
  • 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.

Changed lines 499-510 from:
  • 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.

to:
  • 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.

Deleted lines 505-560:

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.

May 07, 2009, at 05:17 AM by bd - The [hiview] command
Added line 1:
Changed lines 90-91 from:

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

to:
Changed lines 160-199 from:
KindOptions
dialog-alpha, -bounds, -command, -help, -resizable, -title, -visible
document-alpha, -bounds, -closeBox, -collapseBox, -command, -help, -metal, -resizable, -title, -visible, -zoomBox
drawer-alpha, -bounds, -command, -direction, -help, -title, -visible
float-alpha, -bounds, -closeBox, -collapseBox, -command, -help, -metal, -resizable, -sidebar, -title, -visible, -zoomBox
help-alpha, -bounds, -command, -help, -title, -visible
overlay-alpha, -bounds, -command, -help, -title, -visible
plain-alpha, -bounds, -command, -help, -title, -visible
sheet-alpha, -bounds, -command, -help, -resizable, -title, -visible
simple-alpha, -bounds, -command, -help, -title, -visible
toolbar-alpha, -bounds, -command, -help, -title, -visible
utility-alpha, -bounds, -closeBox, -collapseBox, -command, -help, -resizable, -sidebar, -title, -visible, -zoomBox

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:

to:
TypeDescriptionCodeClass ID
bevelbuttonBevel buttonbevlcom.apple.HIBevelButton
chasingarrowsChasing arrowscarrcom.apple.HIChasingArrows
checkboxCheck boxcboxcom.apple.HICheckBox
checkgroupboxCheck group boxcgrpcom.apple.HICheckBoxGroup
clockClockclckcom.apple.HIClock
columnviewColumn Viewdatbcom.apple.HIDataBrowser
comboboxCombo boxcbbxcom.apple.HIComboBox
disclosurebuttonDisclosure buttondisbcom.apple.HIDisclosureButton
disclosuretriangleDisclosure triangledistcom.apple.HIDisclosureTriangle
edittextEdit unicode texteutxcom.apple.HITextField
groupboxGroup boxgrpbcom.apple.HIGroupBox
iconIconiconcom.apple.HIIconView
imageviewImage viewimagcom.apple.HIImageView
imagewellImage wellwellcom.apple.HIImageWell
listviewList Viewdatbcom.apple.HIDataBrowser
littlearrowsLittle arrowslarrcom.apple.HILittleArrows
placardPlacardplaccom.apple.HIPlacardView
popuparrowPopup arrowparrcom.apple.hipopuparrow
popupbuttonPopup buttonpopbcom.apple.HIPopupButton
popupgroupboxPopup group boxpgrpcom.apple.HIPopupButton
progressbarProgress barprgbcom.apple.HIProgressBar
pushbuttonPush buttonpushcom.apple.HIPushButton
pushiconbuttonPush button with iconpicncom.apple.HIPushButton
radiobuttonRadio buttonrdiocom.apple.HIRadioButton
radiogroupRadio grouprgrpcom.apple.HIRadioGroup
relevancebarRelevance barrelbcom.apple.HIRelevanceBar
roundbuttonRound buttonrndbcom.apple.HIRoundButton
scrollbarScroll barsbarcom.apple.HIScrollBar
scrollviewScroll viewscrlcom.apple.HIScrollView
searchfieldSearch fieldsrfdcom.apple.HISearchField
segmentedviewSegmented viewsgmtcom.apple.HISegmentedView
separatorSeparatorsepacom.apple.HIVisualSeparator
sliderSlidersldrcom.apple.HISlider
statictextStatic textstxtcom.apple.HIStaticTextView
tabbedviewTabstabscom.apple.HITabbedView
textviewText viewhitxcom.apple.HITextView
userpaneUser paneupancom.apple.HIUserPane
webviewWeb viewwbvwcom.apple.HIWebView
windowheaderWindow headerwhedcom.apple.HIWindowHeaderView

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

Changed lines 205-338 from:
ValueNameDescription
0EdgeDefaultopen on whatever edge of the parent window
1EdgeTopopen on the top edge of the parent window
2EdgeLeftopen on the left edge of the parent window
4EdgeBottomopen on the bottom edge of the parent window
8EdgeRightopen on the right edge of the parent window

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:

to:
HIViewOS X
Combo Box10.2
Image View10.2
Scroll View10.2
Search Field10.3
Segmented View10.3
Text View10.3
Web view10.2.7

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.

Changed lines 300-312 from:
ValueDescription
-1Sys Direction
0Center
1Left
2Right
3Top
4Bottom
5Top Left
6Bottom Left
7Top Right
8Bottom Right

Possible values for the -textPlace option:

to:
ViewOptions
bevelbutton-behavior, -bounds, -command, -constraints, -enable, -help, -iconref, -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-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, -menu, -parent, -title, -titleWidth, -variableWidth, -variant, -visible
popupgroupbox-bounds, -command, -constraints, -enable, -help, -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

  • 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:

Changed lines 394-432 from:
ValueDescription
-1Sys Direction
0Normally
1To Right Of Graphic
2To Left Of Graphic
3Below Graphic
4Above Graphic

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:

to:
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

  • 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:

Changed lines 465-536 from:
ValueNameDescription
0NoFlags
1IsDisplayOnlynon-editable
2IsLiveautomatically shows current time

Possible values for the -clockType option:

ValueDescription
0Hour Minute
1Hour Minute Second
2Month Day Year
3Month Year

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

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

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
Changed lines 515-1245 from:
to:

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.

May 07, 2009, at 05:08 AM by bd - The [hiview] command
Added lines 894-1125:
May 07, 2009, at 05:07 AM by bd - The [hiview] command
Added lines 550-893:

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.

ValueDescription
1Vertical
2Horizontal
3Both

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:

ValueNameDescription
0NoAttributesno attributes
1Cancelthe view contains the cancel icon in the text field
2SearchIconthe view contains the search icon in the text field

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.

ValueNameDescription
1AlwaysWrapAtViewEdgelines will wrap at the edge of the view rectangle
2NoSelectionprevents setting the insertion point or making a selection
4ReadOnlythe text object will be read-only
8SingleLineOnlythe text object will not scroll vertically

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.

May 07, 2009, at 05:06 AM by bd - The [hiview] command
Added lines 395-549:

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:

ValueNameDescription
0NoAttributesno attributes
1AutoCompletionauto complete the text the user is typing with an item in the list that is the closest appropriate match
2AutoDisclosuredisclose the ComboBox list after the user enters text
4AutoSortthe items in the ComboBox list will be automatically sorted in alphabetical order
8AutoSizeListthe ComboBox list will be automatically sized to fit the Human Interface Guidelines

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.

May 07, 2009, at 05:05 AM by bd - The [hiview] command
Added lines 289-394:

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:

ValueNameDescription
0NoFlags
1IsDisplayOnlynon-editable
2IsLiveautomatically shows current time

Possible values for the -clockType option:

ValueDescription
0Hour Minute
1Hour Minute Second
2Month Day Year
3Month Year

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.

May 07, 2009, at 05:04 AM by bd - The [hiview] command
Added lines 89-288:

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

KindOptions
dialog-alpha, -bounds, -command, -help, -resizable, -title, -visible
document-alpha, -bounds, -closeBox, -collapseBox, -command, -help, -metal, -resizable, -title, -visible, -zoomBox
drawer-alpha, -bounds, -command, -direction, -help, -title, -visible
float-alpha, -bounds, -closeBox, -collapseBox, -command, -help, -metal, -resizable, -sidebar, -title, -visible, -zoomBox
help-alpha, -bounds, -command, -help, -title, -visible
overlay-alpha, -bounds, -command, -help, -title, -visible
plain-alpha, -bounds, -command, -help, -title, -visible
sheet-alpha, -bounds, -command, -help, -resizable, -title, -visible
simple-alpha, -bounds, -command, -help, -title, -visible
toolbar-alpha, -bounds, -command, -help, -title, -visible
utility-alpha, -bounds, -closeBox, -collapseBox, -command, -help, -resizable, -sidebar, -title, -visible, -zoomBox

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:

ValueNameDescription
0EdgeDefaultopen on whatever edge of the parent window
1EdgeTopopen on the top edge of the parent window
2EdgeLeftopen on the left edge of the parent window
4EdgeBottomopen on the bottom edge of the parent window
8EdgeRightopen on the right edge of the parent window

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:

ValueDescription
-1Sys Direction
0Center
1Left
2Right
3Top
4Bottom
5Top Left
6Bottom Left
7Top Right
8Bottom Right

Possible values for the -textPlace option:

ValueDescription
-1Sys Direction
0Normally
1To Right Of Graphic
2To Left Of Graphic
3Below Graphic
4Above Graphic
May 07, 2009, at 05:02 AM by bd - The [hiview] command
Added lines 1-2:
This file documents the [hiview] command introduced in version 8.2b12 of AlphaX.
Page last modified on May 11, 2009, at 02:05 PM
Hosted on SourceForge.net Logo