KD_QNX_input

The KD_QNX_input extension

Description:

The KD_QNX_input extension aims to extend the OpenKODE specification to address issues such as focus rules in a multi-window and/or multi-display environment. The extension also adds support for a keyboard I/O group and keyboard events, which are currently lacking in the OpenKODE 1.0.2 Core Specification.

Functions:

kdOutputSetpQNX()

KDint32 kdOutputSetpQNX( KDint32 startidx, KDuint32 numidxs, const void *buffer );

Except for the data type that is operated on, this function behaves the same as the kdOutputSeti() and kdOutputSetf() OpenKODE Core functions. This function operates on const void * data types which allow you to pass opaque handles to objects to the implementation for processing.

For example, the KD_QNX_IOGROUP_ASSIGN_GROUP I/O group has I/O items that require a window handle to be passed as the output value:

kdOutputSetpQNX (KD_QNX_OUTPUT_ASSIGN_POINTER, 1, &kd_win);

On success, the function returns the number of outputs that were actually set. Otherwise, it returns -1 and stores one of the error codes listed below into the error indicator returned by kdGetError().

The kdOutputSetpQNX() function returns the following error codes:

KD_ENOMEM

Out of memory or other resource.

KD_EIO

Non-specific error from I/O device.

Events:

KD_QNX_EVENT_KEYBOARD

Keyboard input event.

Synopsis:

#define KD_QNX_EVENT_KEYBOARD (KD_QNX_EVENT_UNDEFINED + 1000)

Fired when an input in the keyboard device changes.

The data is contained in the keyboardqnx element of the event data union, with the type KDEventKeyboardQNX, with the following fields:

typedef struct KDEventKeyboardQNX {
    KDint32     index;
    KDuint32    flags;
    KDuint32    modifiers;
    KDuint32    key_cap;
    KDuint32    key_scan;
    KDuint32    key_sym;
} KDEventKeyboardQNX;

index

The index number of the input that actually changed.

flags

The status of the key (e.g. key down or key repeat).

modifiers

The key modifiers for the keyboard event. Some keys (for example, Shift or Num Lock) modify other keys. When a modifier key is pressed or released, it's evaluated through a table and the modifiers field is updated accordingly.

key_cap

The unique scan code produced by the key, without any modifiers.

key_scan

The hardware-dependent scan code for the key.

key_sym

The value of the key with modifiers applied to it.

The key flags, modifiers, and keycodes which the system generates can be found in sys/keycodes.h.

When any one of the application's windows has input focus, the event is sent to that window. The eventuserptr parameter supplied when the window was created is then used as the value of the userptr field of the input event. The event is sent to the queue for the thread that created the window.

I/O groups and items

The I/O groups and items that this extension introduces into OpenKODE by this extension are listed in this section.

KD_QNX_IOGROUP_KEYBOARD

Synopsis:

#define KD_QNX_IOGROUP_KEYBOARD (KD_IO_UNDEFINED + 0x1000)
#define KD_QNX_STATE_KEYBOARD_AVAILABILITY (KD_QNX_IOGROUP_KEYBOARD + 0)
#define KD_QNX_INPUT_KEYBOARD_FLAGS (KD_QNX_IOGROUP_KEYBOARD + 1)
#define KD_QNX_INPUT_KEYBOARD_MODIFIERS (KD_QNX_IOGROUP_KEYBOARD + 2)
#define KD_QNX_INPUT_KEYBOARD_KEY_CAP (KD_QNX_IOGROUP_KEYBOARD + 3)
#define KD_QNX_INPUT_KEYBOARD_KEY_SCAN (KD_QNX_IOGROUP_KEYBOARD + 4)
#define KD_QNX_INPUT_KEYBOARD_KEY_SYM (KD_QNX_IOGROUP_KEYBOARD + 5)

Any time a key is pressed on the keyboard, a KD_QNX_EVENT_KEYBOARD event is generated that contains data associated with the key.

This I/O group can be a per-game-controller group: further groups with the same semantics may appear at KD_QNX_IOGROUP_KEYBOARD + n * KD_IO_CONTROLLER_STRIDE (where n is 1 for the second controller, up to 63 for the 64th controller, and KD_IO_CONTROLLER_STRIDE is 64).

I/O items

When any keyboard inputs change, the KD_QNX_EVENT_KEYBOARD event is generated, rather than the normal KD_EVENT_INPUT.

KD_QNX_STATE_KEYBOARD_AVAILABILITY is a state with a constant value that indicates, using a bitmap, which inputs are available. Bit n represents input KD_QNX_INPUT_KEYBOARD_FLAGS + n, and is set to 1 if the input is available and 0 if not, with unused bits set to 0. The value of the state is 0 if the group is temporarily unavailable, 31 if available.

