Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

HIView Reference

Framework
Carbon/Carbon.h
Companion guide
Declared in
HIClockView.h
HICocoaView.h
HIComboBox.h
HIImageViews.h
HIMenuView.h
HIObject.h
HIScrollView.h
HISearchField.h
HISegmentedView.h
HITextViews.h
HIToolboxDebugging.h
HIView.h
HIWindowViews.h
Menus.h

Overview

HIView is an object-oriented view system subclassed from HIObject. All controls are implemented as HIView objects (“views”). You can easily subclass HIView classes, making it easy to implement custom controls. Over time, the HIView API will replace the current Control Manager. Using the HIView model, every item within a window is a view: the root control, controls, and even the standard window “widgets” (close, zoom, and minimize buttons, resize control, and so on). Current Control Manager function calls are layered on top of this HIView model.

Additional benefits of the HIView model include the following:

For additional information about using HIViews, see HIView Programming Guide.

Functions by Task

Obtaining and Placing Views

Working With Subviews

Manipulating Views

Managing Focus

Processing Events and Hit-Testing for Views

Manipulating View Coordinates

Creating and Manipulating Combo Boxes

Creating and Manipulating Image Views

Creating and Manipulating Scroll Views

Creating and Manipulating Layouts

Manipulating Tracking Areas

Creating and Manipulating Search Fields

Manipulating Menus

Manipulating Segmented Views

Working with Core Graphics Images

Working with Grow Boxes

Using Cocoa Views in Carbon Windows

Functions

HICocoaViewCreate

Creates a Carbon view that serves as a wrapper for a Cocoa view.

OSStatus HICocoaViewCreate (
   NSView *inNSView,
   OptionBits inOptions,
   HIViewRef *outHIView
);

Parameters
inNSView

A pointer to the Cocoa view you want to wrap. This function retains the Cocoa view you pass in; on output, you may safely release the view. If you want to create an empty Carbon wrapper view, you may pass NULL. An empty wrapper view does not draw or respond to user interaction; you can associate it with a Cocoa view at a later time using the function HICocoaViewSetView.

inOptions

Options for the new Carbon wrapper view. Currently this parameter must be 0.

outHIView

A pointer to a variable of type HIViewRef. On output, your variable contains a new Carbon view that serves as a wrapper for the Cocoa view specified in the inNSView parameter. You are responsible for releasing the wrapper view when you no longer need it. Note that if you embed the wrapper view in a Carbon window, the view (along with its associated Cocoa view) will be released automatically when the window is destroyed.

Return Value

An operating system result code. This function returns paramErr whenever the inOptions parameter is not 0 or the outHIView parameter is NULL.

Discussion

This function creates an HIView-based wrapper for a Cocoa view. You can embed the new wrapper view in a Carbon window and use standard HIView functions to manipulate the view. HICocoaView is supported only in compositing windows.

The following example shows how to use this function to create a wrapped Cocoa view that can be embedded in a Carbon window:

NSView *myCocoaView = [[SomeNSView alloc] init];
HIViewRef myHICocoaView;
HICocoaViewCreate (myCocoaView, 0, &myHICocoaView);
[myCocoaView release];
Availability
Declared In
HICocoaView.h

HICocoaViewGetView

Returns the Cocoa view associated with an existing Carbon wrapper view.

NSView * HICocoaViewGetView (
   HIViewRef inHIView
);

Parameters
inHIView

A wrapper view that has an associated Cocoa view.

Return Value

The Cocoa view associated with the specified wrapper view, or NULL if the wrapper view is empty or invalid. If you need to save the Cocoa view for later use, you should retain it.

Availability
Declared In
HICocoaView.h

HICocoaViewSetView

Associates a Cocoa view with a HICocoaView wrapper view.

OSStatus HICocoaViewSetView (
   HIViewRef inHIView,
   NSView *inNSView
);

Parameters
inHIView

An existing HICocoaView wrapper view.

inNSView

A pointer to a Cocoa view. This function retains the Cocoa view you pass in; on output, you may safely release this view. If the HICocoaView wrapper view specified in the inHIView parameter already wraps a Cocoa view, this function releases the wrapped view and replaces it with the Cocoa view you pass in.

Return Value

An operating system result code. This function returns paramErr if either parameter is NULL or invalid.

Discussion

Typically you’ll use this function after you instantiate a nib-based Carbon window that contains an empty HICocoaView wrapper view. The empty wrapper view serves as a placeholder until you call this function to associate a Cocoa view with it. HICocoaView is supported only in compositing windows.

The following example shows how to use this function to associate a Cocoa view with an existing wrapper view:

