WINPUT_READ(3W)

Series 300 Only

NAME

winput_read − read from window input channel

SYNOPSIS

#include <window.h>
int winput_read(fd,bufadr,count);
int fd;
struct event_code *bufadr;
int count;

DESCRIPTION

fd is an integer file descriptor for an opened graphics window type device interface.

bufadr
the address of the buffer to read data into.

count
number of packets to read.

DISCUSSION

This routine may only be used in conjunction with wgskbd(3W) mode 2, known as packetized input mode.

Winput_read reads event_code packets (described below) into a buffer pointed to by bufadr. Each packet placed in the buffer represents a single key press or an event.

Winput_read attempt to read count packets into the bufadr buffer. The number of packets read is returned, and could be less than the number requested, or even zero. For optimal performance, set count to 25.

If more than 25 events occur between calls to winput_read, some event information may be lost. When this occurs, an event_code packet is sent with its event_byte field set to K_OVERFLOW. Any key presses or hot spot events occuring after the overflow condition will be lost. However, the most recent event for all other types of events will not be lost. For example, suppose K_OVERFLOW occurs and the user moves a window several times before the program calls winput_read. Then all window move events between the K_OVERFLOW and the final window move will be lost. But the last window move won’t be lost; the program will still receive a packet for the last window move.

If winput_read is called from a window that has no data available, then the action taken by winput_read depends on the O_NDELAY value, set when the window type device interface was opened. See open(2) and fcntl(2) for details on O_NDELAY. If O_NDELAY is set, winput_read returns 0, meaning that no event packets have yet occurred since the last call to winput_read. If O_NDELAY is not set, winput_read will block until a signal or an event occurs in the window, at which point winput_read returns an event_code packet for the event. If a signal occurred, but not an event, winput_read will return 0.

The packets returned in bufadr are defined by the event_code structure (found in window.h):

struct event_code {
    unsigned char control_byte;
    unsigned char data_byte;
    unsigned char event_byte;
    unsigned char event_cause;
    unsigned int timestamp;
    unsigned int wid;
    int x;
    int y;
};

timestamp
A 32-bit integer number that specifies when, in milliseconds, the packet was received.

wid The window id that the packet originated in. (The winput_widpath(3W) routine can be used to convert this into a window path name.)

control_byte
is a bit field consisting of the OR of the following:

K_SHIFT_B Shift

K_CONTROL_B Control

K_META_B META

K_EXTEND_B Right Extend

K_UP UP==1 DOWN==0

K_NPAD Number Pad Key

K_EVENT Key==0 Event==1

K_SPECIAL Special Keys such as CLR LINE, ENTER, f1, etc.

data_byte
is either a special key (if K_SPECIAL is true), or it is a processed character value appropriate for the current configuration of the input channel (as set by winput_conf(3W)).

Below is a list of all the unique keys (other than alpha-numeric) that are currently supported for the K_SPECIAL data case. (Notice that with the addition of the control bits, every possible unique normal physical mechanical key combination can be represented.)

K_ILLEGAL if no character, data byte will contain ILLEGAL

K_CAPS_ON Only when K_CAPSMODE enabled

K_CAPS_OFF Only when K_CAPSMODE enabled

K_GO_ROMAN Only when language is Katakana or Kanji

K_GO_KATAKANA Only when language is Katakana or Kanji

K_GO_KANJI Only when language is Katakana or Kanji

K_GO_NOKANJI Only when language is Katakana or Kanji

K_CAPS_LOCK Only when K_CAPSMODE disabled

K_TAB

K_F1

K_F2

K_F3

K_F4

K_F5

K_F6

K_F7

K_F8

K_DOWN_ARROW ROLL_DOWN when shifted

K_UP_ARROW ROLL_UP when shifted

K_LEFT_ARROW ROLL_LEFT when shifted

K_RIGHT_ARROW ROLL_RIGHT when shifted

K_INSERT_LINE

K_DELETE_LINE

K_INSERT_CHAR

K_DELETE_CHAR

K_BACKSPACE

K_RETURN

K_EXTEND_LEFT

K_EXTEND_RIGHT

K_META_LEFT

K_META_RIGHT

K_BUTTON1

K_BUTTON2

K_BUTTON3

K_BUTTON4

K_BUTTON5

K_BUTTON6

K_BUTTON7

K_BUTTON8 In proximity−i.e., the graphics tablet stylus or puck switch was placed on the graphics tablet.

K_BREAK RESET_KEY when shifted

K_STOP

K_SELECT

K_NP_ENTER

K_NP_K0

K_NP_K1

K_NP_K2

K_NP_K3

K_HOME_ARROW

K_PREV

K_NEXT

K_ENTER PRINT when shifted K_SYSTEM (USER when shifted)

K_MENU

K_CLR_LINE

K_CLR_DISP

event_byte
is used if the K_EVENT bit is set in control_byte. It can have any of the following values:

K_MOVE_CT Window Move Completion

K_SIZE_LR_CT Size Lower Right Completion

K_ICON_SHK Shrink to an icon

K_ICON_EXP Expand from an icon

K_PAUSE Pause Toggle Bit

K_DESTROY Window is trying to be destroyed

K_SELECTED Window was just selected

K_USELECTED Window was just unselected

K_REPAINT Window needs to be repainted

K_FSSM_ABORT Full screen sprite mode aborted

K_MOUSE_MOVE Mouse has moved

K_BUTTON Button press/release

K_MENU_ITEM User popup menu item selected

K_ELEV_CT Elevator move complete

K_SB_ARROW Scroll bar arrow event

K_OVERFLOW Overflow occurred - events lost

K_USER_HS First user-defined hotspot

K_USER_HS+1 Second user-defined hotspot

K_USER_HS+n nth user-defined hotspot

K_USER_HS+127 Last user-defined hotspot

x,y are used if the K_EVENT bit is set in control_byte. For events (other than hotspots) that generate the SIGWINDOW signal, x and y are set to the values described in weventpoll(3W). For hotspot events, x and y provide the position of the locator, relative to location 0,0 of the window’s raster.

event_cause
is used if the K_EVENT bit is set in control_byte and if the event was caused by a hotspot or valid menu item selection. It indicates which locator button or keyboard key was pressed, or if a hotstop was entered or exited. event_cause can have any one of the following values:

EC_NONE No button pressed and no hotspot entered.

EC_BUTTON1 Button 1 was pressed

EC_BUTTON2 Button 2 was pressed

EC_BUTTON3 Button 3 was pressed

EC_BUTTON4 Button 4 was pressed

EC_BUTTON5 Button 5 was pressed

EC_BUTTON6 Button 6 was pressed

EC_BUTTON7 Button 7 was pressed

EC_BUTTON8 Button 8 was pressed, in proximity−i.e., the graphics tablet stylus or puck switch was placed on the graphics tablet

EC_SELECT SELECT was pressed

EC_ENTER Hotspot was entered

EC_EXIT Hotspot was exited

HARDWARE DEPENDENCIES

Series 500:
Graphics window input routines (winput_∗) are not supported on Series 500; they work only on Series 300.

DIAGNOSTICS

A return of -1 indicates failure; otherwise the number of packets read is returned. See errno(2) for more information.

Hewlett-Packard Company — May 11, 2021

Museum

Related Articles