IKeyboardEvent

The IKeyboardEvent class represents keyboard-related events. A keyboard handler creates an IKeyboardEvent object when a user presses or releases a key.

You must verify that the character code value, scan code value, or virtual key value is valid before you use the value. Use isCharacter, isScanCode, and isVirtual, respectively, to do so. This class provides similar functions to check if the Shift key, Ctrl key, or Alt key is pressed.

If, however, you are within the callback function IKeyboardHandler::characterKeyPress, you do not need to check the character code value with isCharacter. The same is true for the scan code value from IKeyboardHandler::scanCodeKeyPress and the virtual key value from IKeyboardHandler::virtualKeyPress.

Open Class Library first dispatches keyboard events to the window with the input focus, such as an entry field with the input cursor. If that window does not process the keyboard event, it typically routes the event to its owner window. This causes Open Class Library then to dispatch the event to the owner window of the focus window. The event continues to be dispatched to the next owner window until a handler stops the processing or a window processes the keystroke itself. For example, an entry field processes character keys, but it does not process an Enter key. Instead, the entry field propagates the Enter key to its owner window.


IKeyboardEvent - Member Functions and Data by Group

Constructors & Destructor

You can construct, copy, assign, and destruct objects of this class.


[view class]
~IKeyboardEvent
public:
virtual ~IKeyboardEvent()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IKeyboardEvent


Overload 1
public:
IKeyboardEvent(const IKeyboardEvent& event)

Constructs an IKeyboardEvent object from the specified event, initializing the new event with the values of the specified one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IKeyboardEvent(const IEvent& event)

Constructs an IKeyboardEvent object from the specified event. IKeyboardHandler::dispatchHandlerEvent constructs objects of this class from objects of the class IEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator =
public:
IKeyboardEvent& operator =(const IKeyboardEvent& event)

This assignment operator replaces the values of the current IKeyboardEvent object with those of the specified event, event.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Accessors

These members allow you to query values from instances of this class.


[view class]
character
public:
virtual char character() const

Returns the character data of the key if it is a single-byte character. Before calling this function, you must verify that the event contains character data by calling IKeyboardEvent::isCharacter. If you expect multi-byte data, use IKeyboardEvent::mixedCharacter.

If the Ctrl key is pressed (you can test this by calling IKeyboardEvent::isCtrlDown) with a character key, this function does not return a control character. Instead it returns the same character as it would if the Ctrl key had not been pressed.

Exception

IInvalidRequest The keyboard event does not contain character data, or it contains a multi-byte character.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
mixedCharacter
public:
virtual IString mixedCharacter() const

Returns the character data of the key, whether it is a single- or multi-byte character. Before calling this function, you must verify that the event contains character data by calling IKeyboardEvent::isCharacter.

If the Ctrl key is pressed (you can test this by calling IKeyboardEvent::isCtrlDown) with a character key, this function does not return a control character. Instead it returns the same character as it would if the Ctrl key had not been pressed.

Exception

IInvalidRequest The keyboard event does not contain character data.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

When working with multi-byte characters, consider using the class ITextChangeHandler instead of IKeyboardHandler.

Windows Considerations

When working with multi-byte characters, consider using the class ITextChangeHandler instead of IKeyboardHandler.


[view class]
repeatCount
public:
virtual unsigned long repeatCount() const

Returns the number of repeated keys combined into this event.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
scanCode
public:
virtual unsigned long scanCode() const

Returns the hardware scan code of the key. Before calling this function, you must verify that the event contains a scan code by calling IKeyboardEvent::isScanCode.

Exception

IInvalidRequest The keyboard event does not contain a scan code, or it represents a multi-byte character.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
virtualKey
public:
virtual VirtualKey virtualKey() const

Returns the virtual key code of the key. Before calling this function, you must verify that the event contains a virtual key code by calling IKeyboardEvent::isVirtual. The enumeration VirtualKey provides the return values.

Exception

IInvalidRequest The keyboard event does not contain virtual key information.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Testing

Call these testing members to determine the type of data stored in the event.


[view class]
isAltDown
public:
virtual bool isAltDown() const

Returns whether the Alt key is being held down.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isCharacter
public:
virtual bool isCharacter() const

Returns whether the event represents use of a data key.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isComposite
public:
virtual bool isComposite() const

Returns whether the character is formed by combining this key with the previous nonescaping key.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isCtrlDown
public:
virtual bool isCtrlDown() const

