Enabling Compositing in Windows

Windows that use HIView must have compositing turned on. Compositing means that HIView draws window content view by view, from back to front, allowing each view to draw only the portions of itself that are visible. That is, you don’t have to worry about inefficient drawing resulting from drawing on top of existing pixels.

Turn on compositing by setting the compositing window attribute. You can do so in the Info window in Interface Builder or by adding kWindowCompositingAttribute to the attribute list when you call CreateNewWindow. Note that older window creation functions don’t allow compositing.

Unless you really need specialized event handling, you should also specify using the standard window event handler when creating windows for HIView.

If you are porting older control code to HIView, you should know that once compositing is on, your code must accommodate these changes:

• You should replace any calls that draw directly to the screen (DrawControls, Draw1Control) with the appropriate HIView invalidation call (HIViewSetNeedsDisplay).

• You no longer need to erase behind controls, as the compositor keeps track of the background layers and can redraw them as necessary.

Creating a View

Creating views is straightforward. If your view is an older control, just use the Control Manager creation function (for example, CreateCheckBoxControl). For new views, use the appropriate HIView creation function shown in Table 2-1.

Menus in Mac OS X v10.3 and later are automatically implemented as views, so you do not need to change your code to adopt view-based menus.

Note that when initially created, the new HIView views are not associated with a window, and some do not even have a physical size. To give the view physical dimensions, you must embed the view within a parent and then set its size and position by calling the function HIViewSetFrame or HIViewPlaceInSuperviewAt.

You can pass NULL for the window reference when calling older control creation functions if you want to create a control that is not initially associated with a window.

Views are invisible when first created. To make them visible, call HIViewSetVisible or the Control Manager function ShowControl.

Embedding Views

The HIView API provides a number of functions to add or remove views from a view hierarchy:

• To embed a view within another view, call the HIViewAddSubview function:

  OSStatus HIViewAddSubview (HIViewRef inParent, HIViewRef inChild);

  Note that this function merely adds the view to the hierarchy; it does not physically place the view within its parent. To position the view, you should call the HIViewSetFrame function or HIViewPlaceInSuperviewAt.

• To remove a view from its parent, call the HIViewRemoveFromSuperview function:

  OSStatus HIViewRemoveFromSuperview (HIViewRef inView);

• To determine the parent of a view, call the HIViewGetSuperview function:

  HIViewRef HIViewGetSuperview (HIViewRef inView);

• To obtain the root view for a window, call the HIViewGetRoot function:

  HIViewRef HIViewGetRoot (WindowRef inWindow);

Positioning Views

You use the following functions to set or obtain the position of a view within its parent:

• To obtain the local bounds of a view, call the HIViewGetBounds function:

  OSStatus HIViewGetBounds (HIViewRef inView, HIRect *outRect);

• To obtain the frame bounds of a view, call the HIViewGetFrame function:

  OSStatus HIViewGetFrame (HIViewRef inView, HIRect *outRect);

  This function is analogous to the older GetControlBounds function except that the coordinates are referenced to the view’s parent, not the window’s content region.

• To set the frame bounds of a view, call the HIViewSetFrame function.

  OSStatus HIViewSetFrame (HIViewRef inView, const HIRect *inRect);

  This function effectively moves the view within its parent. It also marks the view (as well anything that may have been exposed behind it) to be redrawn.

• To move a view a certain amount within its parent, call the HIViewMoveBy function:

  OSStatus HIViewMoveBy (HIViewRef inView, float inDX, float inDY);

• To place a view at a certain point within its parent, call the HIViewPlaceInSuperviewAt function:

  OSStatus HIViewPlaceInSuperviewAt (HIViewRef inView,

  float inX, float inY);

Automating View Layout

In Mac OS X v10.3 and later, you can use special layout functions to bind the size or position of one view to another view. For example, the layout APIs make it easy to do any of the following:

• Center views either horizontally or vertically (or both) in a window.

• Specify that an OK button always keep its proper pixel distance from the bottom right corner of the window (as per the Aqua guidelines) even if the window is resized.

• Create group boxes that automatically resize proportionally as the content view bounds change.

You can specify the following different layout options:

• Bind a view so that it maintains its relative position to one or more edges of another view. For example, if you bind a button to the top edge of a group box, the button maintains its relative position to that edge if the group box moves. (Note, however, that you can move the button’s top edge independent of the group box.) See The HIBinding Structure for more details.

• Position a view so that it is always aligned to the specified edge (or the center) of another view. For example, if you align a button’s top edge to the top edge of a group box, those edges will always share the same y-coordinate. You can also specify an alignment offset if desired. See The HIPositioning Structure for more details.

• Scale a view so that it maintains a particular size ratio with another view. For example, you can specify that a group box’s width is always half that of the content view that contains it. See The HIScaling Structure for more details.

Note that these layout constraints are "one-way"; for example, if button A is constrained to scale as the size of button B changes, that doesn’t mean that button B will scale when button A changes size.

You specify a view’s layout relationships by setting its HILayoutInfo structure:

struct HILayoutInfo {

    UInt32 version;

    HIBinding binding;

    HIScaling scale;

    HIPositioning position;

    };

The version field simply indicates the version of this data structure (in case it changes in the future); set this field to kHILayoutInfoVersionZero.

The binding, scale, and position fields each point to additional structures that indicate the specific layout constraints for this view.

You can use the view layout APIs to specify layout relationships between any two views (siblings, parents, and so on). The layouts are applied in the following order: binding, scaling, then positioning. Note that some layout information when applied may override previous constraints. For example, positioning constraints may override the bindings set in the HIBinding structure.

• To set layout constraints, you must first call the HIViewGetLayoutInfo function to obtain the layout structure:

  OSStatus HIViewGetLayoutInfo (HIViewRef inView,

  HILayoutInfo *outLayoutInfo);

  Then you can modify the fields of the structure to specify the layout constraints you want.

• To set the layout relationships for a view, you use the HIViewSetLayoutInfo function:

  OSStatus HIViewSetLayoutInfo (HIViewRef inView,

  const HILayoutInfo *inLayoutInfo);

• If you set a layout that constrains view A to view B, the layouts do not get implemented until either view B moves or resizes, or you call the HIViewApplyLayout function on view A:

  OSStatus HIViewApplyLayout (HIViewRef inView);

• Layouts are active by default. To temporarily disable the layout constraints, call HIViewSuspendLayout. To resume the layout, call HIViewResumeLayout:

  OSStatus HIViewSuspendLayout (HIViewRef inView);

  OSStatus HIViewResumeLayout (HIView inView);

• To determine if the layout is active or suspended, call the HIViewIsLayoutActive function:

  Boolean HIViewIsLayoutActive (HIViewRef inView);

The HIBinding Structure

The HIBinding structure specifies the layout bindings for all four sides of the view:

struct HIBinding {

HISideBinding top;

HISideBinding left;

HISideBinding right;

HISideBinding bottom;

}

The HISideBinding structure indicates the binding constraints for a specific side:

struct HISideBinding {

HIViewRef toView;

HIBindingKind kind;

};

The toView field indicates the view you want to bind to. The kind field specifies the side of the inView view to bind to. You can pass any of the following constants in the kind field: kHILayoutBindLeft, kHILayoutBindRight, kHILayoutBindTop, kHILayoutBindBottom.

For example, say you bind the top edge of view A to the top edge of view B as in Figure 2-1.

You can move view A as you please, as binding seeks to preserve only the relative positioning between view A and B.

If view B moves (or resizes), view A must also move (or resize) to preserve the specified binding. In this case, that means to maintain the vertical distance between the top edges of view A and view B.

You can bind all four edges of your view if you desire. Note that your view’s bounds may change if that is required to maintain the specified bindings.

The HIPositioning Structure

The HIPosition structure specifies the position constraints for the view’s axes:

struct HIPositioning {

HIAxisPosition x;

HIAxisPosition y;

}

The HIAxisPosition structure contains the specific positioning constraints for each axis:

struct HIAxisPosition {

HIViewRef toView;

HIPositionKind kind;

float offset;

};

The toView field indicates the view that constrains your view. The kind field indicates along which line or side the two views are aligned. You can pass kHILayoutPositionCenter, kHILayoutPositionLeft, kHILayoutPositionRight, kHILayoutPositionTop, or kHILayoutPositionBottom. The offset field indicates any optional offset to include between toView and your view.

For example, say you position the y axis of view A to match the top edge of view B (that is, positionKind = kHILayoutPositionTop, offset = 0), as in Figure 2-2.

View A cannot move up or down, as it is position-constrained to match the top edge of view B.

If view B moves or resizes, view A must move or resize to match any change in view B’s y coordinate.

struct HIScaling {

    HIAxisScale x;

    HIAxisScale y;

    };

struct HIAxisScale {

    HIViewRef toView;

    HIScaleKind kind;

    float ratio;

    };

Ordering Views

You can also set and manipulate the ordering of subviews within a parent view. This process is similar to ordering (sometimes called z-ordering) windows within an application, with views layered from top to bottom.

• To order a view in front of or behind a sibling view, call the HIViewSetZOrder function:

  OSStatus HIViewSetZOrder (HIViewRef inView, HIViewZOrderOp inOp,

  HIViewRef inOther);

  The inOp parameter (possible values: kHIViewZOrderAbove or kHIViewZOrderBelow) determines the position of inView with respect to inOther.

• To obtain the first (that is, topmost) subview in a parent view, call the HIViewGetFirstSubview function:

  HIViewRef HIViewGetFirstSubview (HIViewRef inParentView);

• To obtain the last (bottommost) subview in a parent view, call the HIViewGetLastSubview function:

  HIViewRef HIViewGetLastSubview (HIViewRef inParentView);

• To obtain the next view after a specified one, call the HIViewGetNextView function:

  HIViewRef HIViewGetNextView (HIViewRef inView);

• To obtain the previous view before a specified one, call the HIViewGetPreviousView function:

  HIViewRef HIViewGetPreviousView (HIViewRef inView);

HIView Visibility

Just like controls, you can set or test for the visibility of views.

• To set the visibility of a view, call the HIViewSetVisible function:

  OSStatus HIViewSetVisible (HIViewRef inView, Boolean inVisible);

  This function is analogous to the older SetControlVisibility function. Hiding a view also hides any embedded subviews.

• To determine whether a view is visible, call the HIViewIsVisible function:

  Boolean HIViewIsVisible (HIViewRef inView);

Note that you can also use the Control Manager functions SetControlVisibility and IsControlVisible on views.

Changing Keyboard Focus

