From AlphaWiki

Commands: HiviewSubviews

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 following options can be specified with the [hiview create] command: -behavior, -bounds, -command, -constraints, -enable, -help, -iconref, -items, -menu, -menuPlacement, -multiValue, -title, -variant, -visible. The -items, -menu, -iconref options can be modified with [hiview configure] but the -behavior, -menuPlacement, -multiValue, -variant options can't. See, in the Popup Button section, the discussion about the respective merits of the -items and the -menu options. One can also specify three extra options using the [hiview configure] command:

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

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:

Check box

Creation options:

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

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:

Column view

The column view supports the following creation options:

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:

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.

Combo box

Creation options:

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 constant containing the following flags:

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:

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

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

Image well

Creation options:

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 following options can be specified with the [hiview create] command: -attributes, -bounds, -command, -constraints, -enable, -help, -multiValue, -num, -labels, -variant, -visible. The -multiValue, -num, -labels options cannot be modified with [hiview configure]. The value of the -attributes option is an additive constant containing the following flags:

ValueDescription
0No attributes
1Selectable columns
2Sortable columns
4Movable columns
8Alternating row colors
16Full row hilite
32Draw column dividers
64No horizontal scrollbar
128No vertical scrollbar

The list view control supports two extra options:

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

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 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 following options can be specified with the [hiview create] command: -bounds, -command, -constraints, -enable, -help, -items, -menu, -menuValue, -title, -titleWidth, -variableWidth, -visible. The -items, -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: ((li 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. ((li 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. On creation, you can specify either the -items or the -menu option: if both are specified, the -menu option has precedence. The -menu option attaches a menu which was previously created with the [menuRef create] command. The -items option lets you pass directly a list of items: if no menu is attached to the popup, the [hiview] command will create one internally, but this menu will not have a menu token, so you won't be able to manipulate it with the [menuRef] or the [menuItem] commands. If a menu is already attached to the popup, specifying a list of items will replace the elements of the menu by the new items. Depending on the context, it may be more practical to use one option or the other. Both options have their advantages:

  • with the -menu option, you can attach a complex hierarchical

menu, containing submenus while the -items option defines only a simple list of items.

  • with the -items option, you do not have to go through the trouble of

creating a menu, populating it and releasing it when it is not needed anymore.

Popup group box

Creation options:

  • the -items option lets you specify a list of items to install in the menu.
  • 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, -items, -menu, -menuValue, -primary, -title, -titleWidth, -variableWidth, -visible. The -items, -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. See also, in this section, the discussion about the respective merits of the -items and the -menu options.

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. This option works only on Mac OS X 10.5 (Leopard). On Mac OS X 10.4 (Tiger), use the -max option instead.
  • the -max option lets you specify the ID of a 'cicn' resource. This option works only on Mac OS X 10.4 (Tiger). On Mac OS X 10.5 or greater, use the -iconref option instead.

The following options can be specified with the [hiview create] command: -iconAlignment, -iconref, -bounds, -command, -constraints, -enable, -help, -title, -variant, -visible. The -iconref, -max options can be modified with [hiview configure] but the -iconAlignment option cannot. The -iconref and the -max options are mutually exclusive. On Mac OS X 10.4, the icon must be specified as a 'cicn' resource via the -max option: the -iconref option will raise an error. The reason for using the -max option is that the Carbon Toolbax itself stores the resource ID in the max field of the control.

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 -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 constant containing the following flags:

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.

User pane

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

Web view

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

  • the -url option lets you specify an URL to load an HTML file and display it in the web view.

Window header

Creation options:

  • the -listHeader option lets you specify a boolean indicating whether the control is to draw as a list header: if this option is set to 1, there is no bottom line. The default value is 0.

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

Retrieved from http://alphatcl.sourceforge.net/wiki/pmwiki.php/Commands/HiviewSubviews
Page last modified on October 03, 2009, at 07:42 AM