NSView *myCocoaView = [[SomeNSView alloc] init];
HICocoaViewSetView (myHICocoaView, myCocoaView);
[myCocoaView release];
Availability
Declared In
HICocoaView.h

HIComboBoxAppendTextItem

Appends a text item to the combo box disclosure list.

OSStatus HIComboBoxAppendTextItem (
   HIViewRef inComboBox,
   CFStringRef inText,
   CFIndex *outIndex
);

Parameters
inComboBox

The combo box having the disclosure list to which the text is to be appended.

inText

The text item to be appended to the combo box disclosure list.

outIndex

On exit, the index of the new item. Can be NULL if you don’t want this information.

Return Value

An operating system status code.

Availability
Declared In
HIComboBox.h

HIComboBoxChangeAttributes

Changes the attributes of a combo box.

OSStatus HIComboBoxChangeAttributes (
   HIViewRef inComboBox,
   OptionBits inAttributesToSet,
   OptionBits inAttributesToClear
);

Parameters
inComboBox

The combo box whose attributes you want to change.

inAttributesToSet

The attributes to set. For possible values, see “Combo Box Attributes.”

inAttributesToClear

The attributes to clear. For possible values, see “Combo Box Attributes.”

Return Value

An operating system status code.

Availability
Declared In
HIComboBox.h

HIComboBoxCopyTextItemAtIndex

Copy a text item from a combo box disclosure list

OSStatus HIComboBoxCopyTextItemAtIndex (
   HIViewRef inComboBox,
   CFIndex inIndex,
   CFStringRef *outString
);

Parameters
inComboBox

The combo box that contains the text item you want to copy.

inIndex

The index of the text item. This function returns paramErr if the index is out of the bounds of the combo box disclosure list.

outString

A copy of the string at the specified index. You are responsible for releasing the string.

Return Value

An operating system status code.

Availability
Declared In
HIComboBox.h

HIComboBoxCreate

Creates a combo box control.

OSStatus HIComboBoxCreate (
   const HIRect *boundsRect,
   CFStringRef text,
   const ControlFontStyleRec *style,
   CFArrayRef list,
   OptionBits inAttributes,
   HIViewRef *outComboBox
);

Parameters
boundsRect

The bounding box of the control.

text

The default text in the editable portion of the control. Can be NULL.

style

The font style of the both editable text and the text in the disclosure list. Can be NULL.

list

The default values available in the disclosure list. Can be NULL.

inAttributes

The default attributes of the combo box. For possible values, see “Combo Box Attributes.”

outComboBox

On exit, a pointer to a reference for the new control.

Discussion

The combo box can be used in compositing mode, as well as traditional Control Manager mode. When created, this view is invisible. To see the view, you must show the view by calling HIViewSetVisible.

Availability
Declared In
HIComboBox.h

HIComboBoxGetAttributes

Gets the attributes of a combo box.

OSStatus HIComboBoxGetAttributes (
   HIViewRef inComboBox,
   OptionBits *outAttributes
);

Parameters
inComboBox

The combo box whose attributes you want to obtain.

outAttributes

The attributes of the combo box. For possible values, see “Combo Box Attributes.”

Return Value

An operating system status code.

Availability
Declared In
HIComboBox.h

HIComboBoxGetItemCount

Gets the number of items in the combo box disclosure list.

ItemCount HIComboBoxGetItemCount (
   HIViewRef inComboBox
);

Parameters
inComboBox

The combo box.

Return Value

The number of items in the combo box disclosure list.

Availability
Declared In
HIComboBox.h

HIComboBoxInsertTextItemAtIndex

Inserts a CFString in a combo box disclosure list.

OSStatus HIComboBoxInsertTextItemAtIndex (
   HIViewRef inComboBox,
   CFIndex inIndex,
   CFStringRef inText
);

Parameters
inComboBox

The combo box having the disclosure list in which the text is to be inserted.

inIndex

The index at which the text should be inserted. If the index does not fall within the number of items in the combo box list, the text is appended to the end of the list.

inText

The text item to be inserted in the combo box disclosure list.

Return Value

An operating system status code.

Availability
Declared In
HIComboBox.h

HIComboBoxIsListVisible

Determines whether a combo box disclosure list is visible.

Boolean HIComboBoxIsListVisible (
   HIViewRef inComboBox
);

Parameters
inComboBox

The Combo box whose disclosure list visibility is to be queried.

Return Value

A Boolean whose value is true if the combo box disclosure list is visible; otherwise, false to indicate that the combo box disclosure list is hidden.

Availability
Declared In
HIComboBox.h

HIComboBoxRemoveItemAtIndex

Removes an item from a combo box disclosure list.

OSStatus HIComboBoxRemoveItemAtIndex (
   HIViewRef inComboBox,
   CFIndex inIndex
);

