graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPINLC - Initialize Locator

GPINLC (wsid, device, view, pos, echo, area, datalen, data)

Purpose

Use GPINLC to initialize the specified locator device.

The Initialize Locator subroutine stores the initial locator position, initial view index, prompt/echo type, echo area, and locator data record in the workstation state list for the specified device.

Two positions are required for some locator prompt/echo types: the initial locator position, which remains fixed during input operation, and the current locator position, which varies dynamically as you use the locator.

Note:

The locator device must be in Request mode.

Parameters

wsid -- specified by user, fullword integer

Workstation identifier.

device -- specified by user, fullword integer

Locator device number (>=1)

view -- specified by user, fullword integer

Initial view index (>=0)

pos -- specified by user, 3 short floating-point numbers (WC)

Initial locator position.

echo -- specified by user, fullword integer

Prompt/echo type (>=1)

area -- specified by user, 6 short floating-point numbers (DC)

Echo area (Xmin, Xmax, Ymin, Ymax, Zmin, Zmax)

datalen -- specified by user, fullword integer

Data record length.

Note:

The data record length parameter must equal zero (datalen=0) if no data record is required for the given prompt/echo type. For prompt/echo types which require a data record, the specified data record length must be greater than, or equal to, 12.

data -- specified by user, variable length data

Locator data record.

Prompt/echo Types

Type One

designates the current position of the locator using a workstation-dependent technique.

Type Two

the crosshair, designates the current position of the locator by spanning the display surface or device echo area with both a vertical and a horizontal line. The lines intersect at the current locator position. Whether the crosshair spans the entire display surface or only the echo area depends on the capabilities of the workstation.

Type Three

designates the current position of the locator using a tracking cross.

Type Four

designates the current position of the locator using a rubber band line connecting the initial locator position given by this subroutine and the current locator position. If no attributes are specified within the data record, workstation dependent defaults are used.

Type Four requires the following data record:

                   -----------------------------
                 0 |       0 or 1 or 7         | Number of integers
                   |---------------------------|
                 4 |          0 or 1           | Number of reals
                   |---------------------------|
                 8 |            0              | Number of strings
          -------- |---------------------------|
          |     12 | attribute control flag ** | 0=NO ATTRIBUTES SPECIFIED
          |        |                           | 1=ATTRIBUTES SPECIFIED
          |        |---------------------------|----
          |     16 |      linetype ASF*        |   |
          |        |---------------------------|   |1=BUNDLED
          |     20 |linewidth scale factor ASF*|   |2=INDIVIDUAL
  integers|        |---------------------------|   |
          |     24 | polyline color index ASF *|   |
          |        |---------------------------|----
          |     28 |       polyline index *    |<---- Bundle table index
          |        |---------------------------|----                  
          |     32 |       linetype index *    |   |
          |        |---------------------------|   | Individual 
          |     36 |    polyline color index * |   | attribute
          -------- |---------------------------|   | settings  
    real -----> 40 |   linewidth scale factor *|   | 
                   ----------------------------|---- 
 
               *  Polyline Attributes
               Only present if attribute control flag=1
               **  Attribute Control Flag
               Only present if number of integers >0

Type Five

designates the current position of the locator using a rubberband rectangle. The diagonal of the rectangle forms a line connecting the initial locator position given by this subroutine and the current locator position. If no attributes are specified within the data record, workstation dependent defaults are used.

