Embedding Views in a Toolbar Item

You can associate an HIView with a toolbar item. For example, you can place buttons, sliders, editable text fields, and other controls in the toolbar item. To do so, you must create a custom HIObject, specifically a subclass of the toolbar item class.

Note that, although the toolbar item is an HIObject, your view is not embedded within that object. For each window the toolbar is associated with, the toolbar item object creates a toolbar item view and then embeds your view within that.

Also, you do not have to supply your own item labels and help tags when creating your custom toolbar item; you can assign these as before using the HIToolbarItemSetLabel and HIToolbarItemSetHelpText functions.

To register your toolbar item subclass, you call the HIObjectRegisterSubclass function. The function in Listing 2-4 shows how you could do this.

Listing 2-4  Registering a toolbar item subclass

#define kMyButtonToolbarItemClassID CFSTR("com.moof.buttontoolbaritem")

void RegisterMyButtonToolbarItemClass()

{

    static bool sRegistered;

    if ( !sRegistered )

    {

        HIObjectRegisterSubclass( kMyButtonToolbarItemClassID,

                kHIToolbarItemClassID, 0, MyButtonToolbarItemHandler,

                GetEventTypeCount( buttonEvents ), buttonEvents, 0, NULL );

        sRegistered = true;

    }

}

This example registers a new toolbar item subclass (kMyButtonToolbarItemClassID) and its associated event handler MyButtonToolbarItemHandler. This toolbar item simply contains a standard push button.

For efficiency, this example also sets a static Boolean to avoid registering the custom item multiple times (although there is no penalty for doing so).

The MyButtonToolbarItemHandler must handle the HIObject construct, initialize, and destruct events. In addition, because you want to embed a view into the toolbar item view, you must also handle the kEventToolbarItemCreateCustomView event.

Listing 2-5 shows how you might implement the event handler for your custom button toolbar item.

Listing 2-5  Event handler for a toolbar item with an embedded view

const EventTypeSpec buttonEvents[] =

{

    { kEventClassHIObject, kEventHIObjectConstruct },

    { kEventClassHIObject, kEventHIObjectInitialize },

    { kEventClassHIObject, kEventHIObjectDestruct },

    { kEventClassToolbarItem, kEventToolbarItemCreateCustomView }

};

const EventTypeSpec pushButtonEvents[] =

{

    { kEventClassControl, kEventControlGetSizeConstraints}

};

struct MyButtonToolbarItem// 1

{

    HIToolbarItemRef        toolbarItem;

};

typedef struct MyButtonToolbarItem MyButtonToolbarItem;

static OSStatus MyButtonToolbarItemHandler( EventHandlerCallRef inCallRef,

                             EventRef inEvent, void* inUserData )

{

    OSStatus            result = eventNotHandledErr;

    MyButtonToolbarItem*    object = (MyButtonToolbarItem*)inUserData;// 2

    switch ( GetEventClass( inEvent ) )

    {

        case kEventClassHIObject:

            switch ( GetEventKind( inEvent ) )

            {

                case kEventHIObjectConstruct:// 3

                    {

                        HIObjectRef         toolbarItem;

                        MyButtonToolbarItem*    item;

                        GetEventParameter( inEvent,

                             kEventParamHIObjectInstance, typeHIObjectRef,

                             NULL, sizeof( HIObjectRef ), NULL,

                             &toolbarItem );

                        result = ConstructMyButtonToolbarItem(toolbarItem,

                             &item );

                        if ( result == noErr )

                            SetEventParameter( inEvent,

                                kEventParamHIObjectInstance, typeVoidPtr,

                                sizeof( void * ), &item );

                    }

                    break;

                case kEventHIObjectInitialize:// 4

                    if (CallNextEventHandler(inCallRef, inEvent) == noErr )

                        {

                            HIToolbarItemSetLabel( object->toolbarItem,

                                                 CFSTR( "Press Me" ) );

                            HIToolbarItemSetHelpText( object->toolbarItem,

                                                 CFSTR("Moof!"), NULL );

                            result = noErr;

                        }

                    break;

                case kEventHIObjectDestruct:// 5

                    free (object);

                    result = noErr;

                    break;

            }

            break;

        case kEventClassToolbarItem:

            switch ( GetEventKind( inEvent ) )

            {

                case kEventToolbarItemCreateCustomView:// 6

                    {

                        EventTargetRef myButtonEventTarget;

                        HIViewRef myButton;

                        Rect myButtonRect = {0,0,20,80};

                        CreatePushButtonControl(NULL, &myButtonRect,// 7

                             CFSTR("Push!"), &myButton);

                        SetEventParameter (inEvent, kEventParamControlRef,

                             typeControlRef, sizeof(myButton), &myButton);

                        myButtonEventTarget =

                                        GetControlEventTarget(myButton);

                        InstallEventHandler (myButtonEventTarget,// 8

                                MyButtonEventHandler,

                                GetEventTypeCount(pushButtonEvents),

                                pushButtonEvents, NULL, NULL);

                        result = noErr;

                    }

                    break;

            }

            break;

    }

    return result;

}

