Carbon Event Manager Programming Guide: Creating Your Own Events

< Previous PageNext Page >

Hide TOC

Creating Your Own Events

In addition to processing and dispatching events, the Carbon Event Manager also lets you create your own events. You may want to create your own custom events, or you might want to reproduce standard events.

You create an event using the CreateEvent function:

OSStatus CreateEvent( CFAllocatorRef inAllocator<null>,

                    UInt32 inClassID, UInt32 kind,EventTime when,

                    EventAttributes flags, EventRef* outEvent);

The inAllocator parameter refers to the allocator you want to use to allocate memory for the event. You can pass NULL to specify the default allocator.
The inClassID and kind parameters indicate the event class and kind. If you are creating custom events, you need to define new values that don’t conflict with existing event classes and kinds. And, of course, you must specify this class and kind when your register a handler to process this type of event.
The when parameter indicates when the event occurred. You can pass 0 to specify the current event time (as returned by the GetCurrentEventTime function). This value may or may not be useful for custom events.
The flags parameter indicates any event attributes you may want to set. The current choices are kEventAttributeNone and kEventAttributeUserEvent.
On return, outEvent contains the newly-created event reference.

If your event requires additional information, you can add data by calling SetEventParameter. If you are creating custom events, you need to define constants for your parameter names and types if they don’t already exist. For example, if you define a parameter for a screen location, you may want to define a new parameter name, but you can probably still use typeQDPoint for the parameter type.

Once you create an event, you need to send it to a handler. There are two basic methods for doing so:

You can post the event to a queue by calling the PostEventToQueue function. You need to obtain the queue reference for the queue you want to post to by calling either GetCurrentEventQueue (which returns the current thread’s queue) or GetMainEventQueue (which returns the queue for the main application thread). The event you post will not be processed until it is pulled from the queue and dispatched to the appropriate event target.
Note that in Mac OS X, you can indicate in the event reference where a posted event should be dispatched by specifying a kEventParamPostTarget event parameter.
You can send it directly to the desired event target by calling SendEventToEventTarget. If this is a custom event, the target you choose should be the one to which you attached your custom event handler. Dispatching the event yourself will ensure that your handler is called immediately.

Note that if you send an event to the standard toolbox dispatcher and it does not recognize it (that is, it’s a custom event), then it will dispatch the event to the application event target (unless you specified an event target in your custom event using the kEventParamPostTarget parameter).

If you want to create and process command events, the Carbon Event Manager provides the function ProcessHICommand:

OSStatus ProcessHICommand (const HICommand* inCommand);

When you pass an Command ID to ProcessHICommand, it builds a kEventCommandProcess event containing the ID and then dispatches the event to either

a menu, if the command is defined in a menu, or
the current user focus

< Previous PageNext Page >

Hide TOC

Last updated: 2005-07-07

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice