7. Interactive Graphics

7.1 Introduction

The previous chapters have described how to produce a static graphical image: if the same program is run twice with the same input parameters, the same image will result. An interactive program allows the user to control the behavior of the program with a graphical input device. PGPLOT supports a limited interactive capability on devices with a cursor for graphical input (e.g., Xwindow workstations, some Tektronix terminals and emulators). The capabilities are necessarily limited by the aim to keep PGPLOT device-independent.

7.2 The Cursor

Some of the graphics devices supported by PGPLOT have a graphics cursor. This appears on the view surface as a plus sign, a cross-hair, or a diamond, and can be moved around the view surface with a mouse, joy-stick, or trackball attached to the graphics device. If the hardware does not provide this mechanism, PGPLOT allows the user to move the cursor using the arrow keys on his terminal. See Appendix D for instructions for using the cursor on a specific device.

7.3 Using the Cursor

The basic routines for cursor input are PGCURS and PGBAND. Routine PGCURS enables the cursor on the selected device, positions it at a specified location within the viewport, and allows the user to move it. When the user has positioned the cursor, he types a key on his terminal; PGCURS returns the cursor position (in world coordinates) and the character that was typed. On some devices the user can also click (depress and release) a mouse button. Buttons 1, 2, 3 have the same effect as typing A, D, or X. Routine PGBAND is similar to PGCURS but has additional options that request that a visible line (``rubber band'') or rectangle join the cursor position to a fixed point and track it as it moves. These options are not available on every device that supports a cursor.

In addition, PGPLOT provides three higher-level routines for cursor input: PGOLIN, PGNCUR, and PGLCUR. These three routines require that the device has erase capability.

PGOLIN allows the user to specify a set of points within the viewport, with the capability of correcting mistakes. Interactive commands (single characters [A, D, or X] typed on the keyboard) allow the user to add a point at the current cursor position, delete the last-entered point, or exit from the subroutine. The world-coordinates of the entered points are returned to the calling program. The following program fragment illustrates the use of PGOLIN; the user supplies NPT (up to 50) points with world-coordinates X() and Y(), and the program then shades the polygon defined by these points by calling PGPOLY:

      INTEGER NPT
      REAL X(50), Y(50)
      ...
      WRITE (6,*) 'Use the cursor to draw a polygon'
      WRITE (6,*) 'Type A to add point, D to delete, X to exit'
      NPT = 0
      CALL PGOLIN (50, NPT, X, Y, 0)
      IF (NPT.GE.3) CALL PGPOLY (NPT, X, Y)

PGNCUR is similar to PGOLIN, but the points are sorted into increasing order of x before being returned to the calling program. In addition, the delete command deletes the point nearest to the cursor, rather than the last-entered point. It can be used, for example, to allow the user to supply a set of points to represent the continuum level on a spectrum.

PGLCUR is similar to PGOLIN but instead of using a graph marker to mark each entered point it draws a polyline through them.

7.4 Buffering

By default, PGPLOT ensures that the image seen on the view surface is up to date at all times; that is, each PGPLOT subroutine updates the image before returning control to the calling program. To improve efficiency, PGPLOT can save instructions for controlling the graphics device in a buffer, and only send them to the device when the buffer is filled up. This means that at any given moment, the image displayed on the screen may not be completely up to date. This can be a problem in an interactive program, where, for example, the user has to tell the program what to do next based on his interpretation of the current display. Three PGPLOT routines (PGBBUF, PGEBUF, and PGUPDT) are provided for controlling the buffering of output. All three routines have no arguments.

The routine PGBBUF causes PGPLOT to begin saving graphical output in a buffer. The output is saved until (1) a matching PGEBUF call is made, or (2) the buffer fills up, or (3) the buffer is emptied by a call to PGUPDT, or (4) PGEND is called. The routine PGEBUF stops buffering and causes the buffered commands to be sent to the output device. Calls to PGBBUF and PGEBUF should always be paired. PGBBUF increments an internal counter, while PGEBUF decrements this counter and flushes the buffer to the output device when the counter drops to zero. This allows a subroutine to turn on and turn off buffering without disturbing any buffering that may have been established by the calling program.

Routine PGUPDT empties the buffer created by PGBBUF, but it does not alter the internal counter. The routine should be called when it is essential that the display be completely up-to-date (before interaction with the user, for example) but it is not known if output is being buffered.

Usually output is not buffered; this is the default state established by PGBEG. The default behavior can be changed, however, by defining an environment variable PGPLOT_BUFFER. If this variable is defined, with any value, PGBEG will start buffering output (by calling PGBBUF).

The following example shows how routine PGLAB might be implemented in terms of routine PGMTXT:

      SUBROUTINE PGLAB (XLBL, YLBL, TOPLBL)
      CHARACTER*(*) XLBL, YLBL, TOPLBL
      CALL PGBBUF
      CALL PGMTXT('T', 2.0, 0.5, 0.5, TOPLBL)
      CALL PGMTXT('B', 3.2, 0.5, 0.5, XLBL)
      CALL PGMTXT('L', 2.2, 0.5, 0.5, YLBL)
      CALL PGEBUF
      END

The calls to PGBBUF and PGEBUF ensure that the output generated by the three calls to PGMTXT is buffered (i.e., sent to the output device as a single command instead of three separate ones). If buffering is already enabled by the program which calls PGLAB, the calls to PGBBUF and PGEBUF have no effect.

On some devices (e.g., X-Window workstations) use of buffering can greatly speed up the execution of a program.

Next: Appendix A