NAME

ESCAPE -4 − add an input device association

SYNOPSIS

C Syntax

void
pescape ( func_id, in, out )
Pintfunc_id;escape function identifier
Pescapein∗in;input data for the function
Pescapeout∗out;OUT output data of the function

FORTRAN Syntax

SUBROUTINE pesc ( FCTID, LIDR, IDR, MLODR, LODR, ODR )
INTEGERFCTIDfunction identification
INTEGERLIDRdimension of input data record array
CHARACTER∗80IDR(LIDR) input data record
INTEGERMLODRmaximum length of output data record
INTEGERLODROUT number of array elements used in ODR
CHARACTER∗80ODR(MLODR) OUT output data record

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

ESCAPE -4 adds an input device association. 

C Input Parameters

func_id
The function identifier for this escape is PUESC_ADD_DEVICE_ASSOCIATION, which is defined in phigs.h to be -4. 

inA pointer to a Pescapein union containing the input data record, uesc4_idatarec. It is defined as:

typedef struct {
Pintwsid;
Passoc_dev_mastermaster;
Passoc_dev_slaveslave;
} Puesc0004_idatarec;/∗ Add input device association ∗/

wsidThe wsid component specifies the workstation identifier of the workstation with which the master and slave input devices are associated. 

masterThe master component is a Passoc_dev_master structure used to specify the master device with which a slave device is to be associated.  Passoc_dev_master is defined in phigs.h as follows:

typedef struct {
Piclassclass;/∗ device class ∗/
Pintnum;/∗ device number ∗/
union {
Pchoicechoice;
} value;
} Passoc_dev_master;

classThe class component is a Piclass enumerated type specifying the master device class.  Values for Piclass are defined in phigs.h as follows:

PI_NONE
PI_LOCATOR
PI_STROKE
PI_VALUATOR
PI_CHOICE
PI_PICK
PI_STRING

numThe num component specifies the master device number. 

choiceIf the master device class is of type CHOICE, the choice component of the value union is used to control the triggering of the slave device.  Pchoice is defined in phigs.h as follows:

typedef struct {
Pchoicestatusstatus;/∗ status of request ∗/
Pintchoice;/∗ choice value ∗/
} Pchoice;

statusThe status component is an enumerated type which may take on the values PCH_OK or PCH_NOCHOICE. 

choiceIf it is specified as PCH_OK, the associated slave device will be triggered when the operator selects the choice value specified in the choice component.  If it is specified as PCH_NOCHOICE, the associated slave device will be triggered when the operator selects any choice value. 

slaveThe slave component is a Passoc_dev_slave structure used to specify the slave device.  Passoc_dev_slave is defined in phigs.h as follows:

typedef struct {
Piclassclass;/∗ device class ∗/
Pintnum;/∗ device number ∗/
} Passoc_dev_slave;

classThe class component is a Piclass enumerated type specifying the slave device class. 

numThe num component specifies the slave device number. 

C Output Parameters

There is no output data record for this escape. 

FORTRAN Input Parameters

FCTID
The function identifier of this escape is PUESCADDASSOC, which is defined in phigs77.h to be -4. 

LIDR
The dimension of IDR (returned by PACK DATA RECORD). 

IDR(LIDR)
An ESCAPE data record packed by PACK DATA RECORD when called with the following parameters:

ILThe number of integers is either 6 or 7. 

IAContains either six or seven integer values (depending on the device classes involved). 

Element 1 is the workstation identifier of the workstation with which the master and slave input devices are associated. 

Elements 2 and 3 specify the master device with which a slave device is to be associated; element 2 specifies the master device class, and element 3 the master device number.  Device class values are specified in phigs77.h as follows:

PNCLASNone
PLOCATLocator
PSTROKStroke
PVALUAValulator
PCHOICChoice
PPICKPick
PSTRINString

Elements 4 and 5 specify the slave device; element 4 specifies the slave device class, and element 5 the slave device number. 

If the master device class is of type CHOICE, elements 6 and 7 (if needed) are used to control the triggering of the slave device.  Element 6 specifies a choice status, which may be either POK (OK) or PNCHOI (NOCHOICE).  If it is specified as POK, the associated slave device will be triggered when the operator selects the choice value specified in element 7.  If it is specified as PNCHOI, the associated slave device will be triggered when the operator selects any choice value. 

RLThe number of real values = 0. 

SLThe number of strings = 0. 

FORTRAN Output Parameters

There is no output data record for this escape. 

Execution

Selected input devices can have associated with them a set of other devices that will also generate input events when the device is triggered.  An association is made with the Add Input Device Association escape, and removed with the Remove Input Device Association escape.  These functions accept a triggering-device/triggered-device pair. This pair indicates an additional device to trigger (the slave device) when the specified triggering device (the master device) is triggered.  For some devices, separate associations can be made with each possible value of the master device (e.g. choice numbers), in which case selection of that value by the operator will trigger the devices associated with that value.  For example, this allows operator selection of a specific choice value on a specified CHOICE device to also trigger one or more LOCATOR devices. 

When a device and its associated devices are triggered, a set of simultaneous events are generated, one event for each device.  Note that both the master and slave devices must be in event mode for this to take place. 

Device associations are currently only supported for CHOICE devices as the master, and LOCATOR and PICK devices as the slave.  Others can be set and removed but the association will not generate an event. 

SEE ALSO

INITIALIZE CHOICE (3P)
INITIALIZE CHOICE 3 (3P)
INITIALIZE LOCATOR (3P)
INITIALIZE LOCATOR 3 (3P)
INITIALIZE PICK (3P)
INITIALIZE PICK 3 (3P)
ESCAPE -5 (3P)

Sun Release 4.0  —  Last change: 13 July 1989