Deprecated Event Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in OS X v10.5

KeyScript

Changes the keyboard script (the script system used for keyboard input), changes the keyboard layout (the mapping of keys to characters) or input method within the current keyboard script (a facility for entering 2-byte characters), or makes a setting related to text input, using the supplied value. (Deprecated in OS X v10.5.)

void KeyScript (
   short code
);
Parameters
code

If 0 or positive, directly specifies a script system (that is, it is read as a script code). Negative values have special meanings.

The code parameter is a selector that can explicitly specify a keyboard script by script code. See the Script Manager for a list of script codes. If the selector specifies a script, then the current default keyboard layout ('KCHR' resource) for that script, as specified in the script’s international bundle resource, becomes the current keyboard layout.

The selector can also implicitly specify a keyboard script (for example, the next script), a keyboard layout (for example, the previously used keyboard layout in the current script), or an input method (for example, inline input versus window-based input). It can also specify settings that enable or disable keyboard layouts and keyboard scripts, and toggle among input options or line direction.

Discussion

For the purposes of KeyScript, keyboard layout means a keyboard-layout ( 'KCHR') resource, plus optionally a key-remap ( 'itlk') resource. To change keyboard layouts means to change the current keyboard-layout resource.

If the Keyboard menu is displayed, KeyScript also updates the Keyboard menu.

If you call KeyScript and explicitly specify a script system that is not available, KeyScript does nothing. The current keyboard script remains unchanged.

Note that Keyscript also does nothing when passed a positive or zero script code if the user has Font and Keyboard Synchronization turned off. You can find the Font and Synchronization checkbox under Options in the Input Menu tab of the International System Preference in Mac OS X.

Special Considerations

KeyScript operates only on those keyboard-layout and key-remap resources that are present in the System file.

Your application’s keyboard-menu setting is not maintained by the Process Manager if the state of the keyboard menu is changed while you are switched out, the Process Manager does not restore your setting when you are switched back in. However, the Process Manager does maintain the keyboard disable state (Script Manager variable smKeyDisableState) for your application. See the Script Manager for a description of the smKeyDisableState variable. KeyScript may move memory; your application should not call this function at interrupt time.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.5.
  • Not available to 64-bit applications.
Declared In
Events.h

Deprecated in OS X v10.6

EventAvail

Retrieves the next available event from the Event Manager without removing the returned event from your application’s event stream. (Deprecated in OS X v10.6.)

Boolean EventAvail (
   EventMask eventMask,
   EventRecord *theEvent
);
Parameters
eventMask

A value that indicates which kinds of events are to be returned; this parameter is interpreted as a sum of event mask constants. You specify the event mask using one or more of the values defined by the “Event Mask Constants.” If no event of any of the designated types is available, EventAvail returns a null event.

theEvent

A pointer to an event structure for the next available event of the specified type or types. The EventAvail function does not remove the returned event from the event stream, but does return the information about the event in an event structure. The event structure includes the type of event received and other information.

Return Value

EventAvail returns false as its function result if the event being returned is a null event; otherwise, EventAvail returns true.

Special Considerations

If EventAvail returns a low-level event from the Operating System event queue, the event will not be accessible later if, in the meantime, the event queue becomes full and the event is discarded from it; however, this is not a common occurrence.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Related Sample Code
Declared In
Events.h

FlushEvents

Removes low-level events from the Operating System event queue. (Deprecated in OS X v10.6.)

void FlushEvents (
   EventMask whichMask,
   EventMask stopMask
);
Parameters
whichMask

A value that indicates which kinds of low-level events are to be removed from the Operating System event queue; this parameter is interpreted as a sum of event mask constants. You specify the event mask using one or more of the values defined in “Event Mask Constants.” The whichMask and stopMask parameters together specify which events to remove.

stopMask

A value that limits which low-level events are to be removed from the Operating System event queue; this parameter is interpreted as a sum of event mask constants. You specify the event mask using one or more of the values defined in “Event Mask Constants.” FlushEvents does not remove any low-level events that are specified by the stopMask parameter. To remove all events specified by the whichMask parameter, specify 0 as the stopMask parameter.

Discussion

FlushEvents removes only low-level events stored in the Operating System event queue; it does not remove activate, update, operating-system, or high-level events. FlushEvents does not remove any types of events not stored in the Operating System event queue.

You can choose to use the FlushEvents function when your application first starts to empty the Operating System event queue of any keystrokes or mouse events generated by the user while the Finder loaded your application. In general, however, your application should not empty the queue at any other time as this loses user actions and makes your application and the computer appear unresponsive to the user.

You specify which low-level events to remove using the whichMask and stopMask parameters. FlushEvents removes the low-level events specified by the whichMask parameter, up to but not including the first event of any type specified by the stopMask parameter.