Type Five requires the following data record:

                 ----------------------------
                0|      0 or 1 or 16        | Number of integers
                 |--------------------------|
                4|         0 or 1           | Number of reals
                 |--------------------------|
                8|            0             | Number of strings
            |--- |--------------------------|
            |  12| attribute control flag **| 0=NO ATTRIBUTES SPECIFIED
            |    |                          | 1=ATTRIBUTES SPECIFIED
            |    |--------------------------|---- 
            |  16|    interior style ASF *  |   |
            |    |--------------------------|   |
            |  20|      style index ASF *   |   |
            |    |--------------------------|   |
            |  24|interior color index ASF *|   | 1=BUNDLED
            |    |--------------------------|   | 2=INDIVIDUAL
            |  28|      edge flag ASF *     |   |
            |    |--------------------------|   |
            |  32|    edge linetype ASF *   |   |
            |    |--------------------------|   |
            |  36|  edge color index ASF *  |   |
            |    |--------------------------|   |
            |  40|  edge scale factor ASF * |   |
            |    |--------------------------|---- 
 integers   |  44|     interior index *     |----
            |    |--------------------------|   | Bundle table index
            |  48|       edge index   *     |---- 
            |    |--------------------------|----
            |  52|     interior style  *    |   |
            |    |--------------------------|   |
            |  56|       style index   *    |   |  Individual
            |    |--------------------------|   |  attribute
            |  60|  interior color index *  |   |  settings
            |    |--------------------------|   |
            |  64|       edge flag   *      |   |
            |    |--------------------------|   |
            |  68|     edge linetype  *     |   |
            |    |--------------------------|   |
            |  72|    edge color index  *   |   |
                 |--------------------------|   |
  real ----->  76|   edge scale factor  *   |   |
                 ---------------------------- ---
 
             *  Polygon Attributes
             Only present if attribute control flag=1
             **  Attribute Control Flag
             Only present if number of integers >0

Type Seven

designates the current position of the locator using a specified structure network attached to the tracking cross.

The structure identifier of the root structure to be dragged is specified in the data record and, optionally, the World Coordinate (WC) point on the structure to which the locator is attached. If the attachment point is not specified, the point (0, 0, 0) is used. If for the attachment point, only x, y coordinates are specified, a z coordinate of zero is used. The structure to be dragged must be associated with the workstation before it can be attached to the locator device.

The structure is conceptually dragged in Viewing Coordinate (VC) space, before the view projection is applied. The structure definition may vary while the locator is active. For example, the application may choose to scale the structure as it is dragged using a modeling transformation. The dragged structure network is clipped to the locator device echo area.

Type Seven requires the following data record:

                ----------------------------
             0  |            1             | Number of integers
                |--------------------------|
             4  |       0, 2 or 3          | Number of reals
                |--------------------------|
             8  |            0             | Number of strings
                |--------------------------|
 integer--->12  |   structure identifier   |
          ----- |--------------------------|
          | 16  |      X coordinate  (WC)  |
          |     |--------------------------|
  reals   | 20  |      Y coordinate  (WC)  |
          |     |--------------------------|
          | 24  |      Z coordinate  (WC)  |
          ----- ----------------------------

Error Codes

25: SPECIFIED WORKSTATION DOES NOT EXIST
59: VIEW INDEX VALUE < ZERO
140: DEVICE NUMBER < ONE OR DEVICE NOT AVAILABLE
141: INPUT DEVICE NOT IN CORRECT MODE
144: PROMPT/ECHO TYPE NOT AVAILABLE ON WORKSTATION
145: ECHO AREA BOUNDARY VALUE IN ERROR
146: FIELD IN INPUT DEVICE DATA RECORD IN ERROR
323: VIEW INDEX EXCEEDS VIEW TABLE CAPACITY
324: PROMPT/ECHO TYPE < ONE
501: DATA RECORD WAS NOT SPECIFIED BUT IS REQUIRED
502: FIELD IN DATA RECORD NOT SUPPORTED ON WORKSTATION
509: DATA LENGTH VALUE < ZERO OR REQUIRED LENGTH

Related Subroutines

GPLCMO: Set Locator Mode
GPQDLC: Inquire Default Locator Device Data
GPQDS: Inquire Maximum Display Surface Size
GPQLC: Inquire Locator Device State
GPQLI: Inquire List of Logical Input Devices

RCP code

201335297 (X'0C002201')