Parameters
inComboBox

The combo box having the disclosure list that from which you want to remove an item.

inIndex

The index of the item to remove.

Return Value

An operating system status code.

Availability
Declared In
HIComboBox.h

HIComboBoxSetListVisible

Hides or shows a combo box disclosure list.

OSStatus HIComboBoxSetListVisible (
   HIViewRef inComboBox,
   Boolean inVisible
);

Parameters
inComboBox

The combo box.

inVisible

A Boolean whose value is true to make the combo box disclosure list visible or false to hide the combo box list.

Return Value

An operating system result code.

Availability
Declared In
HIComboBox.h

HICreateTransformedCGImage

Creates a new Core Graphics image with the standard selected or disabled appearance.

OSStatus HICreateTransformedCGImage (
   CGImageRef inImage,
   OptionBits inTransform,
   CGImageRef *outImage
);

Parameters
inImage

The original image.

inTransform

The transformation to apply to the image. For possible values, see “Transformation Constants.”

outImage

A pointer to a value of type CGImageRef that, on return, contains the new image. You are responsible for releasing the image.

Return Value

An operating system result code.

Availability
Declared In
HIView.h

HIGrowBoxViewIsTransparent

Determines whether a grow box view is transparent.

Boolean HIGrowBoxViewIsTransparent (
   HIViewRef inGrowBoxView
);

Parameters
inGrowBoxView

The grow box view reference to query.

Return Value

A Boolean value that is true if the grow box view is transparent; otherwise, false which indicates the grow box view is an opaque white square with grow lines.

Availability
Declared In
HIWindowViews.h

HIGrowBoxViewSetTransparent

Makes a grow box view transparent or opaque. 

OSStatus HIGrowBoxViewSetTransparent (
   HIViewRef inGrowBoxView,
   Boolean inTransparent
);

Parameters
inGrowBoxView

The grow box view reference.

inTransparent

Pass true to make the grow box view use its transparent look or false to make the grow box view use its opaque appearance.

Return Value

An operating system result code.

Discussion

This function sets a grow box view to be transparent, meaning the grow box lines are drawn over any content under it. When not transparent, the grow box is an opaque white square with the grow lines.

Availability
Declared In
HIWindowViews.h

HIImageViewCopyImage

Obtains the image for an image view.

CGImageRef HIImageViewCopyImage (
   HIViewRef inView
);

Parameters
inView

The image view to query.

Return Value

A Core Graphics (Quartz) image reference, or NULL if there is no image set on the view or if the view ref is invalid.

Discussion

The image is retained, so you should release it when you are finished with it.

Availability
Declared In
HIImageViews.h

HIImageViewCreate

Creates an image view.

OSStatus HIImageViewCreate (
   CGImageRef inImage,
   HIViewRef *outView
);

Parameters
inImage

An initial image, or NULL. You can use SetControlData to set the image later.

outControl

The new image view.

Return Value

An operating system result code.

Discussion

The view responds to the scrollable interface and can be used in a scrolling view. You can pass an image initially, or set one later.

Availability
Declared In
HIImageViews.h

HIImageViewGetAlpha

Obtains the alpha value for a view.

CGFloat HIImageViewGetAlpha (
   HIViewRef inView
);

Parameters
inView

The image view to query.

Return Value

A floating point number representing the alpha from 0.0 through 1.0.

Discussion

An alpha of 1.0 means that the view is fully opaque, and alpha of 0.0 is means the view is fully transparent.

Availability
Declared In
HIImageViews.h

HIImageViewGetScaleToFit

Determines whether an image will scale or clip to the view bounds.

Boolean HIImageViewGetScaleToFit (
   HIViewRef inView
);

Parameters
inView

The image view to query.

Return Value

A Boolean whose value is true if the image scales or false if the image clips.

Discussion

This function determines whether an image view will scale the image it displays to the view bounds or merely clip to the view bounds.

Availability
Declared In
HIImageViews.h

HIImageViewIsOpaque

Determines whether an image view is opaque.

Boolean HIImageViewIsOpaque (
   HIViewRef inView
);

Parameters
inView

The image view to query.

Return Value

A Boolean whose value is true if the image view is opaque; otherwise, false.

Availability
Declared In
HIImageViews.h

HIImageViewSetAlpha

Sets the alpha value for an image view.

OSStatus HIImageViewSetAlpha (
   HIViewRef inView,
   CGFloat inAlpha
);

Parameters
inView

The image view to affect.

inAlpha

The new alpha value.

Return Value

An operating system result code.

Discussion

Allows you to set the alpha for an image, making it more or less transparent. An alpha of 1.0 is fully opaque, and an alpha of 0.0 is fully transparent. The default alpha for an image is 1.0.

