BotoX
/
hl2_src-leak-2017
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
hl2_src-leak-2017/src/common/quicktime_win32/CarbonEventsCore.h

2175 lines
70 KiB
C
Raw Permalink Blame History

/*
File: CarbonEventsCore.h
Contains: Carbon Event Manager
Version: QuickTime 7.3
Copyright: (c) 2007 (c) 1999-2001 by Apple Computer, Inc., all rights reserved.
Bugs?: For bug reports, consult the following page on
the World Wide Web:
http://developer.apple.com/bugreporter/
*/
#ifndef __CARBONEVENTSCORE__
#define __CARBONEVENTSCORE__
#ifndef __CFSTRING__
#include <CFString.h>
#endif
#ifndef __AEREGISTRY__
#include <AERegistry.h>
#endif
#ifndef __AEDATAMODEL__
#include <AEDataModel.h>
#endif
#if PRAGMA_ONCE
#pragma once
#endif
#ifdef __cplusplus
extern "C" {
#endif
#if PRAGMA_IMPORT
#pragma import on
#endif
#if PRAGMA_STRUCT_ALIGN
#pragma options align=mac68k
#elif PRAGMA_STRUCT_PACKPUSH
#pragma pack(push, 2)
#elif PRAGMA_STRUCT_PACK
#pragma pack(2)
#endif
/*======================================================================================*/
/* The core data structure of the Carbon Event system */
/*======================================================================================*/
typedef struct OpaqueEventRef* EventRef;
/*======================================================================================*/
/* EVENT COMMON */
/*======================================================================================*/
/*
* Discussion:
* The following are all errors which can be returned from the
* routines contained in this file.
*/
enum {
/*
* This is returned from PostEventToQueue if the event in question is
* already in the queue you are posting it to (or any other queue).
*/
eventAlreadyPostedErr = -9860,
/*
* You are attemtping to modify a target that is currently in use,
* such as when dispatching.
*/
eventTargetBusyErr = -9861,
/*
* This is obsolete and will be removed.
*/
eventClassInvalidErr = -9862,
/*
* This is obsolete and will be removed.
*/
eventClassIncorrectErr = -9864,
/*
* Returned from InstallEventHandler if the handler proc you pass is
* already installed for a given event type you are trying to
* register.
*/
eventHandlerAlreadyInstalledErr = -9866,
/*
* A generic error.
*/
eventInternalErr = -9868,
/*
* This is obsolete and will be removed.
*/
eventKindIncorrectErr = -9869,
/*
* The piece of data you are requesting from an event is not present.
*/
eventParameterNotFoundErr = -9870,
/*
* This is what you should return from an event handler when your
* handler has received an event it doesn't currently want to (or
* isn't able to) handle. If you handle an event, you should return
* noErr from your event handler. Any return value other than
* eventNotHandledErr will cause event handling to stop; the event
* will not be sent to any other event handler, and the return value
* will be provided to the original caller of SendEventToTarget.
*/
eventNotHandledErr = -9874,
/*
* The event loop has timed out. This can be returned from calls to
* ReceiveNextEvent or RunCurrentEventLoop.
*/
eventLoopTimedOutErr = -9875,
/*
* The event loop was quit, probably by a call to QuitEventLoop. This
* can be returned from ReceiveNextEvent or RunCurrentEventLoop.
*/
eventLoopQuitErr = -9876,
/*
* Returned from RemoveEventFromQueue when trying to remove an event
* that's not in any queue.
*/
eventNotInQueueErr = -9877,
eventHotKeyExistsErr = -9878,
eventHotKeyInvalidErr = -9879
};
/*======================================================================================*/
/* EVENT CORE */
/*======================================================================================*/
/*--------------------------------------------------------------------------------------*/
/* o Event Flags, options */
/*--------------------------------------------------------------------------------------*/
/*
* EventPriority
*
* Discussion:
* These values define the relative priority of an event, and are
* used when posting events with PostEventToQueue. In general events
* are pulled from the queue in order of first posted to last
* posted. These priorities are a way to alter that when posting
* events. You can post a standard priority event and then a high
* priority event and the high priority event will be pulled from
* the queue first.
*/
typedef SInt16 EventPriority;
enum {
/*
* Lowest priority. Currently only window update events are posted at
* this priority.
*/
kEventPriorityLow = 0,
/*
* Normal priority of events. Most events are standard priority.
*/
kEventPriorityStandard = 1,
/*
* Highest priority.
*/
kEventPriorityHigh = 2
};
enum {
kEventLeaveInQueue = false,
kEventRemoveFromQueue = true
};
/*--------------------------------------------------------------------------------------*/
/* o Event Times */
/* */
/* EventTime is in seconds since boot. Use the constants to make life easy. */
/*--------------------------------------------------------------------------------------*/
typedef double EventTime;
typedef EventTime EventTimeout;
typedef EventTime EventTimerInterval;
#define kEventDurationSecond ((EventTime)1.0)
#define kEventDurationMillisecond ((EventTime)(kEventDurationSecond/1000))
#define kEventDurationMicrosecond ((EventTime)(kEventDurationSecond/1000000))
#define kEventDurationNanosecond ((EventTime)(kEventDurationSecond/1000000000))
#define kEventDurationMinute ((EventTime)(kEventDurationSecond*60))
#define kEventDurationHour ((EventTime)(kEventDurationMinute*60))
#define kEventDurationDay ((EventTime)(kEventDurationHour*24))
#define kEventDurationNoWait ((EventTime)0.0)
#define kEventDurationForever ((EventTime)(-1.0))
/* Helpful doodads to convert to and from ticks and event times*/
#ifdef __cplusplus
inline EventTime TicksToEventTime( UInt32 t ) { return ( (t) / 60.0 ); }
inline UInt32 EventTimeToTicks( EventTime t ) { return (UInt32)( ((t) * 60) + 0.5 ); }
#else
#define TicksToEventTime( t ) ((EventTime)( (t) / 60.0 ))
#define EventTimeToTicks( t ) ((UInt32)( ((t) * 60) + 0.5 ))
#endif /* defined(__cplusplus) */
/*--------------------------------------------------------------------------------------*/
/* EventTypeSpec structure */
/* */
/* This structure is used in many routines to pass a list of event types to a function. */
/* You typically would declare a const array of these types to pass in. */
/*--------------------------------------------------------------------------------------*/
/*
* EventTypeSpec
*
* Discussion:
* This structure is used to specify an event. Typically, a static
* array of EventTypeSpecs are passed into functions such as
* InstallEventHandler, as well as routines such as
* FlushEventsMatchingListFromQueue.
*/
struct EventTypeSpec {
UInt32 eventClass;
UInt32 eventKind;
};
typedef struct EventTypeSpec EventTypeSpec;
/*A helpful macro for dealing with EventTypeSpecs */
#define GetEventTypeCount( t ) (sizeof( (t) ) / sizeof( EventTypeSpec ))
typedef OSType EventParamName;
typedef OSType EventParamType;
/*--------------------------------------------------------------------------------------*/
/* o EventLoop */
/*--------------------------------------------------------------------------------------*/
/*
* EventLoopRef
*
* Discussion:
* An EventLoopRef represents an 'event loop', which is the
* conceptual entity that you 'run' to fetch events from hardware
* and other sources and also fires timers that might be installed
* with InstallEventLoopTimer. The term 'run' is a bit of a
* misnomer, as the event loop's goal is to stay as blocked as
* possible to minimize CPU usage for the current application. The
* event loop is run implicitly thru APIs like ReceiveNextEvent,
* RunApplicationEventLoop, or even WaitNextEvent. It can also be
* run explicitly thru a call to RunCurrentEventLoop. Each
* preemptive thread can have an event loop. Cooperative threads
* share the main thread's event loop.
*/
typedef struct OpaqueEventLoopRef* EventLoopRef;
/*
* GetCurrentEventLoop()
*
* Discussion:
* Returns the current event loop for the current thread. If the
* current thread is a cooperative thread, the main event loop is
* returned.
*
* Result:
* An event loop reference.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( EventLoopRef )
GetCurrentEventLoop(void);
/*
* GetMainEventLoop()
*
* Discussion:
* Returns the event loop object for the main application thread.
*
* Result:
* An event loop reference.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( EventLoopRef )
GetMainEventLoop(void);
/*
* RunCurrentEventLoop()
*
* Discussion:
* This routine 'runs' the event loop, returning only if aborted or
* the timeout specified is reached. The event loop is mostly
* blocked while in this function, occasionally waking up to fire
* timers or pick up events. The typical use of this function is to
* cause the current thread to wait for some operation to complete,
* most likely on another thread of execution.
*
* Parameters:
*
* inTimeout:
* The time to wait until returning (can be kEventDurationForever).
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
RunCurrentEventLoop(EventTimeout inTimeout);
/*
* QuitEventLoop()
*
* Discussion:
* Causes a specific event loop to terminate. Usage of this is
* similar to WakeUpProcess, in that it causes the eventloop
* specified to return immediately (as opposed to timing out).
* Typically this call is used in conjunction with
* RunCurrentEventLoop.
*
* Parameters:
*
* inEventLoop:
* The event loop to terminate.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
QuitEventLoop(EventLoopRef inEventLoop);
/*
* GetCFRunLoopFromEventLoop()
*
* Discussion:
* Returns the corresponding CFRunLoopRef for the given EventLoop.
* This is not necessarily a one-to-one mapping, hence the need for
* this function. In Carbon, all cooperative threads use the same
* run loop under the covers, so using CFRunLoopGetCurrent might
* yield the wrong result. In general, you would only need to use
* this function if you wished to add your own sources to the run
* loop. If you don't know what I'm talking about, then you probably
* don't need to use this.
*
* Parameters:
*
* inEventLoop:
* The event loop to get the CFRunLoop for.
*
* Result:
* The CFRunLoopRef for inEventLoop.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.1 and later
* Mac OS X: in version 10.1 and later
*/
EXTERN_API_C( CFTypeRef )
GetCFRunLoopFromEventLoop(EventLoopRef inEventLoop);
/*--------------------------------------------------------------------------------------*/
/* o Low-level event fetching */
/*--------------------------------------------------------------------------------------*/
/*
* ReceiveNextEvent()
*
* Discussion:
* This routine tries to fetch the next event of a specified type.
* If no events in the event queue match, this routine will run the
* current event loop until an event that matches arrives, or the
* timeout expires. Except for timers firing, your application is
* blocked waiting for events to arrive when inside this function.
*
* Parameters:
*
* inNumTypes:
* The number of event types we are waiting for (0 if any event
* should cause this routine to return).
*
* inList:
* The list of event types we are waiting for (pass NULL if any
* event should cause this routine to return).
*
* inTimeout:
* The time to wait (passing kEventDurationForever is preferred).
*
* inPullEvent:
* Pass true for this parameter to actually remove the next
* matching event from the queue.
*
* outEvent:
* The next event that matches the list passed in. If inPullEvent
* is true, the event is owned by you, and you will need to
* release it when done.
*
* Result:
* A result indicating whether an event was received, the timeout
* expired, or the current event loop was quit.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
ReceiveNextEvent(
UInt32 inNumTypes,
const EventTypeSpec * inList,
EventTimeout inTimeout,
Boolean inPullEvent,
EventRef * outEvent);
/*--------------------------------------------------------------------------------------*/
/* o Core event lifetime APIs */
/*--------------------------------------------------------------------------------------*/
typedef UInt32 EventAttributes;
enum {
kEventAttributeNone = 0,
kEventAttributeUserEvent = (1 << 0)
};
/*
* [Mac]CreateEvent()
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
#if TARGET_OS_MAC
#define MacCreateEvent CreateEvent
#endif
EXTERN_API( OSStatus )
MacCreateEvent(
CFAllocatorRef inAllocator, /* can be NULL */
UInt32 inClassID,
UInt32 kind,
EventTime when,
EventAttributes flags,
EventRef * outEvent);
/*
* CopyEvent()
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( EventRef )
CopyEvent(EventRef inOther);
/*
* RetainEvent()
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( EventRef )
RetainEvent(EventRef inEvent);
/*
* GetEventRetainCount()
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( UInt32 )
GetEventRetainCount(EventRef inEvent);
/*
* ReleaseEvent()
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( void )
ReleaseEvent(EventRef inEvent);
/*
* SetEventParameter()
*
* Discussion:
* Sets a piece of data for the given event.
*
* Parameters:
*
* inEvent:
* The event to set the data for.
*
* inName:
* The symbolic name of the parameter.
*
* inType:
* The symbolic type of the parameter.
*
* inSize:
* The size of the parameter data.
*
* inDataPtr:
* The pointer to the parameter data.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
SetEventParameter(
EventRef inEvent,
EventParamName inName,
EventParamType inType,
UInt32 inSize,
const void * inDataPtr);
/*
* GetEventParameter()
*
* Discussion:
* Gets a piece of data from the given event, if it exists.
*
* Parameters:
*
* inEvent:
* The event to get the parameter from.
*
* inName:
* The symbolic name of the parameter.
*
* inDesiredType:
* The desired type of the parameter. At present we do not support
* coercion, so this parameter must be the actual type of data
* stored in the event, or an error will be returned.
*
* outActualType:
* The actual type of the parameter, can be NULL if you are not
* interested in receiving this information.
*
* inBufferSize:
* The size of the output buffer specified by ioBuffer.
*
* outActualSize:
* The actual size of the data, or NULL if you don't want this
* information.
*
* outData:
* The pointer to the buffer which will receive the parameter data.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
GetEventParameter(
EventRef inEvent,
EventParamName inName,
EventParamType inDesiredType,
EventParamType * outActualType, /* can be NULL */
UInt32 inBufferSize,
UInt32 * outActualSize, /* can be NULL */
void * outData);
/*--------------------------------------------------------------------------------------*/
/* o Getters for 'base-class' event info */
/*--------------------------------------------------------------------------------------*/
/*
* GetEventClass()
*
* Discussion:
* Returns the class of the given event, such as mouse, keyboard,
* etc.
*
* Parameters:
*
* inEvent:
* The event in question.
*
* Result:
* The class ID of the event.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( UInt32 )
GetEventClass(EventRef inEvent);
/*
* GetEventKind()
*
* Discussion:
* Returns the kind of the given event (mousedown, etc.). Event
* kinds overlap between event classes, e.g. kEventMouseDown and
* kEventAppActivated have the same value (1). The combination of
* class and kind is what determines an event signature.
*
* Parameters:
*
* inEvent:
* The event in question.
*
* Result:
* The kind of the event.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( UInt32 )
GetEventKind(EventRef inEvent);
/*
* GetEventTime()
*
* Discussion:
* Returns the time the event specified occurred, specified in
* EventTime, which is a floating point number representing seconds
* since the last system startup.
*
* Parameters:
*
* inEvent:
* The event in question.
*
* Result:
* The time the event occurred.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( EventTime )
GetEventTime(EventRef inEvent);
/*--------------------------------------------------------------------------------------*/
/* o Setters for 'base-class' event info */
/*--------------------------------------------------------------------------------------*/
/*
* SetEventTime()
*
* Discussion:
* This routine allows you to set the time of a given event, if you
* so desire. In general, you would never use this routine, except
* for those special cases where you reuse an event from time to
* time instead of creating a new event each time.
*
* Parameters:
*
* inEvent:
* The event in question.
*
* inTime:
* The new time.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
SetEventTime(
EventRef inEvent,
EventTime inTime);
/*--------------------------------------------------------------------------------------*/
/* o Event Queue routines (posting, finding, flushing) */
/*--------------------------------------------------------------------------------------*/
typedef struct OpaqueEventQueueRef* EventQueueRef;
/*
* GetCurrentEventQueue()
*
* Discussion:
* Returns the current event queue for the current thread. If the
* current thread is a cooperative thread, the main event queue is
* returned.
*
* Result:
* An event queue reference.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( EventQueueRef )
GetCurrentEventQueue(void);
/*
* GetMainEventQueue()
*
* Discussion:
* Returns the event queue object for the main application thread.
*
* Result:
* An event queue reference.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( EventQueueRef )
GetMainEventQueue(void);
/*
* EventComparatorProcPtr
*
* Discussion:
* Type of a callback function used by queue searches.
*
* Parameters:
*
* inEvent:
* The event to compare.
*
* inCompareData:
* The data used to compare the event.
*
* Result:
* A boolean value indicating whether the event matches (true) or
* not (false).
*/
typedef CALLBACK_API( Boolean , EventComparatorProcPtr )(EventRef inEvent, void *inCompareData);
typedef STACK_UPP_TYPE(EventComparatorProcPtr) EventComparatorUPP;
/*
* NewEventComparatorUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( EventComparatorUPP )
NewEventComparatorUPP(EventComparatorProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
enum { uppEventComparatorProcInfo = 0x000003D0 }; /* pascal 1_byte Func(4_bytes, 4_bytes) */
#ifdef __cplusplus
inline DEFINE_API_C(EventComparatorUPP) NewEventComparatorUPP(EventComparatorProcPtr userRoutine) { return (EventComparatorUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppEventComparatorProcInfo, GetCurrentArchitecture()); }
#else
#define NewEventComparatorUPP(userRoutine) (EventComparatorUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppEventComparatorProcInfo, GetCurrentArchitecture())
#endif
#endif
/*
* DisposeEventComparatorUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( void )
DisposeEventComparatorUPP(EventComparatorUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(void) DisposeEventComparatorUPP(EventComparatorUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); }
#else
#define DisposeEventComparatorUPP(userUPP) DisposeRoutineDescriptor(userUPP)
#endif
#endif
/*
* InvokeEventComparatorUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( Boolean )
InvokeEventComparatorUPP(
EventRef inEvent,
void * inCompareData,
EventComparatorUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(Boolean) InvokeEventComparatorUPP(EventRef inEvent, void * inCompareData, EventComparatorUPP userUPP) { return (Boolean)CALL_TWO_PARAMETER_UPP(userUPP, uppEventComparatorProcInfo, inEvent, inCompareData); }
#else
#define InvokeEventComparatorUPP(inEvent, inCompareData, userUPP) (Boolean)CALL_TWO_PARAMETER_UPP((userUPP), uppEventComparatorProcInfo, (inEvent), (inCompareData))
#endif
#endif
#if CALL_NOT_IN_CARBON || OLDROUTINENAMES
/* support for pre-Carbon UPP routines: New...Proc and Call...Proc */
#define NewEventComparatorProc(userRoutine) NewEventComparatorUPP(userRoutine)
#define CallEventComparatorProc(userRoutine, inEvent, inCompareData) InvokeEventComparatorUPP(inEvent, inCompareData, userRoutine)
#endif /* CALL_NOT_IN_CARBON */
/*
* PostEventToQueue()
*
* Discussion:
* Posts an event to the queue specified. This automatically wakes
* up the event loop of the thread the queue belongs to. After
* posting the event, you should release the event. The event queue
* retains it.
*
* Parameters:
*
* inQueue:
* The event queue to post the event onto.
*
* inEvent:
* The event to post.
*
* inPriority:
* The priority of the event.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
PostEventToQueue(
EventQueueRef inQueue,
EventRef inEvent,
EventPriority inPriority);
/*
* FlushEventsMatchingListFromQueue()
*
* Discussion:
* Flushes events matching a specified list of classes and kinds
* from an event queue.
*
* Parameters:
*
* inQueue:
* The event queue to flush events from.
*
* inNumTypes:
* The number of event kinds to flush.
*
* inList:
* The list of event classes and kinds to flush from the queue.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
FlushEventsMatchingListFromQueue(
EventQueueRef inQueue,
UInt32 inNumTypes,
const EventTypeSpec * inList);
/*
* FlushSpecificEventsFromQueue()
*
* Discussion:
* Flushes events that match a comparator function.
*
* Parameters:
*
* inQueue:
* The event queue to flush events from.
*
* inComparator:
* The comparison function to invoke for each event in the queue.
*
* inCompareData:
* The data you wish to pass to your comparison function.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
FlushSpecificEventsFromQueue(
EventQueueRef inQueue,
EventComparatorUPP inComparator,
void * inCompareData);
/*
* FlushEventQueue()
*
* Discussion:
* Flushes all events from an event queue.
*
* Parameters:
*
* inQueue:
* The event queue to flush.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
FlushEventQueue(EventQueueRef inQueue);
/*
* FindSpecificEventInQueue()
*
* Discussion:
* Returns the first event that matches a comparator function, or
* NULL if no events match.
*
* Parameters:
*
* inQueue:
* The event queue to search.
*
* inComparator:
* The comparison function to invoke for each event in the queue.
*
* inCompareData:
* The data you wish to pass to your comparison function.
*
* Result:
* An event reference. The event is still in the queue when
* FindSpecificEventInQueue returns; you can remove it from the
* queue with RemoveEventFromQueue. The returned event does not need
* to be released by the caller.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( EventRef )
FindSpecificEventInQueue(
EventQueueRef inQueue,
EventComparatorUPP inComparator,
void * inCompareData);
/*
* GetNumEventsInQueue()
*
* Discussion:
* Returns the number of events in an event queue.
*
* Parameters:
*
* inQueue:
* The event queue to query.
*
* Result:
* The number of items in the queue.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( UInt32 )
GetNumEventsInQueue(EventQueueRef inQueue);
/*
* RemoveEventFromQueue()
*
* Discussion:
* Removes the given event from the queue which it was posted. When
* you call this function, the event ownership is transferred to
* you, the caller, at no charge. You must release the event when
* you are through with it.
*
* Parameters:
*
* inQueue:
* The queue to remove the event from.
*
* inEvent:
* The event to remove.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
RemoveEventFromQueue(
EventQueueRef inQueue,
EventRef inEvent);
/*
* IsEventInQueue()
*
* Discussion:
* Returns true if the specified event is posted to a queue.
*
* Parameters:
*
* inQueue:
* The queue to check.
*
* inEvent:
* The event in question.
*
* Result:
* A boolean value.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( Boolean )
IsEventInQueue(
EventQueueRef inQueue,
EventRef inEvent);
/*--------------------------------------------------------------------------------------*/
/* Queue-synchronized event state */
/*--------------------------------------------------------------------------------------*/
/*
* GetCurrentEvent()
*
* Summary:
* Returns the user input event currently being handled.
*
* Discussion:
* When an event with kEventAttributeUserEvent is dispatched by the
* event dispatcher target, it is recorded internally by the Event
* Manager. At any time during the handling of that event,
* GetCurrentEvent may be used to retrieve the original EventRef.
*
* Result:
* The user input (mouse or keyboard) event currently being handled.
* May be NULL if no event is currently being handled, or if the
* current event was not a user input event. The returned event is
* not retained, and its lifetime should be considered to be no
* longer than the current function; if you need to keep the event
* alive past that time, you should retain it.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( EventRef )
GetCurrentEvent(void);
/*
* GetCurrentEventButtonState()
*
* Summary:
* Returns the current queue-synchronized mouse button state on the
* primary input device.
*
* Discussion:
* At any point in the handling of user input, there are two
* different mouse button states: the queue-synchronized state and
* the hardware state. The hardware state reflects the actual
* current state of the mouse attached to the user's machine. The
* queue-synchronized state reflects the state according to the
* events that have been processed at that point by the application.
* These two states may be different if there are unprocessed events
* in the event queue, or if events are being artificially
* introduced into the event queue from an outside source.
* GetCurrentEventButtonState returns the queue-synchronized button
* state. It is generally better to use this API than to use the
* Button function or the GetCurrentButtonState function (which
* return the hardware state). This gives a more consistent user
* experience when the user input queue is being remoted controlled
* or manipulated via non-hardware event sources such as speech or
* AppleEvents; using GetCurrentEventButtonState is also much faster
* than using Button or GetCurrentButtonState.
*
* Note that GetCurrentEventButtonState only returns a valid button
* state if your application is the active application. If your
* application is not active, then user input events are not flowing
* through the event dispatcher and the queue-synchronized state is
* not updated.
*
* Result:
* The queue-synchronized state of the mouse buttons. Bit zero
* indicates the state of the primary button, bit one the state of
* the secondary button, and so on.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( UInt32 )
GetCurrentEventButtonState(void);
/*
* GetCurrentEventKeyModifiers()
*
* Summary:
* Returns the current queue-synchronized keyboard modifier state.
*
* Discussion:
* At any point in the handling of user input, there are two
* different keyboard modifier states: the queue-synchronized state
* and the hardware state. The hardware state reflects the actual
* current state of the keyboard attached to the user's machine. The
* queue-synchronized state reflects the state according to the
* events that have been processed at that point by the application.
* These two states may be different if there are unprocessed events
* in the event queue, or if events are being artificially
* introduced into the event queue from an outside source.
* GetCurrentEventKeyModifiers returns the queue-synchronized
* modifier state. It is generally better to use this API than to
* use the GetCurrentKeyModifiers API (which returns the hardware
* state). This gives a more consistent user experience when the
* user input queue is being remoted controlled or manipulated via
* non-hardware event sources such as speech or AppleEvents; using
* GetCurrentEventKeyModifiers is also much faster than using
* EventAvail(0, &eventRecord) or GetCurrentKeyModifiers.
*
* Note that GetCurrentEventKeyModifiers only returns a valid
* modifier state if your application is the active application. If
* your application is not active, then user input events are not
* flowing through the event dispatcher and the queue-synchronized
* state is not updated.
*
* Result:
* The queue-synchronized state of the keyboard modifiers. The
* format of the return value is the same as the modifiers field of
* an EventRecord (but only includes keyboard modifiers and not the
* other modifier flags included in an EventRecord).
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( UInt32 )
GetCurrentEventKeyModifiers(void);
/*--------------------------------------------------------------------------------------*/
/* Multiple-button support */
/*--------------------------------------------------------------------------------------*/
/*
* GetCurrentButtonState()
*
* Summary:
* Returns the current hardware mouse button state on the primary
* input device.
*
* Discussion:
* In most cases, you should not use GetCurrentButtonState, but
* should use the GetCurrentEventButtonState function instead.
* GetCurrentEventButtonState is much faster than
* GetCurrentButtonState because it returns the locally cached
* button state; GetCurrentButtonState must get the mouse button
* state from the window server, which is slower. Using
* GetCurrentButtonState also can prevent your application from
* being operated by remote posting of events, since the hardware
* input device is not actually changing state in that case. Most
* commonly, you might need to use GetCurrentButtonState when your
* application is not the active application (as determined by the
* Process Manager function GetFrontProcess). In that case, the
* cached button state returned by GetCurrentEventButtonState is not
* valid because mouse button events are not flowing to your
* application, and you must use GetCurrentButtonState to determine
* the current hardware state.
*
* Result:
* The state of the mouse buttons on the mouse hardware. Bit zero
* indicates the state of the primary button, bit one the state of
* the secondary button, and so on.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( UInt32 )
GetCurrentButtonState(void);
/*--------------------------------------------------------------------------------------*/
/* o Helpful utilities */
/*--------------------------------------------------------------------------------------*/
/*
* GetCurrentEventTime()
*
* Discussion:
* Returns the current time since last system startup in seconds.
*
* Result:
* EventTime.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( EventTime )
GetCurrentEventTime(void);
/*--------------------------------------------------------------------------------------*/
/* o Timers */
/*--------------------------------------------------------------------------------------*/
/*
* EventLoopTimerRef
*
* Discussion:
* An EventLoopTimerRef represents what we term a 'timer'. A timer
* is a function that is called either once or at regular intervals.
* It executes at task level and should not be confused with Time
* Manager Tasks or any other interrupt-level callback. This means
* you can call Toolbox routines, allocate memory and draw. When a
* timer 'fires', it calls a callback that you specify when the
* timer is installed. Timers in general have two uses - as a
* timeout mechanism and as a periodic task. An everyday example of
* using a timer for a timeout might be a light that goes out if no
* motion is detected in a room for 5 minutes. For this, you might
* install a timer which will fire in 5 minutes. If motion is
* detected, you would reset the timer fire time and let the clock
* start over. If no motion is detected for the full 5 minutes, the
* timer will fire and you could power off the light. A periodic
* timer is one that fires at regular intervals (say every second or
* so). You might use such a timer to blink the insertion point in
* your editor, etc. One advantage of timers is that you can install
* the timer right from the code that wants the time. For example,
* the standard Toolbox Edit Text control can install a timer to
* blink the cursor when it's active, meaning that IdleControls is a
* no-op for that control and doesn't need to be called. When the
* control is inactive, it removes its timer and doesn't waste CPU
* time in that state. NOTE: Currently, if you do decide to draw
* when your timer is called, be sure to save and restore the
* current port so that calling your timer doesn't inadvertently
* change the port out from under someone.
*/
typedef struct __EventLoopTimer* EventLoopTimerRef;
/*
* EventLoopTimerProcPtr
*
* Discussion:
* Called when a timer fires.
*
* Parameters:
*
* inTimer:
* The timer that fired.
*
* inUserData:
* The data passed into InstallEventLoopTimer.
*/
typedef CALLBACK_API( void , EventLoopTimerProcPtr )(EventLoopTimerRef inTimer, void *inUserData);
/*
* Discussion:
* Event Loop Idle Timer Messages
*/
enum {
/*
* The user has gone idle (not touched an input device) for the
* duration specified in your idle timer. This is the first message
* you will receive. Start your engines!
*/
kEventLoopIdleTimerStarted = 1,
/*
* If you specified an interval on your idle timer, your idle timer
* proc will be called with this message, letting you know it is
* merely firing at the interval specified. If you did not specify an
* interval, this message is not sent.
*/
kEventLoopIdleTimerIdling = 2,
/*
* The user is back! Stop everything! This is your cue to stop any
* processing if you need to.
*/
kEventLoopIdleTimerStopped = 3
};
typedef UInt16 EventLoopIdleTimerMessage;
/*
* EventLoopIdleTimerProcPtr
*
* Discussion:
* Called when an idle timer fires.
*
* Parameters:
*
* inTimer:
* The timer that fired.
*
* inState:
* The current state of the timer.
*
* inUserData:
* The data passed into InstallEventLoopTimer.
*/
typedef CALLBACK_API( void , EventLoopIdleTimerProcPtr )(EventLoopTimerRef inTimer, EventLoopIdleTimerMessage inState, void *inUserData);
typedef STACK_UPP_TYPE(EventLoopTimerProcPtr) EventLoopTimerUPP;
typedef STACK_UPP_TYPE(EventLoopIdleTimerProcPtr) EventLoopIdleTimerUPP;
/*
* NewEventLoopTimerUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( EventLoopTimerUPP )
NewEventLoopTimerUPP(EventLoopTimerProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
enum { uppEventLoopTimerProcInfo = 0x000003C0 }; /* pascal no_return_value Func(4_bytes, 4_bytes) */
#ifdef __cplusplus
inline DEFINE_API_C(EventLoopTimerUPP) NewEventLoopTimerUPP(EventLoopTimerProcPtr userRoutine) { return (EventLoopTimerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppEventLoopTimerProcInfo, GetCurrentArchitecture()); }
#else
#define NewEventLoopTimerUPP(userRoutine) (EventLoopTimerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppEventLoopTimerProcInfo, GetCurrentArchitecture())
#endif
#endif
#if CALL_NOT_IN_CARBON
/*
* NewEventLoopIdleTimerUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: not available
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( EventLoopIdleTimerUPP )
NewEventLoopIdleTimerUPP(EventLoopIdleTimerProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
enum { uppEventLoopIdleTimerProcInfo = 0x00000EC0 }; /* pascal no_return_value Func(4_bytes, 2_bytes, 4_bytes) */
#ifdef __cplusplus
inline DEFINE_API_C(EventLoopIdleTimerUPP) NewEventLoopIdleTimerUPP(EventLoopIdleTimerProcPtr userRoutine) { return (EventLoopIdleTimerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppEventLoopIdleTimerProcInfo, GetCurrentArchitecture()); }
#else
#define NewEventLoopIdleTimerUPP(userRoutine) (EventLoopIdleTimerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppEventLoopIdleTimerProcInfo, GetCurrentArchitecture())
#endif
#endif
#endif /* CALL_NOT_IN_CARBON */
/*
* DisposeEventLoopTimerUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( void )
DisposeEventLoopTimerUPP(EventLoopTimerUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(void) DisposeEventLoopTimerUPP(EventLoopTimerUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); }
#else
#define DisposeEventLoopTimerUPP(userUPP) DisposeRoutineDescriptor(userUPP)
#endif
#endif
#if CALL_NOT_IN_CARBON
/*
* DisposeEventLoopIdleTimerUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: not available
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( void )
DisposeEventLoopIdleTimerUPP(EventLoopIdleTimerUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(void) DisposeEventLoopIdleTimerUPP(EventLoopIdleTimerUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); }
#else
#define DisposeEventLoopIdleTimerUPP(userUPP) DisposeRoutineDescriptor(userUPP)
#endif
#endif
#endif /* CALL_NOT_IN_CARBON */
/*
* InvokeEventLoopTimerUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( void )
InvokeEventLoopTimerUPP(
EventLoopTimerRef inTimer,
void * inUserData,
EventLoopTimerUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(void) InvokeEventLoopTimerUPP(EventLoopTimerRef inTimer, void * inUserData, EventLoopTimerUPP userUPP) { CALL_TWO_PARAMETER_UPP(userUPP, uppEventLoopTimerProcInfo, inTimer, inUserData); }
#else
#define InvokeEventLoopTimerUPP(inTimer, inUserData, userUPP) CALL_TWO_PARAMETER_UPP((userUPP), uppEventLoopTimerProcInfo, (inTimer), (inUserData))
#endif
#endif
#if CALL_NOT_IN_CARBON
/*
* InvokeEventLoopIdleTimerUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: not available
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( void )
InvokeEventLoopIdleTimerUPP(
EventLoopTimerRef inTimer,
EventLoopIdleTimerMessage inState,
void * inUserData,
EventLoopIdleTimerUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(void) InvokeEventLoopIdleTimerUPP(EventLoopTimerRef inTimer, EventLoopIdleTimerMessage inState, void * inUserData, EventLoopIdleTimerUPP userUPP) { CALL_THREE_PARAMETER_UPP(userUPP, uppEventLoopIdleTimerProcInfo, inTimer, inState, inUserData); }
#else
#define InvokeEventLoopIdleTimerUPP(inTimer, inState, inUserData, userUPP) CALL_THREE_PARAMETER_UPP((userUPP), uppEventLoopIdleTimerProcInfo, (inTimer), (inState), (inUserData))
#endif
#endif
#endif /* CALL_NOT_IN_CARBON */
#if CALL_NOT_IN_CARBON || OLDROUTINENAMES
/* support for pre-Carbon UPP routines: New...Proc and Call...Proc */
#define NewEventLoopTimerProc(userRoutine) NewEventLoopTimerUPP(userRoutine)
#define NewEventLoopIdleTimerProc(userRoutine) NewEventLoopIdleTimerUPP(userRoutine)
#define CallEventLoopTimerProc(userRoutine, inTimer, inUserData) InvokeEventLoopTimerUPP(inTimer, inUserData, userRoutine)
#define CallEventLoopIdleTimerProc(userRoutine, inTimer, inState, inUserData) InvokeEventLoopIdleTimerUPP(inTimer, inState, inUserData, userRoutine)
#endif /* CALL_NOT_IN_CARBON */
/*
* InstallEventLoopTimer()
*
* Discussion:
* Installs a timer onto the event loop specified. The timer can
* either fire once or repeatedly at a specified interval depending
* on the parameters passed to this function.
*
* Parameters:
*
* inEventLoop:
* The event loop to add the timer.
*
* inFireDelay:
* The delay before first firing this timer (can be 0, to request
* that the timer be fired as soon as control returns to your
* event loop). In Mac OS X and CarbonLib 1.5 and later, you may
* pass kEventDurationForever to stop the timer from firing at all
* until SetEventLoopTimerNextFireTime is used to start it; in
* earlier CarbonLibs, to achieve the same effect, just pass zero
* and then immediately call SetEventLoopTimerNextFireTime( timer,
* kEventDurationForever ) before returning control to your event
* loop.
*
* inInterval:
* The timer interval (pass 0 for a one-shot timer, which executes
* once but does not repeat). In Mac OS X and CarbonLib 1.5 and
* later, you may also pass kEventDurationForever to create a
* one-shot timer.
*
* inTimerProc:
* The routine to call when the timer fires.
*
* inTimerData:
* Data to pass to the timer proc when called.
*
* outTimer:
* A reference to the newly installed timer.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
InstallEventLoopTimer(
EventLoopRef inEventLoop,
EventTimerInterval inFireDelay,
EventTimerInterval inInterval,
EventLoopTimerUPP inTimerProc,
void * inTimerData,
EventLoopTimerRef * outTimer);
/*
* InstallEventLoopIdleTimer()
*
* Discussion:
* Installs a timer onto the event loop specified. Idle timers are
* only called when there is no user activity occuring in the
* application. This means that the user is not actively
* clicking/typing, and is also not in the middle of tracking a
* control, menu, or window. TrackMouseLocation actually disables
* all idle timers automatically for you.
*
* Parameters:
*
* inEventLoop:
* The event loop to add the timer.
*
* inDelay:
* The delay before firing this timer after a user input event has
* come in. For example, if you want to start your timer 2 seconds
* after the user stops typing, etc. you would pass 2.0 into this
* parameter. Each time the user types a key (or whatever), this
* timer is reset. If we are considered to be idle when an idle
* timer is installed, the first time it fires will be inDelay
* seconds from the time it is installed. So if you installed it
* in the middle of control tracking, say, it wouldn't fire until
* the user stopped tracking. But if you installed it at app
* startup and the user hasn't typed/clicked, it would fire in
* inDelay seconds.
*
* inInterval:
* The timer interval (pass 0 for a one-shot timer, which executes
* once but does not repeat). You may also pass
* kEventDurationForever to create a one-shot timer.
*
* inTimerProc:
* The routine to call when the timer fires.
*
* inTimerData:
* Data to pass to the timer proc when called.
*
* outTimer:
* A reference to the newly installed timer.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
InstallEventLoopIdleTimer(
EventLoopRef inEventLoop,
EventTimerInterval inDelay,
EventTimerInterval inInterval,
EventLoopIdleTimerUPP inTimerProc,
void * inTimerData,
EventLoopTimerRef * outTimer);
/* GOING AWAY!!!! DO NOT CALL THIS API!!!!! USE INSTALLEVENTLOOPIDLETIMER ABOVE!!!! */
/*
* InstallIdleTimer()
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
InstallIdleTimer(
EventLoopRef inEventLoop,
EventTimerInterval inDelay,
EventTimerInterval inInterval,
EventLoopTimerUPP inTimerProc,
void * inTimerData,
EventLoopTimerRef * outTimer);
/*
* RemoveEventLoopTimer()
*
* Discussion:
* Removes a timer that was previously installed by a call to
* InstallEventLoopTimer. You call this function when you are done
* using a timer.
*
* Parameters:
*
* inTimer:
* The timer to remove.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
RemoveEventLoopTimer(EventLoopTimerRef inTimer);
/*
* SetEventLoopTimerNextFireTime()
*
* Discussion:
* This routine is used to 'reset' a timer. It controls the next
* time the timer fires. This will override any interval you might
* have set. For example, if you have a timer that fires every
* second, and you call this function setting the next time to five
* seconds from now, the timer will sleep for five seconds, then
* fire. It will then resume its one-second interval after that. It
* is as if you removed the timer and reinstalled it with a new
* first-fire delay.
*
* Parameters:
*
* inTimer:
* The timer to adjust
*
* inNextFire:
* The interval from the current time to wait until firing the
* timer again. You may pass kEventDurationForever to stop the
* timer from firing at all.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
SetEventLoopTimerNextFireTime(
EventLoopTimerRef inTimer,
EventTimerInterval inNextFire);
/*======================================================================================*/
/* EVENT HANDLERS */
/*======================================================================================*/
typedef struct OpaqueEventHandlerRef* EventHandlerRef;
typedef struct OpaqueEventHandlerCallRef* EventHandlerCallRef;
/*--------------------------------------------------------------------------------------*/
/* o EventHandler specification */
/*--------------------------------------------------------------------------------------*/
/*
* EventHandlerProcPtr
*
* Discussion:
* Callback for receiving events sent to a target this callback is
* installed on.
*
* Parameters:
*
* inHandlerCallRef:
* A reference to the current handler call chain. This is sent to
* your handler so that you can call CallNextEventHandler if you
* need to.
*
* inEvent:
* The Event.
*
* inUserData:
* The app-specified data you passed in a call to
* InstallEventHandler.
*
* Result:
* An operating system result code. Returning noErr indicates you
* handled the event. Returning eventNotHandledErr indicates you did
* not handle the event and perhaps the toolbox should take other
* action.
*/
typedef CALLBACK_API( OSStatus , EventHandlerProcPtr )(EventHandlerCallRef inHandlerCallRef, EventRef inEvent, void *inUserData);
typedef STACK_UPP_TYPE(EventHandlerProcPtr) EventHandlerUPP;
/*
* NewEventHandlerUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( EventHandlerUPP )
NewEventHandlerUPP(EventHandlerProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
enum { uppEventHandlerProcInfo = 0x00000FF0 }; /* pascal 4_bytes Func(4_bytes, 4_bytes, 4_bytes) */
#ifdef __cplusplus
inline DEFINE_API_C(EventHandlerUPP) NewEventHandlerUPP(EventHandlerProcPtr userRoutine) { return (EventHandlerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppEventHandlerProcInfo, GetCurrentArchitecture()); }
#else
#define NewEventHandlerUPP(userRoutine) (EventHandlerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppEventHandlerProcInfo, GetCurrentArchitecture())
#endif
#endif
/*
* DisposeEventHandlerUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( void )
DisposeEventHandlerUPP(EventHandlerUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(void) DisposeEventHandlerUPP(EventHandlerUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); }
#else
#define DisposeEventHandlerUPP(userUPP) DisposeRoutineDescriptor(userUPP)
#endif
#endif
/*
* InvokeEventHandlerUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( OSStatus )
InvokeEventHandlerUPP(
EventHandlerCallRef inHandlerCallRef,
EventRef inEvent,
void * inUserData,
EventHandlerUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(OSStatus) InvokeEventHandlerUPP(EventHandlerCallRef inHandlerCallRef, EventRef inEvent, void * inUserData, EventHandlerUPP userUPP) { return (OSStatus)CALL_THREE_PARAMETER_UPP(userUPP, uppEventHandlerProcInfo, inHandlerCallRef, inEvent, inUserData); }
#else
#define InvokeEventHandlerUPP(inHandlerCallRef, inEvent, inUserData, userUPP) (OSStatus)CALL_THREE_PARAMETER_UPP((userUPP), uppEventHandlerProcInfo, (inHandlerCallRef), (inEvent), (inUserData))
#endif
#endif
#if CALL_NOT_IN_CARBON || OLDROUTINENAMES
/* support for pre-Carbon UPP routines: New...Proc and Call...Proc */
#define NewEventHandlerProc(userRoutine) NewEventHandlerUPP(userRoutine)
#define CallEventHandlerProc(userRoutine, inHandlerCallRef, inEvent, inUserData) InvokeEventHandlerUPP(inHandlerCallRef, inEvent, inUserData, userRoutine)
#endif /* CALL_NOT_IN_CARBON */
typedef struct OpaqueEventTargetRef* EventTargetRef;
/*--------------------------------------------------------------------------------------*/
/* o Installing Event Handlers */
/* */
/* Use these routines to install event handlers for a specific toolbox object. You may */
/* pass zero for inNumTypes and NULL for inList if you need to be in a situation where */
/* you know you will be receiving events, but not exactly which ones at the time you */
/* are installing the handler. Later, your application can call the Add/Remove routines */
/* listed below this section. */
/* */
/* You can only install a specific handler once. The combination of inHandler and */
/* inUserData is considered the 'signature' of a handler. Any attempt to install a new */
/* handler with the same proc and user data as an already-installed handler will result */
/* in eventHandlerAlreadyInstalledErr. Installing the same proc and user data on a */
/* different object is legal. */
/* */
/* Upon successful completion of this routine, you are returned an EventHandlerRef, */
/* which you can use in various other calls, and is passed to your event handler. You */
/* use it to extract information about the handler, such as the target (window, etc.) */
/* if you have the same handler installed for different objects and need to perform */
/* actions on the current target (say, call a window manager function). */
/*--------------------------------------------------------------------------------------*/
/*
* InstallEventHandler()
*
* Discussion:
* Installs an event handler on a specified target. Your handler
* proc will be called with the events you registered with when an
* event of the corresponding type and class are send to the target
* you are installing your handler on.
*
* Parameters:
*
* inTarget:
* The target to register your handler with.
*
* inHandler:
* A pointer to your handler function.
*
* inNumTypes:
* The number of events you are registering for.
*
* inList:
* A pointer to an array of EventTypeSpec entries representing the
* events you are interested in.
*
* inUserData:
* The value passed in this parameter is passed on to your event
* handler proc when it is called.
*
* outRef:
* Receives an EventHandlerRef, which you can use later to remove
* the handler. You can pass null if you don't want the reference
* - when the target is disposed, the handler will be disposed as
* well.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
InstallEventHandler(
EventTargetRef inTarget,
EventHandlerUPP inHandler,
UInt32 inNumTypes,
const EventTypeSpec * inList,
void * inUserData,
EventHandlerRef * outRef); /* can be NULL */
/*
* InstallStandardEventHandler()
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
InstallStandardEventHandler(EventTargetRef inTarget);
/*
* RemoveEventHandler()
*
* Discussion:
* Removes an event handler from the target it was bound to.
*
* Parameters:
*
* inHandlerRef:
* The handler ref to remove (returned in a call to
* InstallEventHandler). After you call this function, the handler
* ref is considered to be invalid and can no longer be used.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
RemoveEventHandler(EventHandlerRef inHandlerRef);
/*--------------------------------------------------------------------------------------*/
/* o Adjusting set of event types after a handler is created */
/* */
/* After installing a handler with the routine above, you can adjust the event type */
/* list telling the toolbox what events to send to that handler by calling the two */
/* routines below. If you add an event type twice for the same handler, your handler */
/* will only be called once, but it will take two RemoveEventType calls to stop your */
/* handler from being called with that event type. In other words, the install count */
/* for each event type is maintained by the toolbox. This might allow you, for example */
/* to have subclasses of a window object register for types without caring if the base */
/* class has already registered for that type. When the subclass removes its types, it */
/* can successfully do so without affecting the base class's reception of its event */
/* types, yielding eternal bliss. */
/*--------------------------------------------------------------------------------------*/
/*
* AddEventTypesToHandler()
*
* Discussion:
* Adds additional events to an event handler that has already been
* installed.
*
* Parameters:
*
* inHandlerRef:
* The event handler to add the additional events to.
*
* inNumTypes:
* The number of events to add.
*
* inList:
* A pointer to an array of EventTypeSpec entries.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
AddEventTypesToHandler(
EventHandlerRef inHandlerRef,
UInt32 inNumTypes,
const EventTypeSpec * inList);
/*
* RemoveEventTypesFromHandler()
*
* Discussion:
* Removes events from an event handler that has already been
* installed.
*
* Parameters:
*
* inHandlerRef:
* The event handler to remove the events from.
*
* inNumTypes:
* The number of events to remove.
*
* inList:
* A pointer to an array of EventTypeSpec entries.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
RemoveEventTypesFromHandler(
EventHandlerRef inHandlerRef,
UInt32 inNumTypes,
const EventTypeSpec * inList);
/*--------------------------------------------------------------------------------------*/
/* o Explicit Propogation */
/* */
/* CallNextEventHandler can be used to call thru to all handlers below the current */
/* handler being called. You pass the EventHandlerCallRef passed to your EventHandler */
/* into this call so that we know how to properly forward the event. The result of */
/* this function should normally be the result of your own handler that you called */
/* this API from. The typical use of this routine would be to allow the toolbox to do */
/* its standard processing and then follow up with some type of embellishment. */
/*--------------------------------------------------------------------------------------*/
/*
* CallNextEventHandler()
*
* Discussion:
* Calls thru to the event handlers below you in the event handler
* stack of the target to which your handler is bound. You might use
* this to call thru to the default toolbox handling in order to
* post-process the event. You can only call this routine from
* within an event handler.
*
* Parameters:
*
* inCallRef:
* The event handler call ref passed into your event handler.
*
* inEvent:
* The event to pass thru.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
CallNextEventHandler(
EventHandlerCallRef inCallRef,
EventRef inEvent);
/*--------------------------------------------------------------------------------------*/
/* o Sending Events */
/*--------------------------------------------------------------------------------------*/
/*
* Discussion:
* EventTarget Send Options
*/
enum {
/*
* The event should be sent to the target given only, and should not
* propagate to any other target. CallNextEventHandler will do
* nothing in a handler which has received an event sent in this
* manner.
*/
kEventTargetDontPropagate = (1 << 0),
/*
* The event is a notification-style event, and should be received by
* all handlers. The result is usually meaningless when sent in this
* manner, though we do maintain the strongest result code while the
* event falls through each handler. This means that if the first
* handler to receive the event returned noErr, and the next returned
* eventNotHandledErr, the result returned would actually be noErr.
* No handler can stop this event from propagating, i.e. the result
* code does not alter event flow.
*/
kEventTargetSendToAllHandlers = (1 << 1)
};
/*
* SendEventToEventTarget()
*
* Discussion:
* Sends an event to the specified event target.
*
* Parameters:
*
* inEvent:
* The event to send.
*
* inTarget:
* The target to send it to.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: in CarbonLib 1.1 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
SendEventToEventTarget(
EventRef inEvent,
EventTargetRef inTarget);
/*
* SendEventToEventTargetWithOptions()
*
* Discussion:
* Sends an event to the specified event target, optionally
* controlling how the event propagates. See the discussion of the
* event send options above for more detail.
*
* Parameters:
*
* inEvent:
* The event to send.
*
* inTarget:
* The target to send it to.
*
* inOptions:
* The options to modify the send behavior. Passing zero for this
* makes it behave just like SendEventToEventTarget.
*
* Result:
* An operating system result code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( OSStatus )
SendEventToEventTargetWithOptions(
EventRef inEvent,
EventTargetRef inTarget,
OptionBits inOptions);
#if PRAGMA_STRUCT_ALIGN
#pragma options align=reset
#elif PRAGMA_STRUCT_PACKPUSH
#pragma pack(pop)
#elif PRAGMA_STRUCT_PACK
#pragma pack()
#endif
#ifdef PRAGMA_IMPORT_OFF
#pragma import off
#elif PRAGMA_IMPORT
#pragma import reset
#endif
#ifdef __cplusplus
}
#endif
#endif /* __CARBONEVENTSCORE__ */
Reference in New Issue View Git Blame Copy Permalink