A Graphics Window Manager (GWM) widget is a window that conventional (i.e. non-event driven) programs that use Starlink graphics packages (e.g., GKS, SGS, PGPLOT, NCAR, IDI etc.) can use to plot in on X windows displays. GWM is described in SUN/130. The gwm widget makes it possible to integrate GKS and IDI based graphics with user interfaces written in Tcl and Tk. It also has commands for dumping its contents in JPEG, PostScript or LJ250 inkjet format, changing the colour lookup table, clearing the window, scrolling the window and displaying a cross hair that covers full width and height of the window.
The GWM canvas item turns an area of a canvas widget into a GWM window; this provides similar functionality to the GWM widget but also allows other canvas items (lines, polygons, etc.) to be overlayed on the window and therefore graphics from external programs and element created and minipulated by Tk to be mixed.
The gwm command creates a new Tcl command whose name is pathName. The command may then be used to perform various operations on the widget. It has the following general form:
gwm pathName option ?arg arg...?
Option and args determine the exact behaviour of the command.
The following widget commands are possible for gwm widgets:
pathName cget option
Returns the current value of the configuration option given by option. option may have any of the values accepted by the gwm command.
pathName clear
Clear the picture in the widget by setting the entire window to pixel value zero.
pathName configure ?option? ?value option value...?
Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the gwm command.
pathName get colour index
Returns the colour of colour table entry index as a text string in format #RRRRGGGGBBBBB. Index -1 returns the colour of the overlay.
pathName ovclear
Clear the overlay.
pathName print filename
Write the contents of the widget to filename in the format specified by the printformat option. This command returns as soon as the printing has started; the generation of the file continues whenever the Tcl interpreter is idle. When the printing is complete, the global variable specified by the printvar option is set to 1.
pathName set colour index colour
Set the colour of colour table index index to em colour. Index -1 sets the colour of the overlay plane.
pathName set crosshair x_position y_position
Sets the XY position of the crosshair. The values may be in any of the forms acceptable to Tk_GetPixels.
The gwm widget has a command for printing the contents of the gwm window in a number of formats (JPEG, various flavours of PostScript and HP inkjet). The process of generating the file can be quite time consuming for a large window so the print command returns control as soon as the window contents have been captured and the output file created. Actual generation of the file is then carried out whenever the Tcl interpreter is idle enabling the application to continue to respond to X events while the printing is in progress. Completion of the printing process is signaled by a global Tcl variable (gwm_printvar by default) being set to 1.
The simplest way to detect completion is to wait for the value of the variable to change. e.g.:
An alternative approach is to set a trace on the variable so that a procedure is invoked when the print completes. e.g.:
In this example the trace routine merely deletes itself but any other processing can be done here.
Name: background
Class: Background
Command-Line Switch: -background or -bg
Specifies the background colour (colour table entry 0) of the gwm window. Defaults to Black.
Name: colours
Class: Colours
Command-Line Switch: -colours
Specifies the number of colours that the gwm window will attempt to allocate for its colour table. Setting this option after the widget has been created has no effect. Defaults to 64.
Name: crosshair
Class: Crosshair
Command-Line Switch: -crosshair
Specifies whether the cross-hair should be displayed.
Name: crossColour
Class: CrossColour
Command-Line Switch: -crosscolour
Specifies the colour of the crosshair.
Name: cursor
Class: Cursor
Command-Line Switch: -cursor
Specifies the mouse cursor to be used for the widget. The value may have any of the forms acceptable to Tk_GetCursor.
Name: foreground
Class: Foreground
Command-Line Switch: -foreground or -fg
Specifies the foreground colour (colour table entry 1) of the gwm window. Defaults to White.
Name: name
Class: Name
Command-Line Switch: -name or -gwmname
Specifies the name of the gwm window. Setting this option after the widget has been created has no effect. The gwm name is the name used by graphics programs to connect to the window. Defaults to “xwindows”.
Name: height
Class: Height
Command-Line Switch: -height
Specifies the width of the gwm widget. The value is in any of the forms acceptable to Tk_GetPixels. Changing this option after the widget has been created has no effect. Defaults to 512 pixels.
Name: jpegQuality
Class: JpegQuality
Command-Line Switch: -jpegquality
Specifies the quality of the JPEG image in the range 0-100 where 0 is the lowest quality/highest compression and 100 is the highest quality/lowest compression. The normally useful range is 50-95, values above 95 give dramatically increased file size with practically no increase in quality while below 50 the image quality degrades the image quality without much additional compression.
Name: jpegProgressive
Class: JpegProgressive
Command-Line Switch: -jpegprogressive
Specifies a boolean value that determines whether the JPEG image is “progressive”. Progressive images are useful for use on world wide web servers as it allows a browser to display a low quality image quickly and then improve the quality as more data arrives. However not all browsers and other image reading software can interpret progressive JPEGs.
Name: minColours
Class: MinColours
Command-Line Switch: -mincolours
Specifies the minimum number of colours that the gwm window should allocate for its colour table. If fewer than this number of colours are available, the creation of the widget will fail. Changing this option after the widget has been created has no effect. Defaults to 2.
Name: overlay
Class: Overlay
Command-Line Switch: -overlay
Specifies a boolean value that determines whether the gwm window will have an overlay plane. Changing this option after the widget has been created has no effect. Defaults to “no”.
Name: paperWidth
Class: PaperWidth
Command-Line Switch: -paperwidth
Specifies the maximum width of the plot created by the print command. The value is in any of the forms acceptable to Tk_GetPixels. The plot will be the largest size possible that will fit on the paper (after rotation through 90 degrees if necessary) with the same aspect ratio as the gwm window. Defaults to 180mm (a little less than the width of an A4 page).
Name: paperHeight
Class: PaperHeight
Command-Line Switch: -paperheight
Specifies the maximum height of the plot in the same way as paperWidth. Defaults to 250mm (a little less than the height of an A4 page).
Name: printBackground
Class: PrintBackground
Command-Line Switch: printbackground or -printbg
Specifies the colour used for the background of a plot. Any pixel with value zero is plotted in the background colour. Defaults to White.
Name: printFormat
Class: PrintFormat
Command-Line Switch: -printformat
Specifies the format of the file produced by the print command. Valid values are:
Name: printVariable
Class: PrintVariable
Command-Line Switch: -printvariable
Specifies the name of the global variable that is set when a print command has completed. The default is gwm_printvar.
Name: takeFocus
Class: TakeFocus
Command-Line Switch: -takefocus
See the options man page for a description of this option.
Name: width
Class: Width
Command-Line Switch: -width
Specifies the width of the gwm widget. The value is in any of the forms acceptable to Tk_GetPixels. Changing this option after the widget has been created has no effect.
Name: xOffset
Class: XOffset
Command-Line Switch: -xoffset
Specifies by how much the picture is offset from the left hand edge of the window. The value is in any of the forms acceptable to Tk_GetPixels. Positive values shift the picture to the right and negative values shift the picture to the right. The default is zero.
Name: xOvOffset
Class: XOvOffset
Command-Line Switch: -xovoffset
Specifies by how much the overlay is offset from the left hand edge of the window. The value is in any of the forms acceptable to Tk_GetPixels. Positive values shift the picture to the right and negative values shift the picture to the right. The default is zero.
Name: yOffset
Class: YOffset
Command-Line Switch: -yoffset
Specifies by how much the picture is offset from the top edge of the window. The value is in any of the forms acceptable to Tk_GetPixels. Positive values shift the picture to down the screen and negative values shift the picture to up the screen. The default is zero.
Name: yOvOffset
Class: YOvOffset
Command-Line Switch: -yovoffset
Specifies by how much the overlay is offset from the top edge of the window. The value is in any of the forms acceptable to Tk_GetPixels. Positive values shift the picture to down the screen and negative values shift the picture to up the screen. The default is zero.
A gwm widget always uses the colourmap of its parent window; if there are insufficient colourmap entries left (less than minColours) the creation of the widget will fail. In these circumstances, a gwm widget can still be created by creating a frame or top level widget with a new colourmap (with the -colormap new option) and using this as the parent of the gwm widget2.
In the case of a frame with a new colourmap it is also necessary to inform the window manager so that the correct colourmap is installed when the frame receives the input focus with:
wm
colormapwindows
[winfo
toplevel
$w]
$w
where w has been set to the name of the new frame widget.
The same technique can be used to create a gwm widget with a visual type other than the default for the screen being used.
A number of Tk procedures can be found in /star/lib/startcl that may be useful when
using gwm widgets either directly or as examples that can be modified to suit particular
purposes. To use them directly, append /star/lib/startcl to the global variable auto_path,
e.g.:
These procedures make use of a global array called gwm_priv.
gwm_colourDialog w gwm exit
Creates a modeless dialog box with controls for modifying the colours of a gwm widget.
gwm_gwmWithScroll w args
Returns a gwm widget with scroll bars for scrolling the window (and overlay plane if there is one).
gwm_printDialog w gwm
Creates a modal dialog box containing controls for printing a gwm widget.
An gwm server that uses these procedures can be found in /star/bin/startcl/gwm. This is the default server for Starlink systems. It creates a server with buttons for changing the colours, printing the gwm window and clearing the picture and overlay planes. The coordinates of the mouse pointer are also displayed whenever it is over the gwm window. A listing of this script can be found in appendix A.
Arguments for the gwm widget creation command can be supplied on the command line (except -name which is interpreted as an awish option; use -gwmname instead).
To use your own gwm server by default whenever a gwm server is created (either with the xmake
command or automatically by a graphics program), copy /star/bin/startcl/gwmXrefresh
to a directory in your PATH that is positioned before /star/bin/startcl and edit line 13
so that the variable gwmscript is set to the location of suitable script that creates a gwm
widget.
A gwm canvas item is a rectangular area of a canvas widget that has been turned into a gwm window.
The canvas item duplicates much of the functionality of the gwm widget except that:
The important additional functionality that the canvas item offers is the ability to overlay the gwm
picture with other canvas item; since these items can be manipulated through Tcl procedures it is
possible to write programs that enable the user to interact with graphics in a much wider variety of
ways than is possible though GKS or IDI alone. However, any drawing done by an external
program will overwrite any existing canvas items until the window is redrawn by Tk;
the easiest way to force the window to be redrawn is to use the canvas raise or lower
commands (for example, to “lower” the gwm canvas item so that it is underneath all other
items).
Gwm items are created with widget commands of the following form:
pathName create gwm x y option value option value ...
The arguments x and y give the coordinates of the item’s top left hand corner. After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options of the item. The same option-value pairs may be used in itemconfigure widget commands to change the item’s configuration. The following options are supported for gwm items:
-background colour
-bg colour
Specifies the background colour (colour table entry 0) of the gwm window. Defaults to Black.
-colours number
Specifies the number of colours that the gwm window will attempt to allocate for its colour table. Setting this option after the item has been created has no effect. Defaults to 64.
-command number
Specifies the name of the command that is created to clear (erase the picture in) the item and modify the colour table. If no value is specified, no command will be created. Changing this option after the item has been created has no effect.
command
clear
clears the item.
command
set
colour
n
colour
sets colour table entry n to colour.
command
get
colour
n
returns the colour stored in colour table entry n.
-foreground colour
-fg colour
Specifies the foreground colour (colour table entry 1) of the gwm window. Defaults to White.
-gwmname name
-name name
Specifies the name of the gwm window. Setting this option after the item has been created has no effect. The gwm name is the name used by graphics programs to connect to the window. Defaults to “xwindows”.
-height height
Specifies the width of the gwm item. The value is in any of the forms acceptable to Tk_GetPixels. Changing this option after the item has been created has no effect. Defaults to 512 pixels.
-mincolours number
Specifies the minimum number of colours that the gwm window should allocate for its colour table. If fewer than this number of colours are available, the creation of the item will fail. Changing this option after the item has been created has no effect. Defaults to 2.
-tags taglist
Specifies a set of tags to apply to the item. Taglist consists of a list of tag names, which replace any existing tags for the item. Taglist may be an empty list.
-width width
Specifies the width of the gwm item. The value is in any of the forms acceptable to Tk_GetPixels. Changing this option after the item has been created has no effect.
2Some existing graphics programs may attempt to write to the wrong colourmap when used with a gwm widget packed into a frame with a new colourmap and generate an X error. Relinking the program with the latest version of the Starlink software will correct this problem