Here is what the code does:

1. Your subclass must have a structure associated with it that can hold any necessary instance data. This example requires only only one data item: the toolbar item reference. Note that even though this toolbar item provides an HIView, you do not store the HIView reference in this structure.

2. If your application defines any user data for this toolbar item, you can store it in the instance data.

3. When you receive the kEventHIObjectConstruct event, you receive a pointer to store the reference to your toolbar item in the kEventParamHIObjectInstance parameter. You must allocate memory for the item reference and any associated instance data. Here is a possible implementation for the ConstructMyToolbarButtonItem function:

   static OSStatus ConstructMyButtonToolbarItem( HIToolbarItemRef inItem,

   MyButtonToolbarItem** outItem )

   {

   MyButtonToolbarItem* item;

   OSStatus err = noErr;

   item = (MyButtonToolbarItem*)malloc( sizeof( MyButtonToolbarItem ) );

   require_action( item != NULL, CantAllocItem, err = memFullErr );

   item->toolbarItem = inItem;

   *outItem = item;

   CantAllocItem:

   return err;

   }

   After allocating the memory, use SetEventParameter to return a pointer to the space created for the toolbar item reference.

4. When you receive the kEventHIObjectInitialize event, you must perform any initialization that your toolbar item requires, such as setting initial values for some instance data. This example calls the HIToolbarSetItemLabel function to set the text portion of the toolbar item, and HIToolbarItemSetHelpText function to set the help tag text.

5. When you receive the kEventHIObjectDestruct event, you must release the memory that was allocated for your toolbar item. This example simply calls the Memory Manager function free to release the instance data. Note that you must not dispose your HIView reference here.

6. When you receive the kEventToolbarItemCreateCustomView, you must create an HIView to embed in the toolbar item view. Any sort of view is valid; you can embed a picture view, a text field, a button, or even your own custom HIView.

7. This example simply creates a standard push button control and then uses SetEventParameter to store its HIView reference in the kEventParamControlRef parameter of the event. Note that when creating standard views, you must pass NULL for the owning window parameter, as the view is not associated with any window.

8. All views that are associated with toolbar items must respond to the kEventControlGetSizeConstraints event, which asks for the maximum and minimum allowable sizes for the view. The system uses this information to determine how to best size the toolbar item view given its embedded content. In most cases you should simply return the bounds of the view, as in the following code:

   static OSStatus MyButtonEventHandler( EventHandlerCallRef inCallRef,

   EventRef inEvent, void* inUserData )

   {

   switch ( GetEventKind( inEvent ) )

   {

   case kEventControlGetSizeConstraints:

   {

   HISize minBounds = {80,20};

   HISize maxBounds = {80,20};

   SetEventParameter (inEvent,

   kEventParamMinimumSize, typeHISize,

   sizeof(HISize), &minBounds);

   SetEventParameter (inEvent,

   kEventParamMaximumSize, typeHISize,

   sizeof(HISize), &maxBounds);

   return noErr;

   }

   break;

   default:

   break;

   }

   return eventNotHandledErr;

   }

   Note that the HISize type is position-independent, indicating only the width and height of the object.

   Finally, you need to call HIObjectCreate to create an instance of your custom toolbar item. Listing 2-6 shows a function you could use to do this.

   
   
   

   Listing 2-6  Creating a custom toolbar item instance.

   HIToolbarItemRef CreateMyButtonToolbarItem( CFStringRef inIdentifier)

   {

   OSStatus err;

   EventRef event;

   UInt32 options = kHIToolbarItemAllowDuplicates;

   HIToolbarItemRef result = NULL;

   RegisterMyButtonToolbarItemClass();// 1

   err = CreateEvent( NULL, kEventClassHIObject,// 2

   kEventHIObjectInitialize, GetCurrentEventTime(), 0,

   &event );

   require_noerr( err, CantCreateEvent );

   SetEventParameter( event, kEventParamToolbarItemIdentifier,// 3

   typeCFStringRef, sizeof( CFStringRef ), &inIdentifier );

   SetEventParameter( event, kEventParamAttributes, typeUInt32, // 4

   sizeof( UInt32 ), &options );

   err = HIObjectCreate( kMyButtonToolbarItemClassID, event,// 5

   (HIObjectRef*)&result );

   check_noerr( err );

   ReleaseEvent( event );// 6

   CantCreateEvent:

   return result;

   }

