Advanced Search
Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC


Reading the Keyboard


GetKeys Obtains the current state of the keyboard.
KeyTranslate Converts a virtual key code to a character code based on a 'KCHR' resource.
GetCurrentKeyModifiers Returns the current state of the keyboard modifier keys.
IsCmdChar Tests whether the Command key is pressed in conjunction with another key (or keys) that could generate the specified test character.


GetKeys


Obtains the current state of the keyboard.

void GetKeys (
   KeyMap theKeys
);
Parameter Descriptions
theKeys
Returns the current state of the keyboard, including the keypad, if any. The GetKeys function returns this information using the KeyMap type.

typedef long KeyMap[4];

The KeyMap type is interpreted as an array of 128 elements, each having a Boolean value. Each key on the keyboard or keypad corresponds to an element in the KeyMap array. The index for a particular key is the same as the key’s virtual key code minus 1. For example, the key with virtual key code 38 (the “J” key on the Apple Keyboard II) is the 38th element in the returned array. A KeyMap element is true if the corresponding key is down and false if it isn’t. The maximum number of keys that can be down simultaneously is two character keys plus any combination of the five modifier keys.


function result
Discussion

You can use the GetKeys function to determine the current state of the keyboard at any time. For example, you can determine whether one of the modifier keys is down by itself or in combination with another key using the GetKeys function.

Availability

Supported in Carbon. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

Header: Events.h


KeyTranslate


Converts a virtual key code to a character code based on a 'KCHR' resource.

UInt32 KeyTranslate (
   const void * transData,
   UInt16 keycode,
   UInt32 * state
);
Parameter Descriptions
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.

function result
Discussion

The KeyTranslate function returns a 32-bit value that gives the character code for the virtual key code specified by the keycode parameter.

The KeyTranslate function returns the values that correspond to one or possibly two characters that are generated by the specified virtual key code. For example, a given virtual key code might correspond to an alphabetic character with a separate accent character. For example, when the user presses Option-E followed by N, you can map this through the KeyTranslate function using the U.S. 'KCHR' resource to produce ´n, 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

Supported in Carbon. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

Header: Events.h


GetCurrentKeyModifiers


Returns the current state of the keyboard modifier keys.

UInt32 GetCurrentKeyModifiers ();
Parameter Descriptions
function result
A bit mask indicating which keyboard modifier keys are pressed. See "Event Modifier Constants" for a list of possible values.

Discussion

GetCurrentKeyModifiers provides a more convenient way to get the modifier key state than calling GetNextEvent. It returns a value whose individual bits indicate which keyboard modifier keys are currently being pressed. You can test for the Caps Lock, Shift, Control, Option, and Command keys using the “Event Manager Reference” defined by the Event Manager.

Availability

Supported in Carbon. Available in CarbonLib 1.0 and later. Available in Mac OS X 10.0 and later.

Header: Events.h


IsCmdChar


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

Boolean IsCmdChar (
   const EventRecord * event,
   short test
);
Parameter Descriptions
event
The event record for a key-down or auto-key event with the Command key down.

test
The character you want to test.

function result
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

Supported in Carbon. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

Header: Events.h





Last updated: 2003-04-01

Get information on Apple products.
Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Copyright © 2004 Apple Computer, Inc.
All rights reserved. | Terms of use | Privacy Notice