• View
• Edit
• History
• Print

HiviewIntro

• Introduction
  • Parents and children
  • The coordinate system
  • Types of views
• Synopsis
• Quick start example

Introduction

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

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

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

Parents and children

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

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

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

The coordinate system

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

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

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

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

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

Types of views

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

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

Synopsis

The [hiview] command uses the following formal syntax:

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

Quick start example

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

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

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

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

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

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

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

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

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

 	# Display the window
 	hiview show $root

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