X Window Workstations

Author
M. C. Shepherd, 1994.

Supported device
All workstations running the X Window System (Version 11 Release 4 and above) under UNIX, VMS and OpenVMS.

Device type codes

Default device name
The default X display name defined by one's environment.
Under UNIX this is given by the DISPLAY environment variable.
Under VMS it is the device last created with CREATE/DISPLAY.

Device name specification
window@host:display.screen

The device name specifies the X-window display to use, the screen of that display and the PGPLOT window number to use.

The window number is a small integer used to identify individual windows created by PGPLOT. You can either specify the number of an existing inactive window to reuse, or provide a new number to assign to a new window. If the number is omitted or specified as zero, then either the last window to become inactive will be reused, or a new window will be created and assigned the lowest unused window number. The number of each window is displayed in the title of the window.

The host part of the specification is the address of the host on which the display resides. If a DECNET address is used, the host name should be separated from the display number by two colons instead of one.

The display part of the specification is the number of the display server on the given host. Usually this is 0, but if you have multiple X terminals connected to the same machine, then each terminal is generally assigned a different display number.

The screen number is also usually 0, but if your display has multiple screens, then each is identified by a small integer.

For example "2@foo.wherever.edu:0.0/xw" opens PGPLOT window 2 as a /xwindow window on host foo.wherever.edu. Note that the @ symbol is optional if the display name is omitted. Thus "2/xw" opens window 2 on the default display.

Default view surface dimensions
The default geometry of each window is specified in pixels, using the following hierarchy of specifications. Missing details at each level are supplied by those below.
  1. X resource: pgxwin.win#.geometry: WIDTHxHEIGHT+X+Y
  2. X resource: pgxwin.Win.geometry: WIDTHxHEIGHT+X+Y
  3. Environment variable: PGPLOT_XW_WIDTH [fractional display width]
  4. Width=867, height=669 and aspect=8.5/11.
Once displayed, the window can be resized with the mouse, but the drawing area is only resized to reflect this when the next page is started.

Resolution
Depends on monitor.

Color capability
Colormaps of types PseudoColor, StaticColor, GrayScale, StaticGray, and TrueColor are supported. By default, the first available colormap from one of the following lists is used. Thus, where possible a read/write colormap is chosen. This allows color representation changes via PGCTAB, PGSCR and PGSHLS to be applied immediately to previously drawn graphics, which makes it possible to interactively fiddle the colors when used in conjunction with PGBAND.

If the first available colormap type happens to match that of the default colormap of the screen, and enough colors are available therein, then that colormap is used. Otherwise, allocation of a private colormap is attempted. If this fails, the device is treated as monochrome. The default color-map type can be overriden via the pgxwin.Win.visual resource described below. However, if the requested colormap type is not available, the driver reverts to its default colormap search strategy.

By default the driver tries to allocate 100 colors. This number usually makes it possible to have two windows displayed simultaneously without having to allocate a private colormap. This helps to avoid colormap flashing as the pointer is moved between windows. You can override this default with a number in the range 2 to 255 by using the pgxwin.Win.maxColors X resource.

Input capability
The cursor is usually controlled by a mouse. Cursor input is achieved by moving the cursor into the window, and pressing either a mouse button or a keyboard key to select a given position in the window and return a key value. The mouse buttons are mapped to return characters A, D, and X. The cursor can also be moved horizontally and vertically with the keyboard arrow keys: each keystroke moves the cursor by one pixel, or 10 pixels if the SHIFT key is depressed. Rubber-banding is supported: see routine PGBAND. With Click-to-focus window managers you may have to explicitly click on the window to enable keyboard input in the PGPLOT window.

X resources
The following optional X window resources can be used to specify configuration options. On POSIX-compliant systems, these should be placed in a file called .Xdefaults in your home directory. Under VMS they should be placed in DECW$USER_DEFAULTS:DECW$XDEFAULTS.DAT. Note that by default DECW$USER_DEFAULTS is defined as SYS$LOGIN. Resource specification is discussed further in the "Potential problems" section further below.