Returns whether the Ctrl key is being held down.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isForComposite
public:
virtual bool isForComposite() const

Returns whether the character is a nonescaping key, such as an accent, which the user intends to combine with the next character.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isInvalidComposite
public:
virtual bool isInvalidComposite() const

Returns whether the character is not valid to be combined with the previous nonescaping key.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isRepeat
public:
virtual bool isRepeat() const

Returns whether a key has been previously pressed and is being held down.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isScanCode
public:
virtual bool isScanCode() const

Returns whether a hardware scan code is available.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isShiftDown
public:
virtual bool isShiftDown() const

Returns whether the Shift key is being held down.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isUncombined
public:
virtual bool isUncombined() const

Returns whether this key is being pressed without any other keys being pressed.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
isUpTransition
public:
virtual bool isUpTransition() const

Returns whether a previously pressed key is being released. If false, the key is either previously unpressed and now being pressed or previously pressed and still being held down.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isVirtual
public:
virtual bool isVirtual() const

Returns whether the event represents use of a virtual key.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IKeyboardEvent - Enumerations


[view class]
VirtualKey
enum VirtualKey { esc, 
                  tab, 
                  backTab, 
                  space, 
                  backSpace, 
                  enter, 
                  newLine, 
                  shift, 
                  ctrl, 
                  altGraf, 
                  insert, 
                  deleteKey, 
                  home, 
                  end, 
                  pageUp, 
                  pageDown, 
                  left, 
                  right, 
                  up, 
                  down, 
                  capsLock, 
                  numLock, 
                  scrollLock, 
                  pause, 
                  sysRq, 
                  breakKey, 
                  f2, 
                  f3, 
                  f4, 
                  f5, 
                  f6, 
                  f7, 
                  f8, 
                  f9, 
                  f11, 
                  f12, 
                  f13, 
                  f14, 
                  f15, 
                  f16, 
                  f17, 
                  f18, 
                  f19, 
                  f20, 
                  f21, 
                  f22, 
                  f23, 
                  f24, 
                  button1, 
                  button2, 
                  button3, 
                  other, 
                  endDrag, 
                  firstDBCS, 
                  lastDBCS, 
                  firstUser, 
                  lastUser, 
                  f1, 
                  f10, 
                  f25, 
                  f26, 
                  f27, 
                  f28, 
                  f29, 
                  f30, 
                  f31, 
                  f32, 
                  f33, 
                  f34, 
                  f35, 
                  pf1, 
                  pf2, 
                  pf3, 
                  pf4, 
                  clear, 
                  select, 
                  print, 
                  execute, 
                  undo, 
                  redo, 
                  menu, 
                  find, 
                  cancel, 
                  help, 
                  modeSwitch, 
                  alt, 
                  shiftLock, 
                  begin, 
                  meta, 
                  super, 
                  hyper, 
                  multiKey, 
                  kanji, 
                  muhenkan, 
                  henkanMode, 
                  romaji, 
                  hiragana, 
                  katakana, 
                  hiraganaKatakana, 
                  zenkaku, 
                  hankaku, 
                  zenkakuHankaku, 
                  touroku, 
                  massyo, 
                  kanaLock, 
                  kanaShift, 
                  eisuShift, 
                  eisuToggle, 
                  f1, 
                  f10 }

The preceding enumerators list the possible virtual key values that IKeyboardEvent::virtualKey can return. The Open Class Library provides enumerators for a generic keyboard, not just an IBM keyboard.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

The virtual key codes f1, f10, and alt do not appear in this list. Presentation Manager intercepts F1 and F10 key presses, and Alt releases, and processes them as system accelerators. Because of this, you never see them as keyboard events.

The following enumerators also are not supported: f25, f26, f27, f28, f29, f30, f31, f32, f33, f34, f35, pf1, pf2, pf3, pf4, clear, select, print, execute, undo, redo, menu, find, cancel, help, modeSwitch, alt, shiftLock, begin, meta, super, hyper, multiKey, kanji, muhenkan, henkanMode, romaji, hiragana, katakana, hiraganaKatakana, zenkaku, hankaku, zenkakuHankaku, touroku, massyo, kanaLock, kanaShift, eisuShift, and eisuToggle.


IKeyboardEvent - Inherited Member Functions and Data

Inherited Public Functions

IEvent

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data