Library description

BUTTON depends on PGPLOT
Plotting settings
Using BUTTON
A sample program

BUTTON depends on PGPLOT

The BUTTON library has been built based on the graphic subroutine package PGPLOT. In fact, the PGPLOT subroutine
PGBAND(MODE,POSN,XREF,YREF,XC,YC,CH)
is the nucleus of the BUTTON system. This subroutine, which governs the utilization of a mouse device, returns the cursor position (XC,YC) in world coordinates, and the character (CH) typed by the user on the keyboard or mouse button clicked (a three button mouse returns CH='A' --left button--, CH='D' --middle button--, CH='X' --right button--).

BUTTON routines are completely compatible with the PGPLOT routines, exception made for PGBEGIN, which must be replaced by its BUTTON version RPGBEGIN. Other PGPLOT routines, like PGENV, PGBAND, and PGERAS are not recommended, and their counterparts RPGENV, RPGBAND and RPGERAS (RPGERASB and RPGERASW) should be employed instead. The convention employed to name these BUTTON routines is similar to that used in PGPLOT, although an extra 'R' character has been added at the beginning of the each routine name to facilitate the distinction with the PGPLOT routines.

Another set of additional BUTTON routines (IFBUTTON, BUTTON, BUTTQBR, ..., BUTTSYTEXT) allow button manipulation, plotting the buttons in different modes and detecting their selection.

Plotting settings

The appearance of buttons and plots using BUTTON depend on the values of a set of environment variables (all of them declared in the file button.inc). These variables govern the size and location of buttons and plots, and can be changed at running time in a straightforward way by performing calls to subroutines.

The following table shows a list of the environment variables, together with a short description, their defaults values (established in the initial call to the routine RPGBEGIN), and the routines employed to query and set their current values.

variable	default value	description	query routine	set routine
`MAX_XBUTT`	6	number of buttons in the x direction	`BUTTQXB`	`BUTTSXB`
`MAX_YBUTT`	2	number of buttons in the y direction	`BUTTQYB`	`BUTTSYB`
`PGSCF_BUTT`	2	PGPLOT font type for text in buttons	`BUTTQCF`	`BUTTSCF`
`PGSCH_BUTT`	1.0	PGPLOT font size for text in buttons	`BUTTQCH`	`BUTTSCH`
`YTEXT_BUTT`	0.35	relative y-position of the text baseline in buttons	`BUTTQYTEXT`	`BUTTSYTEXT`
`ITICKS_BUTT`	.FALSE.	if .TRUE. invert the tick marks (draw them outside the plot instead of inside)	`BUTTQIT`	`BUTTSIT`
`X1VPORT`	0.10	x-coordinate of the left hand edge of the plot region (in normalized device coordinates, which run from 0 to 1)	`BUTTQPR`	`BUTTSPR`
`X2VPORT`	0.95	x-coordinate of the right hand edge of the plot region	`BUTTQPR`	`BUTTSPR`
`Y1VPORT`	0.10	y-coordinate of the bottom edge of the plot region	`BUTTQPR`	`BUTTSPR`
`Y2VPORT`	0.70	y-coordinate of the top edge of the plot region	`BUTTQPR`	`BUTTSPR`
`X3VPORT`	0.05	x-coordinate of the left hand edge of the button region	`BUTTQBR`	`BUTTSBR`
`X4VPORT`	0.95	x-coordinate of the right hand edge of the button region	`BUTTQBR`	`BUTTSBR`
`Y3VPORT`	0.80	y-coordinate of the bottom edge of the button region	`BUTTQBR`	`BUTTSBR`
`Y4VPORT`	0.95	y-coordinate of the top edge of the button region	`BUTTQBR`	`BUTTSBR`

Using BUTTON

With these default values, the aspect of the plot and button regions is that shown in the following diagram:

button and plot regions

Any call to RPGENV will produce a graph in the plot region. The button area is divided into MAX_XBUTT columns and MAX_YBUTT rows of buttons, which define MAX_XBUTT x MAX_XBUTT possible buttons. The maximum number of buttons is limited to 1000 (although this limit can be modified by varying the parameter MAX_NBUTT in the file button.inc.

In practice, any program that will made use of these buttons, must contain and initial call to the subroutine RPGBEGIN, which determines the number of simultaneous output devices to be employed, and sets the default values of the environment variables. After this inicial call, all the PGPLOT routines (exception made for PGBEGIN) can be employed, in addition to those of BUTTON.

Each button is identified with a number, corresponding to their position on the grid of MAX_XBUTT x MAX_XBUTT possible buttons. Calls to the subroutine BUTTON will display/erase buttons in different modes. The detection of a selected button by the program user is performed with a call to a couple of subroutines:

       CALL RPGBAND(MODE,POSN,XREF,YREF,XC,YC,CH)
       CALL IFBUTTON(XC,YC,NB)

As we explained previously, RPGBAND return the current cursor position (XC,YC) and the pressed mouse button (CH). IFBUTTON determines whether the cursor location corresponds to an activated button. If this is the case, NB returns with the number corresponding to the selected button, or cero if the cursor is not located on any button.

NOTE: since the subroutine RPGERAS only clears the plot region, if labels are drawn outside this region, they are not cleared. In this case it is more convenient to use the subroutine RPGERASW (see sample program).

A sample program

The sample program sample.f, included in the distribution file, shows some of the capabilities of the BUTTON library. Note that this program also incorporates an algorithm to handle, simultaneously, different graphic output devices. However, it is important to note that, if more than one single graphic device is going to be employed, buttons (in this sample program) will only be displayed in the first selected graphic device.

Buttons can be employed graphically or in text mode.

Graphic buttons

% sample
Are you using graphic buttons............(y/n) [y] ? y
Graphic device #1 (? to see list) [/XSERVE] ? /XSERVE
Graphic device #2 (NONE=EXIT) (? to see list) [NONE] ? NONE
        .
        .
        .
        .
Press [CR] to EXIT

Text buttons

In this case, buttons appear in the terminal (VT type), instead that in the graphic output device. If MAX_XBUTT=6, which is the default value, it is necessary to change the terminal width to 132 characters per line.

% sample
Are you using graphic buttons............(y/n) [y] ? n
Do you want to plot the buttons anyway...(y/n) [y] ? n
Graphic device #1 (? to see list) [/XSERVE] ? /XSERVE
Graphic device #2 (NONE=EXIT) (? to see list) [NONE] ? NONE
 
Are you pressing a button (y/n) [y] ? y
Button number [0] ? 1
        .
        .
        .
        .
Are you pressing a button (y/n) [y] ? y
Button number [0] ? 6
 
Press [CR] to EXIT