Here is how the code works:

1. First, register your custom toolbar item by calling the RegisterMyButtonToolbarItemClass function in Listing 2-4.

2. Create an initialization event to send to your item once it is created. Note that this event is sent directly to the toolbar item (that is, it is not placed in the event queue).

3. Set the toolbar item’s identifier in the initialization event using the kEventParamToolbarIdentifier parameter.

4. Set any desired toolbar attributes in the initialization event using the kEventParamAttributes parameter.

   Note that the identifier and the toolbar attributes are the same parameters you would pass into the standard HIToolbarItemCreate function. If you do not set these parameters, the HIObjectCreate call fails.

5. Call HIObjectCreate to create an instance of your custom toolbar item class (kMyButtonToolbarClassID). On return, you receive a ToolbarItemRef (which is also an HIObjectRef) that points to the newly-created toolbar item.

6. After sending the initialization event to your toolbar item, you no longer need to retain it, so call ReleaseEvent.

Creating Items from a Drag

If the user drags something onto the toolbar, and your toolbar accepts drags, your application will have to create a toolbar item from the drag.

Listing 2-7 shows how you could process the drag to create a toolbar item. This example creates URLs from one or more text drag items.

Listing 2-7  Creating a toolbar item from a drag

static HIToolbarItemRef CreateToolbarItemFromDrag( DragRef drag )

{

    UInt16              i, itemCount;

    HIToolbarItemRef    result = NULL;

    CountDragItems( drag, &itemCount );// 1

    for ( i = 1; i <= itemCount; i++ )

    {

        DragItemRef         itemRef;

        FlavorFlags         flags;

        GetDragItemReferenceNumber( drag, i, &itemRef );// 2

        if ( GetFlavorFlags( drag, itemRef, 'TEXT', &flags ) == noErr )// 3

        {

            Size        dataSize;

            char        string[256];

            CFURLRef    url;

            dataSize = sizeof( string );

            GetFlavorData( drag, itemRef, 'TEXT', &string, &dataSize, 0 );// 4

            url = CFURLCreateWithBytes( NULL, string, dataSize,// 5

                             kCFStringEncodingMacRoman, NULL );

            result = CreateMyURLToolbarItem( CFSTR( "MyURLIdentifier" ), url );// 6

            CFRelease( url );// 7

            break;

        }

    }

    return result;

}

Here is how the code works:

1. This example uses a number of Drag Manager calls to process the drag item. First, you call the CountDragItems function on the drag reference to determine how many items are in the drag. (For example, the user might have selected and dragged several items into the toolbar.)

2. Now iterate over the number of drag items. For each item index number, obtain the item reference by calling GetDragItemReferenceNumber.

3. Use the Drag Manager function GetFlavorFlags to determine if the drag item content is of type TEXT. If so, the item contents can be turned into a URL toolbar item. If not, the drag item is rejected and the contents ignored.

4. If the drag flavor is compatible, call the Drag Manager function GetFlavorData to obtain the actual text associated with the drag item.

5. The Core Foundation function CFURLCreateWithBytes converts the string into a CFURL with the specified encoding (in this case, MacRoman).

6. Now pass the CFURL to a toolbar item creation function. This function, which is analogous to the CreateMyButtonToolbarItem function in Listing 2-6, should register the toolbar item subclass, create a kEventHIObjectInitialize event, and call HIObjectCreate.

   You should set several parameters in the initialize event before calling HIObjectCreate:

   • kEventParamToolbarIdentifier, the identifier for this toolbar item.

   • kEventParamAttributes, any toolbar attributes you want to set.

   • kEventParamToolbarItemConfigData, a pointer to any specific configuration data. In this case, the configuration data would be a pointer to the URL obtained from the drag.

7. After passing the CFURL to the toolbar item creation function, you can release your reference to it.

