Provided by: libxgks-dev_2.6.1+dfsg.2-2_amd64 
NAME
XGKS - A GKS library for the X Window System
SYNOPSIS
#include <xgks.h>
Gint gopenws (Gint wsid, Gchar *connection, Gchar *ws_type);
Gint gclosews (Gint wsid);
Gint gclearws (Gint wsid, Gclrflag control_flag);
Gint gopengks (Gfile *err_file, Glong memory);
Gint gclosegks (void);
Gint gsetasf (Gasfs *asf);
Gint gsetcolorrep (Gint wsid, Gint idx, Gcobundl *rep);
Gint ginqcolorrep (Gint wsid, Gint idx, Gqtype type, Gcobundl *rep);
Gint ginqcolorindices (Gint wsid, Gintlist *indices);
Gint ginqcolorfacil (Gchar *ws_type, Gcofac *fac);
Gint ginqpredcolorrep (Gchar *ws_type, Gint index, Gcobundl *rep);
Gint gactivatews (Gint wsid);
Gint gdeactivatews (Gint wsid);
Gint gsetwindow (Gint trans, Glimit *window);
Gint gsetviewport (Gint trans, Glimit *viewport);
Gint gsetviewportinputpri (Gint trans, Gint ref_trans, Gvpri priority);
Gint gselntran (Gint trans);
Gint gsetclip (Gclip ind);
Gint gsetwswindow (Gint wsid, Glimit *window);
Gint gsetwsviewport (Gint wsid, Glimit *viewport);
Gint gevaltran (Gpoint *ppoint, Gpoint *pshift, Gfloat angle, Gpoint *pscale, Gcsw coord,
Gfloat result[2][3]);
Gint gaccumtran (Gfloat segtran[2][3], Gpoint *ppoint, Gpoint *pshift, Gfloat angle,
Gpoint *pscale, Gcsw coord, Gfloat result[2][3]);
Gint gemergencyclosegks (void);
Gint gerrorhand (Gint errnum, Gchar *funcname, Gfile *perrfile);
Gint gerrorlog (Gint errnum, Gchar *funcname, Gfile *perrfile);
Gint gpolyline (Gint num_pts, Gpoint *pts);
Gint gsetlineind (Gint idx);
Gint gsetlinetype (Gint type);
Gint gsetlinewidth (Gfloat width);
Gint gsetlinecolorind (Gint idx);
Gint gsetlinerep (Gint wsid, Gint idx, Glnbundl *rep);
Gint gcreateseg (Gint name);
Gint gcloseseg (void);
Gint grenameseg (Gint old, Gint new);
Gint gdelseg (Gint name);
Gint gdelsegws (Gint wsid, Gint name);
Gint gsetsegattr (Gint name, Gsegattr *segattr);
Gint gsetpickid (Gint pick_id);
Gint gassocsegws (Gint wsid, Gint seg_id);
Gint gcopysegws (Gint wsid, Gint seg_id);
Gint ginsertseg (Gint seg_id, Gfloat segtran[2][3]);
Gint gredrawsegws (Gint wsid);
Gint ginqmodsegattr (Gchar *ws_type, Gmodseg *dyn);
Gint ginqnameopenseg (Gint *seg);
Gint ginqsegattr (Gsegattr *segattr);
Gint ginqassocws (Gint seg, Gintlist *asswk);
Gint ginqsegnames (Gintlist *segs);
Gint ginqsegnamesws (Gint wsid, Gintlist *segs);
Gint ginqnumsegpri (Gchar *ws_type, Gint *numpri);
Gint ginqcurpickid (Gint *pickid);
Gint gpolymarker (Gint num_pts, Gpoint *pts);
Gint gsetmarkersize (Gfloat size);
Gint gsetmarkertype (Gint type);
Gint gsetmarkercolorind (Gint color);
Gint gsetmarkerind (Gint idx);
Gint gsetmarkerrep (Gint wsid, Gint idx, Gmkbundl *rep);
Gint gfillarea (Gint num_pts, Gpoint *pts);
Gint gsetfillcolorind (Gint color);
Gint gsetfillind (Gint idx);
Gint gsetfillintstyle (Gflinter style);
Gint gsetfillrep (Gint wsid, Gint idx, Gflbundl *rep);
Gint gsetfillstyleind (Gint idx);
Gint gsetpatrep (Gint wsid, Gint idx, Gptbundl *rep);
Gint gcellarray (Grect *rect, Gipoint *dim, Gint row, Gint *color);
Gint ginitloc (Gint wsid, Gint dev, Gloc *init, Gint pet, Glimit *area, Glocrec *record);
Gint gsetlocmode (Gint wsid, Gint dev, Gimode mode, Gesw echo);
Gint greqloc (Gint wsid, Gint dev, Gqloc *response);
Gint gsampleloc (Gint wsid, Gint dev, Gloc *response);
Gint ginqlocst (Gint wsid, Gint dev, Gqtype type, Glocst *state);
Gint ginqdefloc (Gchar *type, Gint dev, Gdefloc *data);
Gint gawaitevent (Gfloat timeout, Gevent *event);
Gint gflushevents (Gint wsid, Giclass class, Gint dev);
Gint ginqinputoverflow (Gqueue *overflow);
Gint ginqmoreevents (Gsimultev *events);
Gint ggetloc (Gloc *response);
Gint ggetstroke (Gstroke *response);
Gint ggetchoice (Gchoice *response);
Gint ggetpick (Gpick *response);
Gint ggetval (Gfloat *response);
Gint ggetstring (Gchar *response);
Gint gupdatews (Gint wsid, Gregen regenflag);
Gint gsetcharexpan (Gfloat expansion);
Gint gsetcharheight (Gfloat height);
Gint gsetcharspace (Gfloat spacing);
Gint gsetcharup (Gpoint *up_vector);
Gint gsettextalign (Gtxalign *txalign);
Gint gsettextcolorind (Gint color);
Gint gsettextfontprec (Gtxfp *txfp);
Gint gsettextind (Gint idx);
Gint gsettextpath (Gtxpath path);
Gint gsettextrep (Gint wsid, Gint idx, Gtxbundl *bundle);
Gint gtext (Gpoint *at, Gchar *string);
Gint ginqtextextent (Gint wsid, Gpoint position, Gchar *string, Gextent *extent);
Gint gsetdeferst (Gint wsid, Gdefmode deferral_mode, Girgmode regen_mode);
Gint ginitchoice (Gint wsid, Gint dev, Gchoice *init, Gint pet, Glimit *area, Gchoicerec
*record);
Gint gsetchoicemode (Gint wsid, Gint dev, Gimode mode, Gesw echo);
Gint greqchoice (Gint wsid, Gint dev, Gchoice *response);
Gint gsamplechoice (Gint wsid, Gint dev, Gchoice *response);
Gint ginqchoicest (Gint wsid, Gint dev, Gchoicest *state);
Gint ginqdefchoice (Gchar *type, Gint dev, Gdefchoice *data);
Gint ginitpick (Gint wsid, Gint dev, Gpick *init, Gint pet, Glimit *area, Gpickrec
*record);
Gint gsetpickmode (Gint wsid, Gint dev, Gimode mode, Gesw echo);
Gint greqpick (Gint wsid, Gint dev, Gpick *response);
Gint gsamplepick (Gint wsid, Gint dev, Gpick *response);
Gint ginqpickst (Gint wsid, Gint dev, Gqtype type, Gpickst *state);
Gint ginqdefpick (Gchar *type, Gint dev, Gdefpick *data);
Gint ginitval (Gint wsid, Gint dev, Gfloat init, Gint pet, Glimit *area, Gvalrec *record);
Gint gsetvalmode (Gint wsid, Gint dev, Gimode mode, Gesw echo);
Gint greqval (Gint wsid, Gint dev, Gqval *response);
Gint gsampleval (Gint wsid, Gint dev, Gfloat *response);
Gint ginqvalst (Gint wsid, Gint dev, Gvalst *state);
Gint ginqdefval (Gchar *type, Gint dev, Gdefval *data);
Gint ginitstring (Gint wsid, Gint dev, Gchar *init, Gint pet, Glimit *area, Gstringrec
*record);
Gint gsetstringmode (Gint wsid, Gint dev, Gimode mode, Gesw echo);
Gint greqstring (Gint wsid, Gint dev, Gqstring *response);
Gint gsamplestring (Gint wsid, Gint dev, Gchar *response);
Gint ginqstringst (Gint wsid, Gint dev, Gstringst *state);
Gint ginqdefstring (Gchar *type, Gint dev, Gdefstring *data);
Gint ginitstroke (Gint wsid, Gint dev, Gstroke *init, Gint pet, Glimit *area, Gstrokerec
*record);
Gint gsetstrokemode (Gint wsid, Gint dev, Gimode mode, Gesw echo);
Gint greqstroke (Gint wsid, Gint dev, Gqstroke *response);
Gint gsamplestroke (Gint wsid, Gint dev, Gstroke *response);
Gint ginqstrokest (Gint wsid, Gint dev, Gqtype type, Gstrokest *state);
Gint ginqdefstroke (Gchar *type, Gint dev, Gdefstroke *data);
Gint ginqlinefacil (Gchar *ws_type, Glnfac *fac);
Gint ginqpredlinerep (Gchar *ws_type, Gint idx, Glnbundl *rep);
Gint ginqlineindices (Gint wsid, Gintlist *idxlist);
Gint ginqlinerep (Gint wsid, Gint idx, Gqtype type, Glnbundl *rep);
Gint ginqmarkerfacil (Gchar *ws_type, Gmkfac *fac);
Gint ginqpredmarkerrep (Gchar *ws_type, Gint idx, Gmkbundl *rep);
Gint ginqmarkerindices (Gint wsid, Gintlist *idxlist);
Gint ginqmarkerrep (Gint wsid, Gint idx, Gqtype type, Gmkbundl *rep);
Gint ginqfillfacil (Gchar *ws_type, Gflfac *fac);
Gint ginqpredfillrep (Gchar *ws_type, Gint idx, Gflbundl *rep);
Gint ginqfillindices (Gint wsid, Gintlist *idxlist);
Gint ginqfillrep (Gint wsid, Gint idx, Gqtype type, Gflbundl *rep);
Gint ginqpatfacil (Gchar *ws_type, Gint *fac);
Gint ginqpredpatrep (Gchar *ws_type, Gint idx, Gptbundl *rep);
Gint ginqpatindices (Gint wsid, Gintlist *idxlist);
Gint ginqpatrep (Gint wsid, Gint idx, Gqtype type, Gptbundl *rep);
Gint gmessage (Gint wsid, Gchar *string);
Gint gescinqxattr (Gint wsid, Display **dpy, Window *win, GC *gc);
void gescsetbackingstore (Gint wsid, Gint i);
void gescsetprogname (char *name);
Gint gescsetcolormask (Gint wsid, unsigned long mask);
Gint gescsetdcsize (Gint wsid, Gpoint size);
Gint gescstoreprimi (Gint wsid, Gstore store);
Gint gescredrawnotify (Gint wsid, Gint (*funcp)(Gint wsid, typedef enum Gredraw who));
Gint ginqtextfacil (Gchar *ws_type, Gtxfac *fac);
Gint ginqpredtextrep (Gchar *ws_type, Gint idx, Gtxbundl *rep);
Gint ginqtextindices (Gint wsid, Gintlist *idxlist);
Gint ginqtextrep (Gint wsid, Gint idx, Gqtype type, Gtxbundl *rep);
Gint ginqavailwstypes (Gstrlist *wstypes);
Gint ginqdisplayspacesize (Gchar *ws_type, Gdspsize *dspsz);
Gint ginqwscategory (Gchar *ws_type, Gwscat *cat);
Gint ginqwsclass (Gchar *ws_type, Gwsclass *class);
Gint ginqmodwsattr (Gchar *ws_type, Gmodws *dyn);
Gint ginqdefdeferst (Gchar *ws_type, Gdefer *def);
Gint ginqmaxwssttables (Gchar *ws_type, Gwstables *tables);
Gint ginqnumavailinput (Gchar *ws_type, Gnumdev *num);
Gint ginqwsconntype (Gint wsid, Gwsct *ct);
Gint ginqwsst (Gint wsid, Gwsstate *state);
Gint ginqwsdeferupdatest (Gint wsid, Gwsdus *du);
Gint ginqopst (Gos *state);
Gint ginqlevelgks (Glevel *lev);
Gint ginqwsmaxnum (Gwsmax *maxws);
Gint ginqopenws (Gintlist *wsids);
Gint ginqactivews (Gintlist *wsids);
Gint ginqprimattr (Gpriattr *primattr);
Gint ginqindivattr (Gindattr *indivattr);
Gint ginqcurntrannum (Gint *tran);
Gint ginqntrannum (Gintlist *tranlist);
Gint ginqntran (Gint num, Gwstran *tran);
Gint ginqclip (Gcliprec *clipping);
Gint ginqmaxntrannum (Gint *maxtran);
Gint ginqwstran (Gint wsid, Gwsti *wstran);
Gint ginqpixelarraydim (Gint wsid, Grect *rect, Gipoint *dim);
Gint ginqpixelarray (Gint wsid, Gpoint *point, Gipoint *dimen, Gpxarray *pxarr);
Gint ginqpixel (Gint wsid, Gpoint *ppoint, Gint *pix);
Gint gwritegksm (Gint wsid, Gint type, Gint length, Gchar *data);
Gint ggetgksm (Gint wsid, Ggksmit *result);
Gint greadgksm (Gint wsid, Gint length, Gchar *record);
Gint ginterpret (Ggksmit *recInfo, Gchar *data);
DESCRIPTION
XGKS is an implementation of the ANSI Graphical Kernel System for use with the X Window
System. XGKS was developed at the University of Illinois, Urbana, Illinois, and supported
by IBM ACIS. After being made freely available in the X11R4 distribution, XGKS was
adopted by the Unidata Program Center (UPC) of the University Corporation for Atmospheric
Research (UCAR) in Boulder, Colorado.
STANDARDS
XGKS is an implementation of the ANSI Graphical Kernel System as defined by the
functional description and the draft 1988 C language binding. Thus, the ultimate
reference for any programmer is the C binding manual which details the data types and
functions available. XGKS is a level 2C implementation of the GKS specification.
It supports REQUEST, SAMPLE, and EVENT input modes for all six logical input devices,
workstation independent segment storage, and metafiles.
CAPABILITIES
The XGKS library supports all functions specified by the ANSI standard with the
exception of :
ESCAPE (in its most general form)
GENERALIZED DRAWING PRIMITIVE (in its most general form)
INQUIRE GENERALIZED DRAWING PRIMITIVE
INQUIRE LIST OF AVAILABLE GENERALIZED DRAWING PRIMITIVES
SET PATTERN REFERENCE POINT
SET PATTERN SIZE
The escape and gdp functions are implemented as a set of functions which follow the
naming convention outlined in the C binding. That is, escape functions are
named gescfunction and gdp functions are named ggdpfunction, where function is a
descriptive name for the function performed.
ESCAPE FUNCTIONS
gescinqxattr() returns the attributes of the opened X window for workstation wsid.
gescsetbackingstore() enables (disables) backingstore for workstation wsid if i is non-
zero (zero). Backingstore is enabled by default if it is available on the workstation and
the backingstore X resource (see X-RESOURCES) doesn't indicate otherwise.
gescsetprogname() sets the program name by which the application will be known to X to
name. This name will be used to access X resouces by prepending it to resource names
(along with a separating period `.'). The X window will also be named name. By default,
the name XGKS is used.
gescsetcolormask () changes the color-plane mask on workstation wsid to mask via the X
function XSetPlaneMask().
gescsetdcsize() changes the device coordinate space on workstation wsid to size.
gescstoreprimi() enables (disables) the storing of non-segment output primitives on
workstation wsid if store is non-zero (zero). Storing is enabled by default and is
necessary for an X refresh (after an expose or resize event) to include primitives which
are not stored in any segment.
gescredrawnotify() registers the user-defined redraw function funcp with workstation wsid.
When a redraw action is initiated, the final action will be to call funcp with the first
argument set to the workstation number and the second argument set to GRD_GKS (if the
redraw was initiated by GKS) or to GRD_X (if the redraw was initiated by X). Both
symbolic constants are defined in the header-file xgks.h.
OUTPUT PRIMITIVES
Polylines of any width and color can be displayed while seven line styles are
supported they are:
GLN_DASH long dash
GLN_DDOTDASH double dot dash
GLN_SDASH short dash
GLN_SOLID solid
GLN_DASH medium dash
GLN_DOT dotted
GLN_DOTDASH dot dash
Polymarkers of any size and color can be displayed, five marker styles are provided:
GMK_POINT filled circle
GMK_PLUS +
GMK_STAR *
GMK_O unfilled circle
GMK_X X
All text within XGKS is implemented through stroke fonts, thus text primitives are
fully transformable. Nine font styles are supported:
1 SanSerif Roman
2 Serif Roman
3 SansSerif Bold Roman
4 Serif Bold Roman
5 Sanserif Italic Roman
6 Serif Italic Roman
7 SanSerif Script
8 Serif Script
9 Gothic
Fill Area output primitives can be displayed as hollow, solid, hatched and
patterned. Twenty (numbered one to twenty) hatch and pattern styles are predefined.
The application program can redefine these patterns; however, the programmer should be
aware that the gsetpatrep() function expects patterns to be stored in column major order
from bottom to top. This means that cell[0][0] is the bottom-left corner,
cell[dx-1][dy-1] is the top-right corner, and cell[0][1] is directly above cell[0][0].
GKS Cell Arrays are supported in their most general, transformable form.
LOGIAL INPUT DEVICES
XGKS supports the full GKS input model. Thus, all logical input devices operate in
request, sample, and event modes. Any number of logical input devices can be created for
each of the six input classes. All logical devices are triggered through the use of the
mouse and its buttons with the exception of the choice device where one prompting
technique uses the keyboard's function buttons. A logical input device is only
active when the mouse is within the echo area of the device and one or more of the
mouse buttons is pressed. When the mouse button is released, the physical device
triggers all logical input devices in request or event mode whose echo area surrounds
the cursor. Devices in sample mode are triggered whenever the mouse moves within the
echo area while the mouse is pressed. Any input operation can be aborted by
pressing the Break key on the keyboard.
Five prompting types are defined for the locator:
1 tracking cross
2 crosshair spanning X window
3 tracking cross
4 rubberband line
5 rubberband rectangle
The only restriction placed on these prompts is that prompt and echo type 5 does not
allow the rectangle to be a fill area style other than hollow. The fixed end of
the rubberband line and rubber rectangle is at the initial locator position while
the floating end is the current value.
The stroke input device differs from the locator by allowing more than one coordinate
point to be entered. There are three stroke prompts supported:
1 tracking cross
3 polymarker at each point
4 polyline joining points
The closeness of selected points can be controlled by specifying a minimum X
and minimum Y displacement in the stroke data record during stroke initialization.
Although specified as a distance in World Coordinate space, the restriction is
enforced in Normalized Device space.
The valuator input device allows the user to select a real numbered value within the
application specified range. Only one visual representation is currently supported:
the valuator appears as a bar with a sliding knob whose relative position determines the
current value. A horizontal bar is displayed if the echo area is wider than it
is tall, otherwise a vertical bar is used. This prompt technique is selected by valuator
prompt and echo types one and two.
Two types of choice devices are provided. Choice prompts one and two use the
keyboard function keys as a choice device, thus function key F1 returns choice number
one. Prompt and echo type one enables all function keys while prompt type two enables
only those keys specified in the data record when the device is initialized. Choice
prompt type three presents the user with a menu from which the current choice is
selected. These menus appear and act similar to most X11 window manager menus. That
is, the current selection is highlighted and selection is made by releasing the mouse
button when the desired choice is lit. A word of warning, these menus are displayed
in the choice echo area and DO NOT attempt to restore any output primitives that
they cover.
Currently only two pick prompt types are supported: one and three. Both prompt types
highlight the currently selected segment by flashing a bounding box around the
segment's extent. Also, picking is only implemented at the segment extent level. Thus,
if two segments overlap and the user points at the area of intersection, then the segment
of highest priority will be picked even if the cursor is directly over a primitive
contained in the other segment.
The string device has only one prompt and echo type: number 1. This prompt type
gives the user one line on which to type. This line is positioned in the upper-left
corner of the string echo area and is displayed as a hollow fill area within which an
insertion point cursor and typed text appear. As the user types, the only
special keys are Backspace, Delete, and Enter which perform the obvious functions.
The length of the line is limited by the width of the echo area and the size of the
string buffer as specified by the application program during string
initialization.
LIMITS
Four workstation types are defined by XGKS: MI, MO, WISS, and X11. When calling
the open workstation function the application must specify three parameters: 1) a
workstation identifier, which is an integer used to identify this workstation
throughout the application; 2) a workstation connection, which is either a file name for
the metafile workstations (MI and MO) or an X11 DISPLAY specification string (see the X
man page), or a null character pointer for the X11 workstation (if null, then the
environment variable DISPLAY is consulted); and 3) the workstation type, which is
either one of the strings "MI", "MO", or "WISS" (in which case a workstation of the
appropriate type will be opened) or a null character pointer (in which case an X11 window
will be created); The workstation connection parameter is ignored for the workstation
independent segment store (WISS) workstation. Ten workstations can be open
simultaneously; however, only one WISS workstation can be open.
There are thirty-one normalization transformations, numbered 0 to 30. Transformation
number zero is the identity transformation and cannot be changed.
Every X11 window workstation has a fixed device coordinate space that is 0 to 1279 on
the X axis and 0 to 1023 on the Y axis. This is not to say that the X window is that big,
the GKS workstation will be scaled to fit the X window; this scaling preserves the
aspect ratio.
There are twenty bundle table entries for each type of bundle table.
The size of the color table is determined by the X11 window server and the hardware
being used. The IBM apa16 monochrome display provides two colors and the
Megapel display supports 255 out of 4096 possible colors. Each XGKS workstation shares
the default color map of the display. The GKS SET COLOR REPRESENTATION function uses the
X11 XAllocColor() function to obtain the pixel value of the colorcell having the color
closest to the requested one. The association between GKS colour indices and X11
colorcells is maintained in a lookup table. This mechanism decouples GKS colour indices
from X11 pixel values and makes the XGKS client "friendly" in relation to other X11
clients in the handling of the X11 colormap.
GKS color index zero always refers to the X window background color while GKS color index
one refers to the X window foreground color.
METAFILES
Two Metafile formats are supported: GKSM and CGM. The GKSM format is a formatted audit-
trail of the GKS session: there is an almost isomorphic mapping between GKS calls and GKSM
records. Because GKSM is a formatted encoding, however, this format can impose a
considerable storage requirement. Also, the GKSM format is not widely used.
The CGM format used by XGKS is a subset of the binary encoding specified in the ANSI
X3.122-1986 standard. Because it is a binary encoding, this format is more space
efficient than the GKSM format. It is not quite as powerful, however, as it does not
record an audit-trail of the GKSM session; rather, it describes a set of independent,
static pictures. The CGM format is a widely used graphics standard.
The standard allows several alternative encodings for primitives such as floating-point
and integer values. XGKS uses the default encodings only. These are
REAL PRECISION Fixed point; whole part 16 bits;
fractional part 16 bits.
INTEGER PRECISION 16 bits
COLOUR PRECISION 1 octet (per colour component)
COLOUR INDEX PRECISION 1 octet
INDEX PRECISION 16 bits
VDC TYPE INTEGER
VDC INTEGER PRECISION 16 bits
VDC EXTENT (0,0) to (32767,32767)
COLOUR VALUE EXTENT minimum is (0,0,0) and maximum
is (255,255,255).
This CGM form is compatible with the NCAR Graphics package.
The type of Metafile is selected by the Metafile's filename. Filenames containing the
string ".cgm" (or ".CGM") are assumed to be in CGM format; all other files are assumed to
be in GKSM format.
X-RESOURCES
The following X-resources and their parameters are searched for by the XGKS library:
program.backingstore: on|off
Whether or not the server should use the X backing-store feature for windows created
by this application. Whether the backingstore feature is enabled by default depends
on the capability of the X server: if the server can use backingstore, then it's
enabled by default; otherwise it's disabled by default.
Xgks.Backingstore: on|off
Whether or not the server should use the X backing-store feature for the entire class
of XGKS applications.
program.background: color
Color for the background of the XGKS window for program program. The string color
must be understood by the X-server (.e.g "MidnightBlue").
Xgks.Background: color
Background color for the entire class of XGKS applications.
program.foreground: color
Color for the foreground of the XGKS window for program program. The string colorP
must be understood by the X-server (.e.g "white").
Xgks.Foreground: color
Foreground color for the entire class of XGKS applications.
program.geometry: XSIZExYSIZE[+-]xoff[+-]yoff
Geometry in pixels for the XGKS window of program program.
Xgks.Geometry: XSIZExYSIZE[+-]xoff[+-]yoff
Geometry in pixels for the entire class of XGKS applications.
program.iconic: on|off
Initially, map the XGKS window as an icon rather than as a normal window.
Xgks.Iconic: on|off
Initially, map the entire class of XGKS windows as icons rather than as normal
windows.
program.beep: on|off
Controls whether or not the bell sounds during interactive input in the XGKS window of
program program. The default is off.
Xgks.Beep: on|off
Controls whether or not the bell sounds during interactive input for the entire class
of XGKS applications. The default is off.
program.softclipping: on|off
Enable or disable the soft-clipping of polylines. By default, XGKS defers the
clipping of output primitives to the X Window System. This works reliably only if the
normalized device co-ordinates (NDC) of the output primitives are relatively close to
the NDC [0,1] unit-square. Due to wrap-around in the NDC-to-X co-ordinate
transformation, very large NDC values might cause extraneous lines to appear in the
display window. Though this behavior is server-dependent, it typically occurs when
displaying a small portion of a large graphic. Soft-clipping causes XGKS to clip
polyline output against the current NDC clip-window before calling X; thus eliminating
extraneous lines but incurring some additional computational overhead. Because this
behavior is server-dependent, we suggest you use the default (i.e. no soft-clipping)
until the problem manifests itself.
Xgks.Softclipping: on|off
Enable or disable soft-clipping for the entire class of Unidata XGKS applications.
USING X-RESOURCES
The following pseudo-code details the sequence of steps taken to initialize the program-
specific, internal, X-resource database. Definitions encountered during later steps
override earlier ones.
Clear internal X-resource database;
if (file /usr/lib/X11/app-defaults/program exists)
Merge its definitions into the database;
if (environment variable XAPPLRESDIR exists)
Merge the definitions in file $XAPPLRESDIR/program into the database;
if (X-server has an X-resource database) {
Merge its definitions into the database;
} else if (file ~/.Xdefaults exists) {
Merge its definitions into the database;
}
if (environment variable XENVIRONMENT exists) {
Merge the definitions in file $XENVIRONMENT into the database;
} else if (file ~/.Xdefaults-X-server_hostname exists) {
Merge its definitions into the database;
}
Notes:
1) The X-server may have its X-resource database updated via the xrdb(1) utility.
2) Program is the name of the program as set by the gescsetprogname() function (see
ESCAPE FUNCTIONS).
3) X-server_hostname is the name of the first host to which XGKS connects as returned by
the X function DisplayString(). (e.g. "groucho").
PROGRAMMING
Here is a simple XGKS program that displays "Hello World" in the center of the
default workstation window. After displaying the greeting, the program uses a
choice input device to wait for the user to press the break key. This is done because
the X window that represents this workstation is removed from the screen as soon as
the workstation is closed. The for loop in the main program is a convenient way for
the application to allow the user to specify the workstation connection id on the
command line via a hostname:serverNumber pair. If the connection id is not
specified XGKS will use the value of the environment variable DISPLAY in the users
environment.
#include <stdio.h>
#include <string.h>
#include <xgks.h>
/*
* This function is called when the program is finished
* and we just want to wait until the user is done looking
* at the output. Here we set up a choice device to use
* the function keys. However, we ignore all choices and
* wait for the user to press the Break key.
*/
static void
WaitForBreak(wsid)
Gint wsid;
{
Gchoice init;
Gchoicerec record;
Glimit earea = { 0.0, 1279.0, 0.0, 1023.0 };
gmessage(wsid, "Done, press Break to quit ...");
init.status = GC_NOCHOICE;
init.choice = 0;
record.pet1.data = NULL;
ginitchoice(wsid, 1, &init, 1, &earea, &record);
gsetchoicemode(wsid, 1, GREQUEST, GECHO);
while (init.status != GC_NONE)
greqchoice(wsid, 1, &init);
}
/*
* set up various text parameters and print "Hello World"
*/
PrintHello()
{
Gpoint tpt;
Gpoint up;
Gtxfp txfp;
Gtxalign align;
txfp.font = 4; /* use Serif Bold Roman font */
txfp.prec = GSTROKE;
gsettextfontprec(&txfp);
gsetcharexpan(0.5);
gsetcharspace(0.2);
gsettextcolorind(1); /* should be white */
gsetcharheight(0.05);
up.x = 0.0; up.y = 1.0; /* characters are straight up */
gsetcharup(&up);
align.hor = GTH_CENTER;
align.ver = GTV_HALF;
gsettextalign(&align);
gsettextpath(GTP_RIGHT); /* print from left to right */
tpt.x = 0.5; tpt.y = 0.5;/* center of the window */
gtext(&tpt,"Hello World!");
}
main(argc,argv)
int argc;
char *argv[];
{
int i, wsid=1;
char *conn = (char*)NULL;
for (i=1; i<argc; i++) {
if (strchr(argv[i], ':'))
conn = argv[i];
/* Application dependent options here */
}
gopengks(stdout,0);
if (gopenws(wsid, conn, conn) != 0)
exit(1);
gactivatews(wsid);
PrintHello();
WaitForBreak(wsid);
gdeactivatews(wsid);
gclosews(wsid);
gclosegks();
exit(0);
}
To compile the program, we use the following command line (NB: ${prefix}
is the root of the installation-tree):
cc hello.c -o hello -I${prefix}/include -L${prefix}/lib -lxgks -lX11 -lm
Or, if on an Apollo workstation:
cc hello.c -o hello -I${prefix}/include -L${prefix}/lib -lxgks -L/usr/lib/X11 -lX11 -lm
To execute, just type:
./hello
(NB: you must be running an X server when you run any XGKS application.)
Similarly, to compile a Fortran-based XGKS program (e.g. hello.f), we use:
f77 -O -o hello hello.f -L${prefix}/lib -lxgks -lX11 -lm
or, if using an Apollo workstation:
f77 -O -o hello hello.f -L${prefix}/lib -lxgks -L/usr/lib/X11 -lX11 -lm
or, if using an HP 9000/720 workstation:
f77 -O -o hello hello.f -Wl,-L,${prefix}/lib -lxgks -Wl,-L,/usr/lib/X11R4 -lX11 -lm
When the program opens the GKS workstation the X11 window system will prompt the
user to open a new window. The program will display "Hello World!" and then wait for
the user to press the Break key. While the GKS workstation window is on the screen
the user can resize, move, cover, and uncover the window and XGKS will take
care of redisplaying the greeting.
FILES
In the following, ${prefix} is the root of the installation directory-tree as defined by
the Makefile macro of the same name.
${prefix}/lib/libxgks.a The XGKS library.
${prefix}/lib/xgksfonts Font data-base directory.
${prefix}/bin Directory containing sample programs.
${prefix}/include/xgks.h C header-file.
ENVIRONMENT
XGKSFontDir, if set, contains the pathname of the directory which contains the XGKS fonts.
If not set, then the compiled-in pathname is used (see FILES).
SEE ALSO
X(1), xrdb(1), xterm(1).
Computer Graphics - Graphical Kernel System (GKS) Functional Description. ANSI,
X3.124-1985.
C Language Binding of GKS. ANSI X3H34/83-12R5, March 1986.
Computer Graphics, Donald Hearn and Pauline Baker, Prentice-Hall, 1986.
The X Window System, Robert W. Scheifler and Jim Gettys, ACM Transactions on Graphics,
volume 5, number 2, April 1986, pp. 79-109.
BUGS
The only workstations currently supported are X, GKSM, and CGM.
Support for input Metafiles is primitive, at best.
The decoupling between GKS colour-indices and X pixel values is primitive at best. Also,
an XGKS window always uses the default colormap.
BUG REPORTING
Bugs reports should be sent to xgks-bugs@unidata.ucar.edu [128.117.140.3]. Please include
a potential fix, if possible.
MAILING-LIST
A mutual-aid society, electronic mailing-list exists. Requests to join should be sent to
xgks-request@unidata.ucar.edu [128.117.140.3].
AUTHORS
Greg Rogers (grogers@a.cs.uiuc.edu)
Sung Hsien Ching (ksung@a.cs.uiuc.edu)
Yu Pan
Steve Emmerson (steve@unidata.ucar.edu)
This project was supported by IBM ACIS and was directed by Professors Bill Kubitz and Roy
Campbell of the Graphics Workstation Research Group, Department of Computer Science, at
the University of Illinois in Urbana, Illinois. Special thanks go to David Berkowitz and
Terry Rowan, our IBM contacts, who helped us get early versions of the X server for our
workstations.
Maintenance of XGKS by the Unidata Program Center is supported by the National Science
Foundation. Special thanks to all those in the user community who contribute to its
evolution.