Series 300 Only

NAME

winput_setroute − routes input and events to another window

SYNOPSIS

int winput_setroute(fd,routepath);
int fd;
char ∗routepath;

DESCRIPTION

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

routepath
is a pointer to a null-terminated path name of the window to receive all input and events occurring in the window represented by fd.  This string can be a maximum of 40 characters in length. 

DISCUSSION

This routine reroutes a (source) window’s input to another (destination) window.  After calling this routine, all keystrokes and events that would normally go to the source window will instead be sent to the destination window.  The fd parameter is the file descriptor returned from opening the source window’s device interface; routepath points to the path name of the destination window’s window type device interface. 

On receiving input from the source window, the destination window will handle the data in a way appropriate to its input mode, as set by the wgskbd(3W) routine, regardless of the input mode of the source window.

Each window has its own set of winput_conf(3W) configuration parameters. When using input routing, it is normally desirable to have all windows set to the same configuration.  This can be accomplished either by setting each window to the same wgskbd(3W) mode or by explicitly calling winput_conf(3W) to set the parameters of each window. 

Although it is desirable to have the same winput_conf configuration parameters for each window, it is not absolutely necessary.  If the source and destination windows have different winput_conf parameters, then input from the destination window will conform to the winput_conf parameters of the source window. 

In Mode 2 (packetized input mode), the wid field of the event_code structure will be set to the window id of the window from which the packet originated.  Because of this, wid is useful to determine which window an event or keypress actually occurred in.  In all other modes, the process that reads data from the routepath window cannot determine which window the input data originated from. 

The call will return the window id, wid, for the window referenced by fd if it is successful.  Otherwise -1 will be returned, and errno(2) will be set appropriately.

If a window which is the target of one or more input routes is destroyed, all input routing for those windows is cancelled.  Input and event routing can also be disabled by passing a null value for routepath. 

When input routing is enabled for a window, any data waiting in the input queue at the time of the winput_setroute is flushed.  This is typically done immediately after an open(2) call, to ensure routing of important input and events. 

Multi-hop routing is allowed.  For example, the input to window a can be routed to window b, which in turn can be routed to window c.  In this example, any input to windows a, b, or c will be routed to window c. 

Note, however, that routing loops are not allowed.  For example, routing a to b, b to c, and c to a will cause an error.  Also, routing a window to itself (e.g., window d to window d) is a loop and is not allowed. 

If routing is disabled in one of the windows in a multi-hop route, then routing still is valid for the windows that precede the disabled window in the route path.  For example, suppose a routes to b, b routes to c, and c routes to d.  Then, if the route from c to d is disabled, any input originating from windows a, b, or c is still available only from window c, while input originating from window d is still available only from window d. 

HARDWARE DEPENDENCIES

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

SEE ALSO

wgskbd(3W),winput_conf(3W),winput_getroute(3W),winput_read(3W), winput_widpath(3W). 

DIAGNOSTICS

A return of -1 indicates failure; otherwise the window id, wid, of the window referenced by fd is returned.  See errno(2) for more information.

Hewlett-Packard Company  —  May 11, 2021