If the event queue doesn’t contain any of the events specified by the whichMask parameter, FlushEvents does not remove any events from the queue.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
Declared In
Events.h

GetNextEvent

Retrieves events one at a time from the Event Manager. (Deprecated in OS X v10.6.)

Boolean GetNextEvent (
   EventMask eventMask,
   EventRecord *theEvent
);
Parameters
eventMask

A value that indicates which kinds of events are to be returned; this parameter is interpreted as a sum of event mask constants. You specify the event mask using one or more of the values defined in “Event Mask Constants.” If no event of any of the designated types is available, GetNextEvent returns a null event.

theEvent

A pointer to an event structure for the next available event of the specified type or types. The GetNextEvent function removes the returned event from the event stream and returns the information about the event in an event structure. The event structure includes the type of event received and other information.

Return Value
Discussion

GetNextEvent returns false as its function result if the event being returned is a null event or if GetNextEvent has intercepted the event; otherwise, GetNextEvent returns true. The GetNextEvent function calls the Operating System Manager function SystemEvent to determine whether the event should be handled by the application or the Operating System.

The GetNextEvent function also intercepts Command–Shift–number key sequences and calls the corresponding 'FKEY' resource to perform the associated action. The Event Manager’s processing of Command–Shift–number key sequences with numbers 3 through 9 can be disabled by setting the ScrDmpEnable global variable (a byte) to 0.

Special Considerations

For greater support of the multitasking environment, your application should use WaitNextEvent instead of GetNextEvent whenever possible.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Related Sample Code
Declared In
Events.h

IsCmdChar

Tests whether the Command key is pressed in conjunction with another key (or keys) that could generate the specified test character. (Deprecated in OS X v10.6.)

Boolean IsCmdChar (
   const EventRecord *event,
   short test
);
Parameters
event

The event record for a key-down or auto-key event with the Command key down.

test

The character you want to test.

Return Value

The function returns TRUE if the test character is produced with the current modifier keys, or if it would be produced by changing the current modifier key bits in either or both of the following ways: (1) turning the Command bit off or (2) toggling the Shift bit.

Discussion

This function tests whether the Command key is pressed in conjunction with another key (or keys) that could generate the test character for some combination of Command up or down and Shift up or down. This accommodates European keyboards that may have the test character as a shifted character, and non-Roman keyboards that will only generate the test character if the Command key is pressed. It's most useful for testing for Command-period, but it can test for command-AnyCharacter.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
Declared In
Events.h

KeyTranslate

Converts a virtual key code to a character code based on a 'KCHR' resource. (Deprecated in OS X v10.6.)

UInt32 KeyTranslate (
   const void *transData,
   UInt16 keycode,
   UInt32 *state
);
Parameters
transData

A pointer to the 'KCHR' resource that you want the KeyTranslate function to use when converting the key code to a character code.

keycode

A 16-bit value that your application should set so that bits 0–6 contain the virtual key code and bit 7 contains either 1 to indicate an up stroke or 0 to indicate a down stroke of the key. Bits 8–15 have the same interpretation as the high byte of the modifiers field of the event structure and should be set according to the needs of your application.

state

A pointer to a value that your application should set to 0 the first time it calls KeyTranslate or any time your application calls KeyTranslate with a different 'KCHR' resource. Thereafter, your application should pass the same value in the state parameter as KeyTranslate returned in the previous call.

Return Value

A 32-bit value that gives the character code for the virtual key code specified by the keycode parameter.

Discussion

The KeyTranslate function returns the values that correspond to one or possibly two characters that are generated by the specified virtual key code. The following diagram shows the structure of the 32-bit number that KeyTranslate returns.

31             24 23            16 15             8 7               0
---------------------------------------------------------------------
|                |                |                |                |
---------------------------------------------------------------------
    Reserved 1    Character code 1    Reserved 2    Character code 2

For example, a given virtual key code might correspond to an alphabetic character with a separate accent character. When the user presses Option-E followed by E, you can map this through the KeyTranslate function using the U.S. 'KCHR' resource to produce é, which KeyTranslate returns as two characters in the bytes labeled Character code 1 and Character code 2.

If KeyTranslate returns only one character code, it is always in the byte labeled Character code 2. However, your application should always check both bytes labeled Character code 1 and Character code 2 for possible values that map to the virtual key code.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Related Sample Code
Declared In
Events.h

PostEvent

Posts events into the Operating System event queue. (Deprecated in OS X v10.6.)

OSErr PostEvent (
   EventKind eventNum,
   UInt32 eventMsg
);
Parameters
eventNum

A value that indicates the type of event to post into the Operating System event queue. You specify the event kind using one or more of these values defined in “Event Mask Constants”: mouseDown, mouseUp, keyDown, keyUp, autoKey, and diskEvt. Do not attempt to post any other type of event in the Operating System event queue.