Availability
Declared In
HIImageViews.h

HIImageViewSetImage

Sets the image to display in an image view.

OSStatus HIImageViewSetImage (
   HIViewRef inView,
   CGImageRef inImage
);

Parameters
inView

The image view to affect.

inImage

The image to set.

Return Value

An operating system status code.

Discussion

The image passed in is retained by the view, so you may release the image after calling this function if you no longer need to reference it.

Availability
Declared In
HIImageViews.h

HIImageViewSetOpaque

Sets the opacity of an image view.

OSStatus HIImageViewSetOpaque (
   HIViewRef inView,
   Boolean inOpaque
);

Parameters
inView

The image view to set.

inOpaque

A Boolean whose value is true to make the image view opaque or false to disable the opacity setting.

Return Value

An operating system result code.

Discussion

When opacity is enabled, the image view can make certain optimizations for compositing and scrolling. The alpha-related image view APIs are rendered useless when opacity is enabled. An image view, when created, is opaque by default. You must pass false to this function in order to change the alpha, etc. or if your image does not fill the full bounds of the view.

Availability
Declared In
HIImageViews.h

HIImageViewSetScaleToFit

Specifies whether an image should scale or clip to the view’s bounds.

OSStatus HIImageViewSetScaleToFit (
   HIViewRef inView,
   Boolean inScaleToFit
);

Parameters
inView

The image view.

inScaleToFit

A Boolean whose value is true to indicate that the image should be scaled to fit the view bounds or false to indicate that the image should clip to the view’s bounds.

Return Value

An operating system status code.

Discussion

Normally, an image view clips to the view’s bounds. Use this function to tell the image view to size the image to fit into the view’s bounds.

Availability
Declared In
HIImageViews.h

HIMenuGetContentView

Obtains an HIViewRef that can be used to draw menu content for a menu.

OSStatus HIMenuGetContentView (
   MenuRef inMenu,
   ThemeMenuType inMenuType,
   HIViewRef *outView
);

Parameters
inMenu

The menu for which an HIViewRef is to be obtained.

inMenuType

The type of menu for which the menu content view is to be returned. The same MenuRef may have multiple content views, depending on the menu type being displayed.

outView

A pointer to a value of type HIViewRef that, on return, represents the view, or NULL if the menu does not use an HIView to draw its content. The caller should not release this view.

Return Value

An operating system result code. If the menu uses an MDEF instead of a view to draw its content, this function sets outView to NULL and returns noErr.

Discussion

If the content view has not yet been created, the Menu Manager will create the content view using the view class ID and initialization event associated with the menu. Note that the menu content view is not the same as the window content view; the menu content view is embedded inside the window content view.

Availability
Declared In
Menus.h

HIMenuViewGetMenu

Returns the MenuRef associated with a view that is a subclass of HIMenuView.

MenuRef HIMenuViewGetMenu (
   HIViewRef inView
);

Parameters
inView

The view whose menu is to be returned.

Return Value

The MenuRef associated with the specified view, or NULL if a view is passed that is not a subclass of HIMenuView.

Discussion

An HIMenuView subclass might use call this function to determine the menu it should draw.

Special Considerations

Prior to Mac OS X v10.5, this function returns NULL if passed an instance of the standard menu view. In Mac OS X v10.5 and later, this function correctly returns the owning menu of an instance of the standard menu view.

Availability
Declared In
HIMenuView.h

HIScrollViewCanNavigate

Determines whether it is possible to navigate in a scroll view. 

Boolean HIScrollViewCanNavigate (
   HIViewRef inView,
   HIScrollViewAction inAction
);

Parameters
inView

The view to query.

inAction

The navigation action to test. For possible values, see “Scroll View Action Constants.”

Return Value

A Boolean whose value is true if the navigation specified by inAction is possible; otherwise, false.

Discussion

Use this function to determine whether it is possible to perform a particular navigation within a scroll view. For example, if a scroll view is already at the top of the scrollable content, it is not possible to navigate upward, so the home and page up actions would not be possible. You might use this function to help you update the state of menu items.

Availability
Declared In
HIScrollView.h

HIScrollViewCreate

Creates a scroll view. 

OSStatus HIScrollViewCreate (
   OptionBits inOptions,
   HIViewRef *outView
);

Parameters
inOptions

Options for our scroll view. You must specify either a horizontal or a vertical scroll bar. If neither is passed, an error is returned. For possible values, see “Scroll View Constants.”

outView

The new scroll view.

Return Value

An operating system result code.

Discussion

This view has three parts. It can have a horizontal scroll bar, a vertical scroll bar, and a view to be scrolled that must be added by