In Mac OS X v10.2 and later, most views can acquire keyboard focus. This feature allows a user to select a checkbox, enter text, or click a button entirely through the keyboard. The user presses the Tab key to advance the focus and Shift-Tab to move it backwards. Pressing the Space bar activates the view with focus.

Your application should allow the user to advance focus and activate focused views. HIView provides several functions to change keyboard focus:

• To advance the focus to the next appropriate view, call the HIViewAdvanceFocus function:

  OSStatus HIViewAdvanceFocus (HIViewRef inRootForFocus,

  EventModifiers inModifiers);

  You pass in the root of the subtree in which to confine the focus. That is, if you pass in a content view as the root, the focus is confined to the subviews within the content view. You must also pass in the event modifiers parameter of the keyboard event that resulted in the call to HIViewAdvanceFocus.

  HIViewAdvanceFocus sends a kEventControlSetFocusPart event whenever a view is requested to gain, advance, or lose keyboard focus.

  Note that if your window uses the standard event handler, the basic focus-shifting work (acquiring the raw keyboard input, calling HIViewAdvanceFocus and so on) is handled for you, and the standard views support the kEventControlSetFocusPart event. However, if you are creating a custom view, you may need to handle the kEventControlSetFocusPart event yourself.

  Menus and menu items automatically gain keyboard focus support, independent of any standard event handlers.

• HIViewAdvanceFocus uses its own algorithm to determine the next view to acquire focus, generally attempting to move the focus from left to right, top to bottom, taking groups of views into account. However, if you want to explicitly specify which view should follow a given view in the focus chain, call the HIViewSetNextFocus function:

  OSStatus HIViewSetNextFocus (HIViewRef inView,

  HIViewRef inNextFocus);

Translating Coordinates

Although HIView simplifies most operations by adopting a view-relative coordinate system, at times you may need to know the coordinates of a object relative to a different view. The HIView API provides several functions to simplify these translations:

• To translate the coordinates of a point from one view to another, call the HIViewConvertPoint function:

  OSStatus HIViewConvertPoint (HIPoint *inPoint, HIViewRef inSourceView,

  HIViewRef inDestView);

• To translate an HIRect structure from one view to another, call the HIViewConvertRect function:

  OSStatus HIViewConvertRect (HIRect *ioRect, HIViewRef inSourceView,

  HIViewRef inDestView);

• To translate a region from one view to another, call the HIViewConvertRegion function:

  OSStatus HIViewConvertRegion (RgnHandle ioRgn, HIViewRef inSourceView,

  HIViewRef inDestView);

For example, if you wanted to obtain the global coordinates of a point within a view, (to be used in, say, a call to WaitMouseUp), you can call HIViewConvertPoint to obtain the window-relative coordinates. You can then get to global coordinates by calling GetWindowBounds, specifying the structure region, and add the top left global point of the window to the window-relative point.

Drawing in Views

You can use any of the usual Quartz functions to draw in your views. However, because HIView flips the Core Graphics context it passes to you, you draw using the QuickDraw coordinate system by default. If you need to draw images, you can use the HIViewDrawCGImage function, which flips the Core Graphics context (CGContext) back to the Quartz coordinate system, draws the image, and then flips the context back:

OSStatus HIViewDrawCGImage (CGContextRef inContext,

                                const HIRect *inBounds,

                                CGImageRef inImage);

This function is essentially identical to the Quartz function CGContextDrawImage except that it reverses the direction of the y-coordinate axis.

If you prefer to draw in your view using the Quartz coordinate system, you can translate the context you receive in your drawing handler

HIViewGetBounds (view, &bounds);

CGContextTranslateCTM (theContext, 0, bounds.size.height);

CGContextScaleCTM (theContext, 1.0, -1.0);

The CGContextTranslateCTM shifts the origin of the y-axis by the height of the view bounds, while the CGContextScaleCTM call invert the y-axis.

Note that unlike in older system software, you should never draw your views outside of a kEventControlDraw handler; do not use the Control Manager functions UpdateControls, DrawControls, or Draw1Control to draw to the screen. Instead, you must let the system know that a view, or a portion thereof, needs to be updated. This process is analogous to the older method of adding dirty areas to an update region.

To mark a view as dirty and needing to be redrawn, call the HIViewSetNeedsDisplay function:

OSStatus HIViewSetNeedsDisplay (HIViewRef inView,

                                    Boolean inNeedsDisplay);

Pass true for the inNeedsDisplay parameter if you want the view updated. You should make this call wherever you would have previously called DrawControls.

If you need to update only a portion of a view, you can call the HIViewSetNeedsDisplayInRegion function:

OSStatus HIViewSetNeedsDisplayInRegion (HIViewRef inView, RgnHandle inRgn,

                                            Boolean inNeedsDisplay);

In Mac OS X v10.4 and later you can also use the HIViewSetNeedsDisplayInRect and HIViewSetNeedsDisplayInShape functions:

OSStatus HIViewSetNeedsDisplayInRect( HIViewRef inView,

                const HIRect *  inRect, Boolean inNeedsDisplay);

OSStatus HIViewSetNeedsDisplayInShape( HIViewRef inView,

                HIShapeRef   inArea, Boolean inNeedsDisplay)

At the appropriate time, the system copies the updated regions to the screen (or calls your drawing routines).

In rare cases where you want to redraw your view immediately, you can call the HIViewRender function in Mac OS X v10.3 and later. Doing so allows you to bypass firing Carbon event timers or any other actions that may occur when cycling through the event loop.