eventMsg

An unsigned integer that contains the contents of the message field for the event that PostEvent should post in the queue.

Return Value

A result code. See “Event Manager Result Codes.”

Discussion

In the eventNum and eventMsg parameters, you specify the value for the what and message fields of the event’s event structure. The PostEvent function fills out the when, where, and modifiers fields of the event structure with the current time, current mouse location, and current state of the modifier keys and mouse button.

The PostEvent function posts only events that are enabled by the system event mask. If the event queue is full, PostEvent removes the oldest event in the queue and posts the new event.

Note that if you use PostEvent to repost an event, the PostEvent function fills out the when, where, and modifier fields of the event structure, giving these fields of the reposted event different values from the values contained in the original event.

Do not post any events other than mouse-down, mouse-up, key-down, key-up, auto-key, and disk-inserted events in the Operating System event queue. Attempting to post other events into the Operating System event queue interferes with the internal operation of the Event Manager.

In most cases, your application should not call the PostEvent function.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
Events.h

WaitNextEvent

Retrieves events one at a time from the Event Manager. (Deprecated in OS X v10.6.)

Boolean WaitNextEvent (
   EventMask eventMask,
   EventRecord *theEvent,
   UInt32 sleep,
   RgnHandle mouseRgn
);
Parameters
eventMask

A value that indicates which kinds of events are to be returned. This parameter is interpreted as a sum of event mask constants. You specify the event mask using values defined in “Event Mask Constants.” To accept all events, you can specify the everyEvent constant as the event mask.

If no event of any of the designated types is available, WaitNextEvent returns a null event. WaitNextEvent determines the next available event to return based on the eventMask parameter and the priority of the event.

Events not designated by the event mask remain in the event stream until retrieved by an application. Low-level events in the Operating System event queue are kept in the queue until they are retrieved by your application or another application or until the queue becomes full. Once the queue becomes full, the Operating System Event Manager begins discarding the oldest events in the queue.

theEvent

A pointer to an event structure for the next available event of the specified type or types. The WaitNextEvent function removes the returned event from the event stream and returns the information about the event in an event structure. The event structure includes the type of event received and other information.

In addition to the event structure, high-level events can contain additional data; use the Apple Event Manager AEProcessAppleEvent function to get additional data associated with these events.

sleep

The number of ticks (a tick is approximately 1/60 of a second) indicating the amount of time your application is willing to relinquish the processor if no events are pending for your application. If you specify a value greater than 0 for the sleep parameter, your application relinquishes the processor for the specified time or until an event occurs.

You should not set the sleep parameter to a value greater than the number of ticks returned by GetCaretTime if your application provides text-editing capabilities. When the specified time expires, and if there are no pending events for your application, WaitNextEvent returns a NULL event in the parameter theEvent.

When running on Mac OS X, a Carbon application will block for the entire duration of the sleep parameter if there are no events to be delivered. This is slightly different behavior than on Mac OS 9, where the application will often receive NULL events before the sleep duration has elapsed.

mouseRgn

A handle to a region that specifies a region inside of which mouse movement does not cause mouse-moved events. In other words, your application receives mouse-moved events only when the cursor is outside the specified region. You should specify the region in global coordinates. If you pass an empty region or a null region handle, the Event Manager does not report mouse-moved events to your application. Note that your application should recalculate the mouseRgn parameter when it receives a mouse-moved event, or it will continue to receive mouse-moved events as long as the cursor position is outside the original mouseRgn.

Return Value

The WaitNextEvent function returns false as its function result if the event being returned is a null event or if WaitNextEvent has intercepted the event; otherwise, WaitNextEvent returns true.

Discussion

The WaitNextEvent function calls the Operating System Event Manager function SystemEvent to determine whether the event should be handled by the application or the Operating System.

If no events are pending for your application, WaitNextEvent waits for a specified amount of time for an event. (During this time, processing time may be allocated to background processes.) If an event occurs, it is returned through the parameter theEvent, and WaitNextEvent returns a function result of true. If the specified time expires and there are no pending events for your application, WaitNextEvent returns a null event in theEvent and a function result of false.

Before returning an event to your application, WaitNextEvent performs other processing and may intercept the event.

The WaitNextEvent function intercepts Command–Shift–number key sequences and calls the corresponding ' FKEY ' resource to perform the associated action. The Event Manager’s processing of Command–Shift–number key sequences with numbers 3 through 9 can be disabled by setting the ScrDmpEnable global variable (a byte) to 0.

If the returned event is a high-level event and your application supports Apple events, use the Apple Event Manager function AEProcessAppleEvent to respond to the Apple event and to get additional information associated with the Apple event.

To retrieve an event without removing it from the event stream, use EventAvail.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Related Sample Code
Declared In
Events.h


© 2003, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-10-31)