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.

---

In 6.5.0, KD QNX extension enums have been corrected to use the proper naming conventions. The naming convention KD_QNX_* has been changed to KD_*_QNX. Any existing 6.4.1 applications that have been built with the old KD headers will still be binary compatible with applications that are created in 6.5.0 however, in order to rebuild applications with the new 6.5.0 KD header, you must update all extension enum references to the new format.

---

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_IOGROUP_ASSIGN_GROUP_QNX I/O group has I/O items that require a window handle to be passed as the output value:

kdOutputSetpQNX (KD_OUTPUT_ASSIGN_POINTER_QNX, 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_EVENT_KEYBOARD_QNX

Keyboard input event.

Synopsis:

#define KD_EVENT_KEYBOARD_QNX (KD_EVENT_UNDEFINED_QNX + 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_IOGROUP_KEYBOARD_QNX

Synopsis:

#define KD_IOGROUP_KEYBOARD_QNX (KD_IO_UNDEFINED + 0x1000)
#define KD_STATE_KEYBOARD_AVAILABILITY_QNX (KD_QNX_IOGROUP_KEYBOARD + 0)
#define KD_INPUT_KEYBOARD_FLAGS_QNX (KD_QNX_IOGROUP_KEYBOARD + 1)
#define KD_INPUT_KEYBOARD_MODIFIERS_QNX (KD_QNX_IOGROUP_KEYBOARD + 2)
#define KD_INPUT_KEYBOARD_KEY_CAP_QNX (KD_QNX_IOGROUP_KEYBOARD + 3)
#define KD_INPUT_KEYBOARD_KEY_SCAN_QNX (KD_QNX_IOGROUP_KEYBOARD + 4)
#define KD_INPUT_KEYBOARD_KEY_SYM_QNX (KD_QNX_IOGROUP_KEYBOARD + 5)

Any time a key is pressed on the keyboard, a KD_EVENT_KEYBOARD_QNX 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_IOGROUP_KEYBOARD_QNX + 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_EVENT_KEYBOARD_QNX event is generated, rather than the normal KD_EVENT_INPUT.

KD_STATE_KEYBOARD_AVAILABILITY_QNX is a state with a constant value that indicates, using a bitmap, which inputs are available. Bit n represents input KD_INPUT_KEYBOARD_FLAGS_QNX + 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_IOGROUP_DISP_GROUP_QNX (KD_IO_UNDEFINED + 0x500)
#define KD_STATE_DISP_GROUP_AVAILABILITY_QNX (KD_QNX_IOGROUP_DISP_GROUP + 0)
#define KD_OUTPUT_DISP_POINTER_QNX (KD_QNX_IOGROUP_DISP_GROUP + 1)
#define KD_OUTPUT_DISP_JOGDIAL_QNX (KD_QNX_IOGROUP_DISP_GROUP + 2)
#define KD_OUTPUT_DISP_KEYBOARD_QNX (KD_QNX_IOGROUP_DISP_GROUP + 3)
#define KD_OUTPUT_DISP_MOUSE_QNX (KD_IOGROUP_DISP_GROUP_QNX + 4)
#define KD_OUTPUT_DISP_TOUCH_QNX (KD_IOGROUP_DISP_GROUP_QNX + 5)

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_OUTPUT_DISP_POINTER_QNX 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_OUTPUT_DISP_POINTER_QNX + index of keyboard × KD_IO_CONTROLLER_STRIDE).

I/O items

KD_STATE_DISP_GROUP_AVAILABILITY_QNX is a state with a constant value that indicates, using a bitmap, which outputs are available. Bit n represents output KD_OUTPUT_DISP_POINTER_QNX + 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.

8

There's a mouse.

16

There's a touch screen.

31

A pointer, jogdial, keyboard, mouse, and touch screen are present.

KD_QNX_IOGROUP_ASSIGN_GROUP

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

Synopsis:

#define KD_IOGROUP_ASSIGN_GROUP_QNX (KD_IO_UNDEFINED + 0)
#define KD_STATE_ASSIGN_GROUP_AVAILABILITY_QNX (KD_IOGROUP_ASSIGN_GROUP_QNX + 0)
#define KD_OUTPUT_ASSIGN_POINTER_QNX (KD_IOGROUP_ASSIGN_GROUP_QNX + 1)
#define KDOUTPUT_ASSIGN_JOGDIAL_QNX_ (KD_IOGROUP_ASSIGN_GROUP_QNX + 2)
#define KD_OUTPUT_ASSIGN_KEYBOARD_QNX (KD_IOGROUP_ASSIGN_GROUP_QNX + 3)
#define KD_OUTPUT_ASSIGN_MOUSE_QNX (KD_IOGROUP_ASSIGN_GROUP_QNX + 4)
#define KD_OUTPUT_ASSIGN_TOUCH_QNX (KD_IOGROUP_ASSIGN_GROUP_QNX + 5)

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_OUTPUT_ASSIGN_JOGDIAL_QNX 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_OUTPUT_ASSIGN_KEYBOARD_QNX + 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_STATE_ASSIGN_GROUP_AVAILABILITY_QNX is a state with a constant value that indicates, using a bitmap, which outputs are available. Bit n represents output KD_OUTPUT_ASSIGN_JOGDIAL_QNX + 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.

8

There's a mouse.

16

There's a touch screen.

31

A pointer, jogdial, keyboard, mouse, and touch screen are present.

See also:

Working with External APIs, KD_QNX_window, io-winmgr