[ Previous | Next | Contents | Glossary | Home | Search ]
The graPHIGS Programming Interface: ISO PHIGS Subroutine Reference

Chapter 10. Input Subroutines

Input subroutines allow users to supply input to your application. There are six logical input device classes: locator, stroke, valuator, choice, pick, and string. There are three modes of interaction with the input devices: sample, request, and event.

The subroutines discussed in this section perform the following operations:

To determine the actual input capabilities of a specific workstation, use the appropriate inquiry subroutines.

The measure and trigger of each logical input device is described in terms of the physical devices available on a workstation. See The graPHIGS Programming Interface: Technical Reference for the details of each logical device supported on a workstation

The default size of the input queue is 16K. You can control this size with the IQSIZE default, which is explained in the The graPHIGS Programming Interface: Technical Reference.

The input queue elements all have a header of 16 bytes. Use the information supplied in Appendix B of The graPHIGS Programming Interface: Technical Reference to interpret the information after the header.

AWAIT EVENT (PHOP,WSOP,*,*)

Purpose

Use Await Event to move the next event from the input queue into the current event report. If the input queue is empty, then the graPHIGS API is placed in a wait state until at least one of the following occurs:

  1. The application adds an event to the input queue.

  2. The time specified in the timeout parameter has elapsed. If the timeout parameter specifies a value of zero or less, then no wait takes place. If the timeout parameter specifies a value greater than zero, then a wait takes place for the specified time interval. The maximum time interval is 55,800 seconds (15.5 hours).

    The graPHIGS API uses the operating system's timing facility. (See The graPHIGS Programming Interface: Writing Applications).

    When a timeout or error situation occurs, the graPHIGS API returns NONE for the input class parameter. Otherwise, the graPHIGS API returns the workstation identifier, input class, and the logical device number. Input classes include: LOCATOR, STROKE, VALUATOR, CHOICE, PICK, and STRING.

    The application must use the appropriate "Get" subroutine call to obtain the value(s) of the input residing in the current event report (i.e., Get Choice, Get Locator 3, Get String).

    Language Bindings

    3. C

    pawait_event (timeout, ws_id, dev_class, in_num)

    Input Parameters

    Pfloat timeout
    Timeout interval in seconds.

    Output Parameters

    Pint *ws_id
    Workstation identifier.

    Pin_class *dev_class
    Input device class (0=PIN_NONE, 1=PIN_LOC, 2=PIN_STROKE, 3=PIN_VAL, 4=PIN_CHOICE, 5=PIN_PICK, 6=PIN_STRING).

    Pint *in_num
    Logical input device number.

    FORTRAN

    PWAIT (tout, wkid, icl, idnr)

    Input Parameters

    real tout
    Timeout interval in seconds.

    Output Parameters

    integer wkid
    Workstation identifier.

    integer icl
    Input device class (0=PNCLAS, 1=PLOCAT, 2=PSTROK, 3=PVALUA, 4=PCHOIC, 5=PPICK, 6=PSTRIN).

    integer idnr
    Logical input device number.

    Errors

    3
    Function Requires State (PHOP,WSOP,*,*)
    256
    Warning, Input Queue Has Overflowed

    Note:

    The graPHIGS API performs this operation even if error 256 occurs.

    Related Subroutines

  3. Flush Device Events

  4. Get Choice

  5. Get Locator

  6. Get Locator 3

  7. Get Pick

  8. Get String

  9. Get Stroke

  10. Get Stroke 3

  11. Get Valuator

  12. Inquire Input Queue Overflow

  13. Inquire More Simultaneous Events

  14. Set Choice Mode

  15. Set Locator Mode

  16. Set Pick Mode

  17. Set String Mode

  18. Set Stroke Mode

  19. Set Valuator Mode

    20. [ Previous | Next | Contents | Glossary | Home | Search ]