You can turn off drawing related to a view by calling the HIViewSetDrawingEnabled function:

OSStatus HIViewSetDrawingEnabled (HIViewRef inView, Boolean inEnabled);

Turning off drawing in a view also affects any subviews embedded within it.

When drawing is turned off, the view is not drawn or updated (that is, calls to HIViewSetNeedsDisplay or even Draw1Control have no effect).

To determine whether drawing is allowed for a view, call the HIViewIsDrawingEnabled function:

Boolean HIViewIsDrawingEnabled (HIViewRef inView);

Manipulating Menu Views

Beginning in Mac OS X v10.3, all menus are implemented as views. This feature allows additional flexibility in creating or modifying menus. The actual menu content views are created lazily, as needed. That is, the Menu Manager does not create the menu content view, or even the owning window/root view/content view hierarchy that holds it, until the user first clicks on a menu title in the menu bar.

Listing 2-1 gives an example of how you can manipulate a menu as a view. This example allows you to install an event handler on the menu content view.

Listing 2-1  Creating a menu with an embedded image

IBNibRef nibRef;

MenuRef myMenuRef;

HIViewRef theView;

EventTypeSpec myEvent;

…

CreateMenuFromNib (nibRef, CFSTR ("myMenu"),&myMenuRef);

InsertMenu (myMenuRef, 0);

HIMenuGetContentView (myMenuRef, kThemeMenuTypePullDown, &theView);

myEvent.eventClass = kEventClassControl;

myEvent.eventKind = kEventControlOwningWindowChanged;

InstallControlEventHandler (theView, myPictureHandler, 2, &myEvent,0, NULL);

Here is how the code works:

1. First create the menu. The easiest way is to load it from a nib file, but you can use older Menu Manager functions to do so as well. After creating the menu, use InsertMenu to install it into the menu bar. At this point, none of the menu content views or owning windows have been created.

2. Call HIMenuGetContentView on your menu reference to obtain the menu content view associated with it. This is the view that displays the menu items. Note that making this call forces an instantiation of the menu content view before it actually needs to be displayed.

3. Install an event handler for the kEventControlOwningWindowChanged event on the menu content view. This event is sent when the menu content view is attached to a window content view for display (which occurs the first time the user clicks the menu title to display the menu).

Listing 2-2 shows a possible implementation for the event handler installed in Listing 2-1. This example installs an image view in your menu content view so that it appears behind the menu items.

Listing 2-2  Adding an image view to a menu

OSStatus PictureHandler( EventHandlerCallRef caller, EventRef event,

                            void* refcon )

{

    OSStatus    err = eventNotHandledErr;

    WindowRef   owner;

    GetEventParameter( event, kEventParamControlCurrentOwningWindow,

                     typeWindowRef, NULL, sizeof( owner ), NULL, &owner );

    if ( owner != NULL )

    {

        // find the content view

        HIViewRef content;

        HIViewFindByID( HIViewGetRoot( owner ), kHIViewWindowContentID,

                         &content );

        // create a data provider for our image

        CFURLRef url = CFBundleCopyResourceURL( CFBundleGetMainBundle(),

                            CFSTR("GoldenGate"), CFSTR("jpg"), NULL );

        CGDataProviderRef data = CGDataProviderCreateWithURL( url );

        CFRelease( url );

        // create our image

        CGImageRef image = CGImageCreateWithJPEGDataProvider( data, NULL,

                                     true, kCGRenderingIntentDefault );

        CFRelease( data );

        // create our image view

        HIViewRef imageView;

        HIImageViewCreate( image, &imageView );

        HIImageViewSetOpaque( imageView, false );

        HIImageViewSetAlpha( imageView, 0.3 );

        CFRelease( image );

        // position our image view below the content view's children

        HIViewAddSubview( content, imageView );

        HIViewSetZOrder( imageView, kHIViewZOrderBelow, NULL );

        HIViewSetVisible( imageView, true );

        // size our image view to match the content view

        HIRect bounds;

        HIViewGetBounds( content, &bounds );

        HIViewSetFrame( imageView, &bounds );

    }

    return err;

}

Here is how the code works:

1. Call GetEventParameter to obtain a reference to the window that owns this menu. Note that each menu has its own separate owning window (including submenus).

2. Call HIViewFindByID to obtain the content view for the window. This is the view that contains the menu content view, and also the one in which the image view will be embedded.

3. Create a data provider for the image you want to display. First, call the Core Foundation function CFBundleCopyResourceURL to get the URL to the image in the bundle, then call the Core Graphics function CGDataProviderCreateWithURL to obtain a data provider. After creating the data provider, you can release the URL by calling CFRelease.

4. Next, create a Core Graphics image from the data provider by calling CGImageCreateWithJPEGDataProvider. After creating the image, you can release the data provider.

5. Call HIImageViewCreate to create an image view from the Core Graphics image. After creating the image view, you can dispose of the Core Graphics image by calling CFRelease.

6. Passing false to HIImageViewSetOpaque specifies that the image view is not opaque.

7. Set the transparency of the image view by calling HIViewSetAlpha. Making the image translucent allows the background of the window content view (that is, the light gray striping) to show through. The alpha range can vary from 0 (transparent) to 1 (opaque).

8. Call HIViewAddSubview to add the image view to the window content view.

9. Call HIViewSetZOrder to place the image view behind the menu content view.