The event handler for your custom URL toolbar item class must handle the usual creation, destruction, and initialization events. The construction event allocates memory for the instance data, and the destruction event releases it. Note that the data structure for the instance data has two fields in this case: one to hold the toolbar item reference, and the other to hold the URL.

struct CustomToolbarItem

{

    HIToolbarItemRef        toolbarItem;

    CFURLRef                url;

};

typedef struct CustomToolbarItem CustomToolbarItem;

The initialization event handler must obtain the configuration data passed with the event and store that in the instance data as a URL. Listing 2-8 shows an example of how you could do this.

Listing 2-8  Initialization function for the kEventHIObjectInitialize event

/* Assume that the event handler called CallNextEventHandler before

/* calling this function */

static OSStatus InitializeCustomToolbarItem( CustomToolbarItem* inItem,// 1

                     EventRef inEvent )

{

    CFTypeRef       data;

    IconRef         iconRef;

    if ( GetEventParameter( inEvent, kEventParamToolbarItemConfigData,// 2

                     typeCFTypeRef, NULL,

            sizeof( CFTypeRef ), NULL, &data ) == noErr )

    {

        if ( CFGetTypeID( data ) == CFStringGetTypeID() )// 3

            inItem->url = CFURLCreateWithString( NULL, (CFStringRef)data,

                                         NULL );

        else

            inItem->url = (CFURLRef)CFRetain( data );

    }

    else

    {

        inItem->url = CFURLCreateWithString( NULL, // 4

                                CFSTR( "http://www.apple.com" ), NULL );

    }

    HIToolbarItemSetLabel( inItem->toolbarItem, CFSTR( "URL Item" ) );// 5

    if ( GetIconRef( kOnSystemDisk, kSystemIconsCreator, kGenericURLIcon,// 6

                     &iconRef ) == noErr )

    {

        HIToolbarItemSetIconRef( inItem->toolbarItem, iconRef );

        ReleaseIconRef( iconRef );// 7

    }

    HIToolbarItemSetHelpText( inItem->toolbarItem, // 8

                        CFURLGetString( inItem->url ), NULL );

    return noErr;

}

Here is how the code works:

1. This function takes two parameters: the toolbar item to initialize, and the initialization event that was sent to it.

2. Use GetEventParameter to obtain the configuration data stored in the initialization event. This is the URL obtained from the drag (the one stored in the kEventHIObjectInitialize event passed to HIObjectCreate.

3. If the configuration data passed is of type CFString, then you must call CFURLCreateWithString to convert it to a CFURL type before storing it in the instance data structure.

   If the data is already of type CFURL, we can simply retain its reference and store it in the instance data.

4. If for some reason no configuration data was passed in the initialization event, set the instance data URL to some default value.

5. Call HIToolbarItemSetLabel to set the displayed text for the toolbar item.

6. If your custom toolbar item does not create an HIView to display, in most cases you should assign it an icon. This example simply uses the Icon Services function GetIconRef to obtain a generic URL icon, and assigns it to the toolbar item by calling HIToolbarItemSetIconRef.

7. After assigning the icon reference to the toolbar item, you can release your reference to it.

8. Call HIToolbarItemSetHelpText to assign the help tag text for your toolbar item.

In addition to the kEventClassHIObject events, your custom URL toolbar item should also handle two additional events:

• kEventToolbarItemGetPersistentData: You receive this event when the toolbar wants to store configuration information in the user’s preferences. You should return a pointer (which must be of type CFTypeRef) to any data you want to store in the kEventParamConfigData parameter.

  Note that this data is saved in XML format; any data you store in this event must be CFPropertyList-compatible. Currently this means the data must be one of the following types: CFString, CFData, CFNumber, CFBoolean, CFDate, CFArray, and CFDictionary.

  Note that for CFType references, you should pass a copy of the data, as the system will dispose of the reference it receives to the configuration data.

• kEventToolbarItemPerformAction: You receive this event when the user clicks on your toolbar item. Your handler can then take any appropriate action. For example, if the user clicks on your custom URL toolbar item, you can call the Launch Services function LSOpenCFURLRef to open the URL using the user’s default browser.

  Note that if your toolbar item handles the kEventToolbarItemPerformAction event, you should set the command ID for the toolbar item to kHIToolbarCommandPressAction (value: 'tbpr'). Doing so ensures that HIToolbar can send the perform action event when your toolbar item is selected from the overflow menu. This command ID is available in Mac OS X v.10.2.3 and later.