### 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.

~IKeyboardEvent

      public:
      virtual ~IKeyboardEvent()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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.

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

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.

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

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

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.

isAltDown

      public:
      virtual bool isAltDown() const

  Returns whether the Alt key is being held down.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

isCtrlDown

      public:
      virtual bool isCtrlDown() const

  Returns whether the Ctrl key is being held down.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

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

isScanCode

      public:
      virtual bool isScanCode() const

  Returns whether a hardware scan code is available.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isShiftDown

      public:
      virtual bool isShiftDown() const

  Returns whether the Shift key is being held down.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

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

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

  -     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

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None