10. Call HIViewSetVisible to make the image view visible.

11. Lastly, set the bounds of the image view to be the same as that of the window content view. Doing so ensures that the image covers the entire background of the menu. HIViewGetBounds obtains the bounds of the window content view, and HIViewSetFrame sets the bounds of the image view to match those of the content view.

View-based menus allow you even more flexibility when creating custom menu items. For example, you can draw into your menus using Quartz, embed controls within the menu, and so on. Instead of creating custom MDEFs for your menus, you simply create a custom view, and implement Carbon events to handle any required messaging. See Creating Custom Menus for more information.

Creating a Scroll View

The HIView scroll view provides an easy way to display a scrollable image. For example, you can simply embed an image view within the scroll view and the scroll view automatically handles the scrolling of the image; you don’t need to worry about installing live feedback handlers, adjusting scroller positions and sizes, or moving pixels.

Listing 2-3 shows a simple example of displaying a scrollable JPEG image in a document window. This example assumes that the image you want to display is a JPEG file installed in your application bundle (in the Resources folder).

Listing 2-3  Creating a scroll view with an embedded image

WindowRef scrollWindow;

Rect windowBounds = {100, 100, 500, 550};

HIRect myViewRect;

HIViewRef myImageView, myScrollView, myContentView;

CGImageRef myImage;

CGDataProviderRef myProvider;

CFBundleRef theAppBundle;

CFStringRef filename;

CFURLRef theURL;

CreateNewWindow (kDocumentWindowClass, kWindowStandardHandlerAttribute |

             kWindowCompositingAttribute, &windowBounds,&scrollWindow);

/* Get the JPEG image from a file. */

theAppBundle = CFBundleGetMainBundle();

filename = CFStringCreateWithCString(NULL, "CowPuppy.jpg",

                kCFStringEncodingASCII);

theURL = CFBundleCopyResourceURL (theAppBundle, filename, NULL, NULL);

/* Quartz stuff to put the JPEG image into an image view */

myProvider = CGDataProviderCreateWithURL(theURL);

myImage = CGImageCreateWithJPEGDataProvider (myProvider, NULL, false,

                                     kCGRenderingIntentDefault);

CGDataProviderRelease (myProvider);

CFRelease(filename);

/* Now create the scroll view and image view. */

HIScrollViewCreate (kHIScrollViewOptionsVertScroll |

                     kHIScrollViewOptionsHorizScroll, &myScrollView);

HIViewSetVisible (myScrollView, true);

HIViewFindByID(HIViewGetRoot(scrollWindow), kHIViewWindowContentID,

                 &myContentView);

HIViewAddSubview (myContentView, myScrollView);

myViewRect.origin.x = 50.0;

myViewRect.origin.y = 10.0;

myViewRect.size.width = 300.0;

myViewRect.size.height = 300.0;

HIViewSetFrame (myScrollView, &myViewRect);

HIImageViewCreate (myImage, &myImageView);

CGImageRelease (myImage);

HIViewSetVisible (myImageView, true);

HIViewAddSubview (myScrollView, myImageView);

ShowWindow (scrollWindow);

Here is how the code works:

1. Call CreateNewWindow to create a new document window. Note that you must set the kWindowCompositingAttribute attribute if you want to use HIView objects in the window. Use of the standard window handler is also highly recommended.

   If you are creating a window from a nib file, you must set the Compositing checkbox for the window from the Info window in Interface Builder.

2. Call the Core Foundation CFBundle function CFBundleGetMainBundle to find the main application bundle.

3. Create a CFString of the name of the image file using the Core Foundation function CFStringCreateWithCString.

4. Call the Core Foundation function CFBundleCopyResourceURL to build a URL path to the image file in the application bundle.

5. Use the Core Graphics function CGDataProviderCreateWithURL to create a data provider. In Quartz, you need to create data providers before creating a CGImage object.

6. Call the Core Graphics function CGImageCreateWithJPEGDataProvider to create a CGImage object from the JPEG file.

7. After creating the CGImage object, you can release the data provider and the CFString filename object by calling CGDataProviderRelease and CFRelease respectively.

8. To create the scroll view, call the HIScrollViewCreate function. This example passes in options specifying both horizontal and vertical scroll bars.

9. Call HIViewSetVisible to make the scroll view visible.

10. In order to embed the scroll view properly, you need to obtain the content view of the window. You do so by calling the HIViewFindByID function, specifying that you want to find the content view. Note that this function requires the root view as its first parameter. To obtain the root view for this window, you must call HIViewGetRoot.

    Note that to obtain the content view, you could also call the Control Manager function GetRootControl.

11. To embed the scroll view in the content view, call the HIViewAddSubview function. Note that at this point, although the scroll view is embedded in the content view, it has no bounds (that is, it has no physical location or size).

12. To set the bounds of the scroll view, you fill in an HIRect structure. Note that this structure has a format different from that of the QuickDraw Rect structure. This example creates a 300 pixel square scroll view located at (50,10) in the local coordinates of the content view.

13. Once you specify the bounds in myViewRect, you pass them into the HIViewSetFrame function to set the frame bounds of the scroll view (that is, the coordinates of the scroll view relative to the content view).

    If you want the scroll view to occupy the entire content view, you can call HIViewGetBounds (not HIViewGetFrame) on the content view and pass the resulting HIRect into HIViewSetFrame for the scroll view.