KD_QNX_IOGROUP_DISP_GROUP

I/O group for per-input I/O group display focus.

Synopsis:

#define KD_QNX_IOGROUP_DISP_GROUP (KD_IO_UNDEFINED + 0x500)
#define KD_QNX_STATE_DISP_GROUP_AVAILABILITY (KD_QNX_IOGROUP_DISP_GROUP + 0)
#define KD_QNX_OUTPUT_DISP_POINTER (KD_QNX_IOGROUP_DISP_GROUP + 1)
#define KD_QNX_OUTPUT_DISP_JOGDIAL (KD_QNX_IOGROUP_DISP_GROUP + 2)
#define KD_QNX_OUTPUT_DISP_KEYBOARD (KD_QNX_IOGROUP_DISP_GROUP + 3)

This I/O group defines outputs that give the ability to assign an input device's display focus. The outputs take a display ID argument for which to set the display focus of the I/O group corresponding to the I/O items define (for example, KD_QNX_OUTPUT_DISP_POINTER corresponds to the KD_IOGROUP_POINTER). The display ID must correspond to the display ID specified in winmgr.conf or to a system generated display ID. If the display ID argument is -1, focus will be reset to the default, which is to set display focus to the first display.

This I/O group supports stride. Any input device's I/O groups that support stride, support corresponding I/O items. This allows your application to set focus to a particular device when there is more than one device present. Additional I/O items will be present at the base offset of the device type multiplied by index of the device × stride (for example, KD_QNX_OUTPUT_DISP_POINTER + index of keyboard × KD_IO_CONTROLLER_STRIDE).

I/O items

KD_QNX_STATE_DISP_GROUP_AVAILABILITY is a state with a constant value that indicates, using a bitmap, which outputs are available. Bit n represents output KD_QNX_OUTPUT_DISP_POINTER + n, and is set to 1 if the output is available, and 0 if not, with unused bits set to 0. The value of the state is:

0

The group is temporarily unavailable.

1

There's a pointer present.

2

There's a jogdial preset.

4

There's a keyboard.

7

A pointer, jogdial, and keyboard are present.

KD_QNX_IOGROUP_ASSIGN_GROUP

I/O group for per-input I/O group window focus.

Synopsis:

#define KD_QNX_IOGROUP_ASSIGN_GROUP (KD_IO_UNDEFINED + 0)
#define KD_QNX_STATE_ASSIGN_GROUP_AVAILABILITY (KD_QNX_IOGROUP_ASSIGN_GROUP + 0)
#define KD_QNX_OUTPUT_ASSIGN_POINTER (KD_QNX_IOGROUP_ASSIGN_GROUP + 1)
#define KD_QNX_OUTPUT_ASSIGN_JOGDIAL (KD_QNX_IOGROUP_ASSIGN_GROUP + 2)
#define KD_QNX_OUTPUT_ASSIGN_KEYBOARD (KD_QNX_IOGROUP_ASSIGN_GROUP + 3)

This I/O group defines outputs which give the ability to assign an input device's focus to a specific window. The outputs take a window argument in order to set the focus of the I/O group corresponding to the I/O items define (for example, KD_QNX_OUTPUT_ASSIGN_JOGDIAL corresponds to the KD_IOGROUP_JOGDIAL). The window argument can have been created in any thread of an application, or must be the KDWindow field of a notification event sent to a delegate thread. If the window argument is -1, focus will be reset to the default value, which is to obey global focus.

Global focus consists of the display that has current focus, and the window that has focus on that display. Global focus can be set with pointer devices by clicking and releasing on the same window. When you set the focus to a particular window, it causes it to obey the assignment of focus for that device.

This I/O group supports stride. Any input device's I/O groups that support stride, support the corresponding I/O items. This lets your application set focus to a particular device when there is more then one present. Additional I/O items will be present at the base offset of the device type multiplied by index of the device * stride (for example, KD_QNX_OUTPUT_ASSIGN_KEYBOARD + index of keyboard * KD_IO_CONTROLLER_STRIDE).

---

The absence of pointer devices is intentional, since they are used to set global focus.

---

I/O items

KD_QNX_STATE_ASSIGN_GROUP_AVAILABILITY is a state with a constant value that indicates, using a bitmap, which outputs are available. Bit n represents output KD_QNX_OUTPUT_ASSIGN_JOGDIAL + n, and is set to 1 if the output is available, and 0 if not, with unused bits set to 0.

The value of the state is:

0

The group is temporarily unavailable.

1

There's a jogdial preset.

2

There's a keyboard.

3

A pointer, jogdial, and keyboard are present.

See also:

Working with External APIs, KD_QNX_window, io-winmgr