WHOTSPOT_CREATE(3W)

Series 300 Only

NAME

whotspot_create − create a hotspot

SYNOPSIS

#include <window.h>
int whotspot_create(fd,bmask,x,y,w,h,event_byte);
int fd;
int bmask;
int x,y,w,h;
int event_byte;

DESCRIPTION

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

bmask
is a bit mask indicating which locator button(s) activate the hotspot. The bit mask is defined as follows:

HS_MASK_BUTTON1 Locator Button 1

HS_MASK_BUTTON2 Locator Button 2

HS_MASK_BUTTON3 Locator Button 3

HS_MASK_BUTTON4 Locator Button 4

HS_MASK_BUTTON5 Locator Button 5

HS_MASK_BUTTON6 Locator Button 6

HS_MASK_BUTTON7 Locator Button 7

HS_MASK_BUTTON8 Locator Button 8 (In Proximity)−i.e., the graphics tablet stylus or puck switch was placed on the graphics tablet

HS_MASK_SELECT Keyboard SELECT

HS_MASK_ENTEREXIT Locator enter/exit

x,y are the coordinates of the upper left corner of the rectangular hotspot region in device units relative to the upper left corner of the virtual raster of the window.

w,h are the width and height of the rectangular hotspot region in device units. These parameters must be greater than zero.

event_byte
is the event to occur when the hotspot is activated. Legal values are discussed below.

DISCUSSION

This call creates a hotspot for the window specified by the opened fd. The hotspot_id for the created hotspot is returned. The hotspot_id is then used to refer to the newly created hotspot in subsequent calls. If a -1 is returned the call was unsuccessful.

A hotspot is activated whenever one of the buttons or the SELECT key specified in bmask is pressed while the locator is within the rectangle defined by x,y,w,h. A hotspot will also be activated if the enter/exit bit in bmask is 1 and the locator enters or exits the specified hotspot. Any combination of locator buttons, SELECT key, and enter/exit may be specified in bmask.

The activation of a hotspot can be detected by enabling SIGWINDOW for hotspots via wsetsigmask(3W), then using weventpoll(3W) to determine which hotspot was activated. Weventpoll(3W) will return the event_byte for the last hotspot activated and the cause for the hotspot being activated in x and y respectively. The cause returned in y can be any one of the following:

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 (proximity) was pressed−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

If packetized window input is enabled for the window (see wgskbd(3W)), the hotspot data can be read from the input queue as an event_code packet. The value for the control_byte will be K_EVENT, the value for data_byte will be K_ILLEGAL, the value for event_byte will be the value specified in whotspot_create or whotspot_set(3W), and the value for event_cause will be one of EC_BUTTON1 through EC_EXIT.

The value specified for event_byte must be one of K_MOVE_ST, K_SIZE_LR_ST, K_POPUP_ST, or a value between 128 and 255 inclusive. If the value is K_MOVE_ST, K_SIZE_LR_ST, or K_POPUP_ST, then an interactive move, size, or pop-up menu, respectively, will be started for that window. In those cases the hotspot activation will not be signalled via SIGWINDOW. If event_byte is between 128 and 255 inclusive, the hotspot activation will be signalled via SIGWINDOW and the event_code packet will also be available via the packetized input queue.

The rectangles defined by hotspots can overlap. When they overlap, the hotspots form a stack within the window of which they are a part. When a hotspot is created, it is placed at the top of the stack. The position of a hotspot in the stack cannot be changed, except by deleting it and creating it again to force it to the top. The locator can only be over one hotspot at one time; if the locator is over a region that is the overlap between two or more hotspots, the locator is considered to be only over the top-most of those hotspots.

Whenever a hotspot is activated with a locator button, the activation only occurs on the downstroke of the button, not the upstroke. The upstroke of that button is never transmitted.

An enter/exit hotspot does not require that the window be the selected window for it to be activated. A button press over a hotspot whose bmask includes that button in a window that is not the selected window will activate the hotspot but will not select the window.

HARDWARE DEPENDENCIES

Series 500:
Hotspot routines (whotspot_∗) are not supported on Series 500; they work only on the Series 300.

DIAGNOSTICS

A return of -1 indicates failure; otherwise the hotspot_id for the created hotspot is returned. See errno(2) for more information.

Hewlett-Packard Company — May 11, 2021

Museum

Related Articles