14. To create the image view, you call HIImageViewCreate, passing in the CGImage object you obtained from CGImageCreateWithJPEGDataProvider.

15. After creating the image view, you can dispose of the CGImage object by calling the Core Graphics function CGImageRelease.

16. Call HIViewSetVisible to make the image view visible.

17. Call HIViewAddSubview to embed the image view within the scroll view. The image view will appear with the top-left corner aligned with the scroll view’s origin.

18. Call the Window Manager function ShowWindow to display the window with the scroll view.

If you create your scroll view to be resizable, by passing true to the HIScrollViewSetScrollBarAutoHide function, you can specify that the scroll bars be hidden if the scroll view is enlarged to the point that the entire image is visible.

Creating a Combo Box

HIView lets you create a combo box control using simple function calls. All of the basic pop-up behavior and item selection is handled for you automatically. In addition, HIView combo boxes also support the following optional features, which you set by specifying attributes during creation:

• auto-completion in the editable text field (kHIComboBoxAutoCompletionAttribute)

• automatic disclosure of list items when the user enters text (kHIComboBoxAutoDisclosureAttribute)

• alphabetical sorting of list items (kHIComboBoxAutoSortAttribute)

• automatic resizing of the list to conform to the Aqua human interface guidelines (kHIComboBoxAutoSizeListAttribute). Note that if you do not specify this attribute, you must size the list yourself using Control Manager SetControlData tags. Otherwise the size of the list is undefined. See HIView.h for a listing of available combo box data tags.

Listing 2-4 shows a code fragment that creates the simple combo box in Figure 1-7.

Listing 2-4  Creating a simple combo box

WindowRef myPrefsWindow;

HIViewRef myCombo, myContentView;

HIRect hiRect;

Rect myBounds = {100, 100, 500, 500};

Rect ComboRect = {0, 0, 20, 100};

CreateNewWindow (kMovableModalWindowClass, kWindowStandardHandlerAttribute|

                kWindowCompositingAttribute, &myBounds,&myPrefsWindow);

hiRect.origin.x = ComboRect.left;

hiRect.origin.y = ComboRect.top;

hiRect.size.width = ComboRect.right-ComboRect.left;

hiRect.size.height = ComboRect.bottom-ComboRect.top;

HIComboBoxCreate (&hiRect, CFSTR ("Hobbes"), NULL, NULL,

                    kHIComboBoxStandardAttributes, &myCombo);

HIViewSetVisible (myCombo, true);

HIViewFindByID (HIViewGetRoot(myPrefsWindow),kHIViewWindowContentID,

                 &myContentView);

HIViewAddSubview (myContentView, myCombo);

HIViewPlaceInSuperviewAt (myCombo, 25.0, 25.0);

HIComboBoxAppendTextItem (myCombo, CFSTR ("Hobbes"), NULL);

HIComboBoxAppendTextItem (myCombo, CFSTR ("Plato"), NULL);

HIComboBoxAppendTextItem (myCombo, CFSTR ("Heidegger"), NULL);

HIComboBoxAppendTextItem (myCombo, CFSTR ("Aristotle"), NULL);

ShowWindow (myPrefsWindow);

Here is what the code does:

1. This example places the combo box in a movable modal window created using CreateNewWindow. Note that you must specify the kWindowCompositingAttribute attribute.

2. This example originally specifies the bounds of the combo box as a QuickDraw Rect structure and then translates those coordinates into a Quartz-compatible HIRect structure.

3. To create the combo box, call the HIComboBoxCreate function. You specify the following parameters:

   • The bounds of the combo box, as an HIRect structure.

   • The initial text in the editable text field as a Core Foundation CFString. This text could indicate the kind of item the user should enter, or the default item selection.

   • A pointer to a Control Manager ControlFontStyleRec structure indicating the font style to use for this combo box. Pass NULL (as in this example) if you want to use the default system font.

   • A Core Foundation CFArray containing the items you want to display in the item list. You can also pass NULL (as in this example) and add items on-the-fly later.

   • The attributes you want for this combo box. Specifying kHIComboBoxStandardAttributes gives you the automatic sizing, list disclosure, and text completion features.

   On return, myCombo contains the new combo box.

4. As usual, the new HIView is initially hidden, so call HIViewSetVisible to make it visible.

5. To embed the combo box in the movable modal window’s content view, you can call HIViewFindByID and HIViewAddSubview, just as in Listing 2-3. However, as an alternative to using HIViewSetFrame to position the combo box in the view, you can call the HIViewPlaceInSuperviewAt function. You can do this because the combo box already has a size; you now need to specify only a position. The coordinates you specify indicate the top-left corner of the view’s bounds.

6. You can add items to the combo box list by simply calling the HIComboBoxAppendTextItem function. This example adds four items.

Creating Custom Views

One of the advantages of HIView is that you can subclass an existing view when creating a custom view. In object-oriented fashion, a view is essentially a class defined by Carbon event handlers (essentially methods) and instance data. To create a custom view, you must create a subclass of HIView and add your custom functionality by overriding event handlers.

OSStatus HIObjectRegisterSubclass (CFStringRef inClassID,

                                CFStringRef inBaseClassID,

                                OptionBits inOptions,

                                EventHandlerUPP inConstructProc,

                                UInt32 inNumEvents,

                                const EventTypeSpec *inEventList,

                                void* inConstructData,

                                HIObjectClassRef *outClassRef);