The following resource descriptions show how a resource line should be constructed in one's resource file. Where default values are available they are indicated. Otherwise the value is indicated symbolically and instructions are given for substituting appropriate values.

pgxwin.Win.geometry: WIDTHxHEIGHT+X+Y
This specifies the size and position of a window in pixels. Any of the above components can be omitted. The X and Y values specify the position of the top left corner of the window wrt the top left corner of the screen, if positive, or the bottom right corner wrt the bottom right corner, if negative.

pgxwin.Win.iconGeometry: +X+Y
This specifies the position of the iconized form of a window, in pixels. The X and Y values specify the position of the top left corner of the window wrt the top left corner of the screen, if positive, or the bottom right corner wrt the bottom right corner, if negative.

pgxwin.Win.acceptQuit: False
Most window managers provide a way for the user to destroy a window using the mouse, often via an option in a pull down menu. By default PGPLOT takes steps to ignore this action when a window is actually being used by a PGPLOT program. To re-enable it, set:
pgxwin.Win.acceptQuit: True

pgxwin.Win.iconize: False
By default, PGPLOT /XSERVE windows remain mapped when PGEND is called or when the program is terminated. If instead you wish the window to be iconized until opened by a new PGPLOT program, set:
pgxwin.Win.iconize: True

pgxwin.Win.maxColors: 100
This specifies the maximum number of colors that PGPLOT tries to allocate for each X window. Reducing the number of colors allocated makes it more likely that each window will share the same colormap and thus stop ``colormap flashing''. Note that the value of the maxColors option must not be less than that of the minColors resource described below.

pgxwin.Win.minColors: 16
To reject colormaps with fewer than a given number of color entries, specify the minimum number of colors required.

pgxwin.Win.visual: default
If you have a preference for the type of colormap to use, specify the name of the preferred type. PGPLOT will then try that type first. The following type names are recognized:
  • default - Use the colormap search strategy described in the "Color Capability" section.
  • monochrome - Use black and white.
  • PseudoColor - Read/write color visual.
  • DirectColor - (This is treated as an alias for TrueColor).
  • StaticColor - Read-only color visual.
  • TrueColor - Read-only color visual (3 primary colortables).
  • GrayScale - Read/write gray-scale visual.
  • StaticGray - Read-only gray-scale visual.

pgxwin.Win.crosshair: False
To augment the default active PGPLOT cursor with cross hairs, set:
pgxwin.Win.crosshair: True

pgxwin.server.visible: True
To hide the PGPLOT server window set
pgxwin.server.visible: False

pgxwin.server.iconGeometry: +X+Y
This specifies the position of the server window icon on the X display, in display pixels. The X and Y values specify the position of the top left corner of the window wrt the top left corner of the screen, if positive, or the bottom right corner wrt the bottom right corner, if negative.
Note that resource specifications that start with pgxwin.Win apply to all PGPLOT /xwindow and /xserve windows. To target options at specific windows, replace the Win component of the specification with win#, where # is the number of the PGPLOT window. For example:
   pgxwin.Win.crosshair:       True
   pgxwin.win2.crosshair:      False
stipulates that all windows except PGPLOT window 2 will use a crosshair for the default cursor. Note that Win is spelt with an upper case initial 'W', whereas win# is spelt with an initial lower-case 'w'. This is important because all resource names are case sensitive.

A better example of the utility of targeting options at specific windows is the following: 

   pgxwin.Win.geometry:        500x500+600+360
   pgxwin.win1.geometry:       500x500+600+33
This example places the first PGPLOT window in one position on the display, and all other windows in a second location - thus avoiding obscuring the first by the second etc..

Similarly if one wanted to dedicate one window to line graphics, one could designate a specific window number to have a reduced number of colors. 

   pgxwin.win10.maxColors:     16
