This section describes the routines that are used by low level graphics software to interact with GWM windows. A working knowledge of Xlib programming is assumed.
The routines described here are for the use of “system” software only and all this information in this section is subject to change without notice. Therefore before making any use of it you should consult the Starlink project staff at RAL.
These return a status value rather than reporting errors; symbolic names for the status values can be
found in gwm_err.h. Note that these are not EMS error codes.
A GWM window consists of the following components:
Various items of information are stored as properties of the window so that any applications which
knows the id of the window can read and write them. The GWM_SetXxxx and GWM_GetXxxx routines
can be used to access them. The properties are:
GWM_background GWM_colour_table GWM_foreground GWM_name GWM_ov_mask GWM_pixmap GWM_x_offset GMW_y_offset GWM_x_ov_offset GWM_y_ov_offset Everything drawn in the window must also be drawn in the pixmap so that the window is refreshed properly. The easiest way to do this is to draw into the pixmap first and then add the x and y offsets to all the absolute coordinates and then draw into the window. The graphics context must have its plane mask set to the value of the overlay mask property (so as to avoid altering the overlay plane) and the foreground set to one of the numbers in the colour table array. If the drawing operation results in anything being drawn with the background colour then the background should also be set to one of the numbers in the colour table array, usually the first.
If the drawing operation involves a large amount of data it may be more efficient to only draw into the
pixmap and then copy the pixmap to the window with XCopyArea. The destination position should be
the x and y offset values and again, the overlay plane must be protected by the plane mask in the
gc.
Drawing in the overlay plane is just the same as drawing into the window except that the plane mask must be set to the complement of the overlay mask property and the foreground and background colours must be all 1s and all 0s respectively1. The overlay offset values must be added to the coordinates when drawing into the window.
On a display with a writeable colour table, the colour table property is a list of the colour cells allocated to the refresh process and must not be altered.
On a display with a fixed colour table the colour table property will list all possible pixel values—since the colour cells can’t be changed they can be used by all windows—and the colour table can be used to map “virtual” pixel values to the real pixel values used to write to the window and may be altered. For example, GKS uses the colour table to map colour indices onto pixel values.
If a window has an overlay plane, the colour of the overlay plane is set by setting the colour cells that correspond to values listed in the colour tables ORed with the bit position of the overlay plane (ie. the complement of the plane mask).
Scrolling of the window and overlay planes is achieved by setting the values of the offset and overlay offset properties. The refresh process is notified of the changes and updates the destination positions it uses when copying the pixmap. However, it does not update the window when the property values change so the application that changes the offsets must copy the window contents to the new position itself.
Some example programs that illustrate how to perform various operations on a GWM
window can be found in the gwm examples directory ($STARLINK_DIR/share/gwm on Starlink
systems).
1Of course in actual fact only the bit that corresponds to the overlay plane matters since the rest are masked by the plane mask but all 1s and all 0s is the easiest value to use