#define kMyCustomViewClassID CFSTR("com.myCorp.myApp.myView")

OSStatus myCustomViewRegister()

{

    OSStatus                err = noErr;

    static HIObjectClassRef sMyViewClassRef = NULL;

    if ( sMyViewClassRef == NULL )

    {

        EventTypeSpec       eventList[] = {

            { kEventClassHIObject, kEventHIObjectConstruct },

            { kEventClassHIObject, kEventHIObjectInitialize },

            { kEventClassHIObject, kEventHIObjectDestruct },

            { kEventClassControl, kEventControlInitialize },

            { kEventClassControl, kEventControlDraw },

            { kEventClassControl, kEventControlHitTest },

            { kEventClassControl, kEventControlGetPartRegion } };

        err = HIObjectRegisterSubclass(

            kMyCustomViewClassID,       // class ID

            kHIViewClassID,             // base class ID

            NULL,                       // option bits

            myCustomViewHandler,        // construct proc

            GetEventTypeCount( eventList ),

            eventList,

            NULL,                       // construct data,

            &sMyViewClassRef );

    }

    return err;

}

OSStatus myCustomViewHandler(

    EventHandlerCallRef     inCallRef,

    EventRef                inEvent,

    void*                   inUserData )

{

    OSStatus                err = eventNotHandledErr;

    UInt32                  eventClass = GetEventClass( inEvent );

    UInt32                  eventKind = GetEventKind( inEvent );

    myCustomViewData*       data = (myCustomViewData*) inUserData;

    switch ( eventClass )

    {

        case kEventClassHIObject:

        {

            switch ( eventKind )

            {

                case kEventHIObjectConstruct:

                    err = myCustomViewConstruct( inEvent );

                    break;

                case kEventHIObjectInitialize:

                    err = myCustomViewInitialize( inCallRef, inEvent,

                                                    data );

                    break;

                case kEventHIObjectDestruct:

                    err = myCustomViewDestruct( inEvent, data );

                    break;

            }

        }

        break;

        case kEventClassControl:

        {

            switch ( eventKind )

            {

                case kEventControlInitialize:

                    err = noErr;

                    break;

                case kEventControlDraw:

                    err = myCustomViewDraw( inEvent, data );

                    break;

                case kEventControlHitTest:

                    err = myCustomViewHitTest( inEvent, data );

                    break;

                case kEventControlGetPartRegion:

                    err = myCustomViewGetRegion( inEvent, data );

                    break;

            }

        }

        break;

    }

    return err;

}

typedef struct

{

    ControlRef control;

} myCustomViewData;

OSStatus myCustomViewConstruct (EventRef inEvent)

{

    OSStatus                err;

    myCustomViewData*       data;

    data = malloc( sizeof( myCustomViewData ) );

    require_action( data != NULL, CantMalloc, err = memFullErr );

    err = GetEventParameter( inEvent, kEventParamHIObjectInstance,

                            typeHIObjectRef, NULL, sizeof( HIObjectRef ),

                            NULL, (HIObjectRef*) &data->control );

    require_noerr( err, ParameterMissing );

    // Set the userData to be used with all subsequent eventHandler calls

    err = SetEventParameter( inEvent, kEventParamHIObjectInstance,

                            typeVoidPtr, sizeof( myCustomViewData* ),

                            &data );

ParameterMissing:

    if ( err != noErr )

        free( data );

CantMalloc:

    return err;

}

OSStatus myCustomViewDestruct (EventRef inEvent,

                                myCustomViewData* inData)

{

    free (inData);

    return noErr;

}

OSStatus myCustomViewInitialize (EventHandlerCallRef inCallRef,

                            EventRef inEvent,

                            myCustomViewData* inData)

{

    OSStatus err;

    Rect bounds;

    // Let any parent classes have a chance at initialization

    err = CallNextEventHandler( inCallRef, inEvent );

    require_noerr( err, TroubleInSuperClass );

    // Extract the bounds from the initialization event

    err = GetEventParameter( inEvent, 'Boun', typeQDRectangle,

            NULL, sizeof( Rect ), NULL, &bounds );

    require_noerr( err, ParameterMissing );

    // Resize the view

    SetControlBounds( inData->control, &bounds );

ParameterMissing:

TroubleInSuperClass:

    return err;

}

OSStatus CreateMyCustomView ( WindowRef inWindow, const Rect*inBounds,

                                ControlRef* outControl )

{

    OSStatus            err;

    ControlRef          root;

    EventRef            event;

    // Register this class

    err = myCustomViewRegister();

    require_noerr( err, CantRegister );

    // Make an initialization event

    err = CreateEvent( NULL, kEventClassHIObject, kEventHIObjectInitialize,

                        GetCurrentEventTime(), 0, &event );

    require_noerr( err, CantCreateEvent );

    // If bounds were specified, push the them into the initialization event

    // so that they can be used in the initialization handler.

    if ( inBounds != NULL )

    {

        err = SetEventParameter( event, 'Boun', typeQDRectangle,

                sizeof( Rect ), inBounds );

        require_noerr( err, CantSetParameter );

    }

    err = HIObjectCreate( kMyCustomViewClassID, event, (HIObjectRef*)

                            outControl );

    require_noerr( err, CantCreate );

    // If a parent window was specified, place the new view into the

    // parent window.

    if ( inWindow != NULL )

    {

        err = GetRootControl( inWindow, &root );

        require_noerr( err, CantGetRootControl );

        err = HIViewAddSubview( root, *outControl );

    }

CantCreate:

CantGetRootControl:

CantSetParameter:

CantCreateEvent:

    ReleaseEvent( event );

CantRegister:

    return err;

}