This window would then be selected using a device specification of "10/xserve".

The /XWINDOW and /XSERVE window server (pgxwin_server).
All PGPLOT /xwindow and /xserve windows on a single display are created and maintained by a separate server program called pgxwin_server. If PGPLOT has been installed correctly then this program is automatically started by the /xw and /xs driver when first called upon. pgxwin_server then continues to serve windows to subsequent PGPLOT programs and remains running indefinitely. In order that it be possible to kill the server, an icon window for it is displayed. Window managers generally provide a way to interactively kill windows, and if this is applied to the server window, then the server will close any inactive /xserve windows, and if no active /xw or /xs windows remain, then the server will shut itself down cleanly. Note that inactive windows are distinguishable from active windows by the appearance of a skull-and-crossbones cursor.

If pgxwin_server fails to start automatically, see the "Potential problems" section below on how to remedy this. However, if for some reason it is necessary to run pgxwin_server manually, you'll need to know the following. In particular, under VMS, before you can run the server you will first need to register it as a foreign command, by typing: 

pgxwin_server:=="$directory_name:pgxwin_server.exe"
If your default display is correctly set then simply typing: 
pgxwin_server
with no arguments should start the server, and the server icon should appear on the display. If an alternate display is desired then the default display can be overridden with the -display argument. Other options to override selected X resources from the command-line are also available. To see them type: 
pgxwin_server -help

Potential problems.
The server fails to start.
If the server fails to start automatically then this means that the /xw and /xs driver was unable to find the pgxwin_server executable. It first looks in the directory specified in your PGPLOT_DIR environment variable (or LOGICAL PGPLOT_DIR variable under VMS). Under UNIX, if it fails to find the executable there, it then looks for the executable in each component directory cited in your PATH environment variable. To fix the problem, first determine where the person who compiled PGPLOT installed pgxwin_server and then either place this directory name in your PGPLOT_DIR variable or, under UNIX, add it to your PATH.

If you are still unable to get the server to start automatically, please send me Email at mcs@astro.caltech.edu. In the meantime, you can work around the problem by starting the server by hand, as described previously.

X resource options are ignored.
First check check both the spelling and case of your resource names. Resource names are case sensitive and must appear exactly as indicated above.

The X resource database is compiled by the pgxwin_server program when it is started. Resources set after it has been started are ignored and pgxwin_server will need to be restarted before they are acquired. There are a number of places in which the server can find resources, and your specifications will not be seen if they appear in the wrong place. pgxwin_server attempts to follow the rules laid down by the X Toolkit. First it looks for a RESOURCE_MANAGER property on the root window of your display. This contains a list of resource names and values and comes into being when the standard xrdb program is applied to a resource file. It is common for xrdb to be applied automatically to your Xdefaults file, or to a system supplied xdefaults file when the X server is first started. If this is the case then changes to your Xdefaults file will be ignored until the server is restarted or you explicitly re-run the xrdb command.

If - and only if - the RESOURCE_MANAGER property does not exist, then under UNIX pgxwin_server looks for a file called .Xdefaults in your home directory, and under VMS it looks for a file called DECW$USER_DEFAULTS:DECW$XDEFAULTS.DAT. If it finds this file, it initializes its resource database from it. It then also looks to see if the XENVIRONMENT environment variable contains a valid file name and if so reads resources from that file, overriding any contrasting resources from your Xdefaults file.

To be sure that changes to resources in your Xdefaults are seen by pgxwin_server you should use the xrdb command to install them on the display:

UNIX: 
 (cd;xrdb .Xdefaults)

VMS: 
 $ xrdb -nocpp decw$user_defaults:decw$xdefaults.dat
If the xrdb command is not defined on your system, then first execute: 
 $ @DECW$UTILS:DECW$DEFINE_UTILS.COM

Then terminate pgxwin_server by quiting its icon and ask for /xw or /xs again to restart it.