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.
You can construct, copy, assign, and destruct objects of this class.
![]() |
public:
virtual ~IKeyboardEvent()
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IKeyboardEvent(const IKeyboardEvent& event)
Constructs an IKeyboardEvent object from the specified event, initializing the new event with the values of the specified one.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IKeyboardEvent& operator =(const IKeyboardEvent& event)
This assignment operator replaces the values of the current IKeyboardEvent object with those of the specified event, event.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
These members allow you to query values from instances of this class.
![]() |
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.
IInvalidRequest | The keyboard event does not contain character data, or it contains a multi-byte character. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
IInvalidRequest | The keyboard event does not contain character data. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
When working with multi-byte characters, consider using the class ITextChangeHandler instead of IKeyboardHandler.
When working with multi-byte characters, consider using the class ITextChangeHandler instead of IKeyboardHandler.
![]() |
public:
virtual unsigned long repeatCount() const
Returns the number of repeated keys combined into this event.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
IInvalidRequest | The keyboard event does not contain a scan code, or it represents a multi-byte character. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
IInvalidRequest | The keyboard event does not contain virtual key information. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Call these testing members to determine the type of data stored in the event.
![]() |
public:
virtual bool isAltDown() const
Returns whether the Alt key is being held down.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isCharacter() const
Returns whether the event represents use of a data key.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isComposite() const
Returns whether the character is formed by combining this key with the previous nonescaping key.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isCtrlDown() const
Returns whether the Ctrl key is being held down.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isInvalidComposite() const
Returns whether the character is not valid to be combined with the previous nonescaping key.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isRepeat() const
Returns whether a key has been previously pressed and is being held down.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isScanCode() const
Returns whether a hardware scan code is available.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isShiftDown() const
Returns whether the Shift key is being held down.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isUncombined() const
Returns whether this key is being pressed without any other keys being pressed.
Windows | OS/2 | AIX |
Ignored | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isVirtual() const
Returns whether the event represents use of a virtual key.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
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.
virtual ~IEvent()
IWindowHandle controlHandle() const
virtual IWindow* controlWindow() const
IEvent& decrementOwnerLevels()
virtual IWindow* dispatchingWindow() const
unsigned long eventId() const
IWindowHandle handle() const
IEvent( IWindow* window, unsigned long eventId, const IEventParameter1& parameter1, const IEventParameter2& parameter2 )
IEvent( const IWindowHandle& handle, unsigned long eventId, const IEventParameter1& parameter1, const IEventParameter2& parameter2 )
IEvent(const IEvent& event)
IEvent& operator =(const IEvent& event)
IEventParameter1 parameter1() const
IEventParameter2 parameter2() const
bool passToOwner() const
IEventResult result() const
IEvent& setControlHandle(const IWindowHandle& handle)
IEvent& setDispatchingHandle(const IWindowHandle& handle)
IEvent& setDispatchingWindow(IWindow* window)
IEvent& setHandle(const IWindowHandle& handle)
IEvent& setNumberOfLevels(int levels = - 1)
IEvent& setPassToOwner(bool passOn = true)
IEvent& setResult(bool eventResult)
IEvent& setResult(const IEventResult& eventResult)
virtual IWindow* window() const