enum {kMenuDefClassID = 1};

struct MenuDefSpec

{

    MenuDefType defType;

    union

    {

        MenuDefUPP defProc;

        struct

        {

            CFStringRef classID;

            EventRef initEvent;

            }view;

        }u;

    }

typedef struct

{

    HIViewRef           view;

    HIViewRef           button;

}

MyMenuData;

static const EventTypeSpec  kMyMenuEvents[] =

{

    { kEventClassHIObject, kEventHIObjectConstruct },

    { kEventClassHIObject, kEventHIObjectDestruct },

    { kEventClassControl, kEventControlInitialize },

    { kEventClassControl, kEventControlBoundsChanged },

    { kEventClassControl, kEventControlGetOptimalBounds },

    { kEventClassScrollable, kEventScrollableGetInfo }

};

static pascal OSStatus MyMenuHandler( EventHandlerCallRef inCaller,

                        EventRef inEvent, void* inRefcon )

{

    OSStatus    err = eventNotHandledErr;

    MyMenuData* data = (MyMenuData*) inRefcon;

    switch ( GetEventClass( inEvent ) )

    {

        case kEventClassHIObject:

            switch ( GetEventKind( inEvent ) )

            {

                case kEventHIObjectConstruct:

                {

                    data = (MyMenuData*) calloc( 1, sizeof( MyMenuData ) );

                    require_action( data != NULL, CouldntAllocData,

                                    err = memFullErr );

                    GetEventParameter(inEvent,kEventParamHIObjectInstance,

                            typeHIObjectRef, NULL, sizeof( data->view ),

                            NULL, &data->view );

                    SetEventParameter(inEvent,kEventParamHIObjectInstance,

                             typeVoidPtr, sizeof( data ), &data );

                    err = noErr;

                    break;

                }

                case kEventHIObjectDestruct:

                    free( (void*) data );

                    err = noErr;

                    break;

            }

            break;

        case kEventClassControl:

            switch ( GetEventKind( inEvent ) )

            {

                case kEventControlInitialize:

                {

                    Rect        bounds = { 0, 0, 0, 0 };

                    err = CreatePushButtonControl( NULL, &bounds,

                                     CFSTR("Beep!"), &data->button );

                    require_noerr( err, CouldntCreateButton );

                    HIViewAddSubview( data->view, data->button);

                    break;

                }

                case kEventControlGetOptimalBounds:

                {

                    HIRect bounds = { { 0, 0 }, { 90, 100} };

                    SetEventParameter( inEvent,

                                 kEventParamControlOptimalBounds,

                                 typeHIRect, sizeof( bounds ), &bounds );

                    err = noErr;

                    break;

                }

                case kEventControlBoundsChanged:

                {

                    HIRect bounds;

                    HIViewGetBounds( data->view, &bounds );

                    HIRect frame;

                    frame.origin.x = 10;

                    frame.origin.y = bounds.size.height/2 - 10;

                    frame.size.height = 20;

                    frame.size.width = bounds.size.width - 20;

                    HIViewSetFrame( data->button, &frame );

                    err = noErr;

                    break;

                }

            }

            break;

        case kEventClassScrollable:

            switch ( GetEventKind( inEvent ) )

            {

                case kEventScrollableGetInfo:

                {

                    HIRect bounds;

                    HIPoint origin = { 0, 0 };

                    HIViewGetBounds( data->view, &bounds );

                    SetEventParameter( inEvent, kEventParamImageSize,

                         typeHISize, sizeof( bounds.size ), &bounds.size );

                    SetEventParameter( inEvent, kEventParamViewSize,

                         typeHISize, sizeof( bounds.size ), &bounds.size );

                    bounds.size.height = 20;    // arbitrary

                    SetEventParameter( inEvent, kEventParamLineSize,

                         typeHISize, sizeof( bounds.size ), &bounds.size );

                    SetEventParameter( inEvent, kEventParamOrigin,

                         typeHIPoint, sizeof( origin ), &origin );

                    err = noErr;

                    break;

                }

            }

            break;

    }

CouldntCreateButton:

CouldntAllocData:

    return err;

}

#define kMyCustomMenuViewClassID CFSTR("com.apple.sample.kMyCustomMenuClassID")

OSStatus MyCreateCustomMenu (MenuID theID)

{

    MenuDefSpec     defSpec;

    MenuRef         theMenu;

    HIObjectClassRef theClassIDRef;

    OSStatus        err;

    HIObjectRegisterSubclass( kMyCustomMenuViewClassID,

                        kHIMenuViewClassID, kNilOptions, MyMenuHandler,

                        GetEventTypeCount( kMyMenuEvents ), kMyMenuEvents,

                        NULL, &theClassIDRef );

    defSpec.defType = kMenuDefClassID;

    defSpec.u.view.classID = kMyCustomMenuViewClassID;

    defSpec.u.view.initEvent = NULL;

    err = CreateCustomMenu( &defSpec, 0, 0, &theMenu );

    if ( err == noErr ) {

        SetMenuTitleWithCFString( theMenu, CFSTR("Button") );

        InsertMenu( theMenu, theID );

    }

    return err;

}