hpux man page for xtgetgc

XtGetGC()																 XtGetGC()

Name
  XtGetGC - obtain a read-only, sharable GC.

Synopsis
  GC XtGetGC(object, value_mask, values)
	 Widget object;
	 XtGCMask value_mask;
	 XGCValues *values;

Inputs
  object    Specifies the object with which the GC is to be associated; may be of class Object or any subclass thereof.

  value_mask
	    Specifies which fields of the GC are to be filled in with widget data.

  values    Specifies the actual values for this GC.

Returns
  A read-only GC with fields as specified in value_mask and values.

Description
  XtGetGC()  returns  a  sharable,  read-only  GC with values as specified in values for each bit set in value_mask.  The GC is valid for the
  screen and depth of object, or the nearest widget ancestor if object is not a subclass of Core.

  XtGetGC() shares only GCs in which all values in the GC are the same.  In particular, it does not use the value_mask provided to  determine
  which  fields of the GC a widget considers relevant.	value_mask is used only to tell the server which fields should be filled in with wid-
  get data and which it should fill in with default values.

Usage
  The Intrinsics provide a mechanism whereby widgets can share a graphics context (GC), reducing  the  number  of  GCs	created  and  thereby
  improving server performance.  The mechanism is a simple caching scheme, and all GCs obtained by means of this mechanism must be treated as
  read-only.

  If a GC with modifiable fields is needed, in Release 4 or previous releases the Xlib XCreateGC() function must  be  used.   In  Release  5,
  XtAllocateGC() allows a widget to allocate a shared GC with modifiable fields.

  Generally  only  widgets  will  need to allocate GCs, though some applications may also want to do so.  When done with a shared GC, free it
  with XtReleaseGC().

Structures
  The XtGCMask type is defined as follows:

     typedef unsigned long  XtGCMask; /* Mask of values that are used by widget*/

  Each of the symbols in the table below sets a single bit in an XtGCMask.  The value_mask, argument is formed	by  combining  these  symbols
  with the bitwise OR operator ( ):

GCArcMode	GCFillRule	      GCLineWidth
GCBackground	GCFillStyle	      GCPlaneMask
GCCapStyle	GCFont		      GCStipple
GCClipMask	GCForeground	      GCSubwindowMode
GCClipXOrigin	GCFunction	      GCTile
GCClipYOrigin	GCGraphicsExposures   GCTileStipXOrigin
GCDashList	GCJoinStyle	      GCTileStipYOrigin
GCDashOffset	GCLineStyle

The XGCValues structure contains the GC fields:

typedef struct {
  int function;       /* logical operation */
  unsigned long plane_mask;/* plane mask */
  unsigned long foreground;/* foreground pixel */
  unsigned long background;/* background pixel */
  int line_width;     /* line width */
  int line_style;     /* LineSolid, LineOnOffDash,
			 LineDoubleDash */
  int cap_style;      /* CapNotLast, CapButt,
			 CapRound, CapProjecting */
  int join_style;     /* JoinMiter, JoinRound, JoinBevel */
  int fill_style;     /* FillSolid, FillTiled,
			 FillStippled, FillOpaqueStippled */
  int fill_rule;      /* EvenOddRule, WindingRule */
  int arc_mode;       /* ArcChord, ArcPieSlice */
  Pixmap tile;	      /* tile pixmap for tiling operations */
  Pixmap stipple;     /* stipple 1 plane pixmap for stippling */
  int ts_x_origin;    /* offset for tile or
  int ts_y_origin;     * stipple operations */
  Font font;	      /* default text font for text operations */
  int subwindow_mode; /* ClipByChildren, IncludeInferiors */
  Bool graphics_exposures;/* should exposures be generated? */
  int clip_x_origin;  /* origin for clipping */
  int clip_y_origin;
  Pixmap clip_mask;   /* bitmap clipping; other calls for rects */
  int dash_offset;    /* patterned/dashed line information */
  char dashes;
} XGCValues;

See Also
  XtAllocateGC(1), XtReleaseGC(1).

Xt - Graphics Context															 XtGetGC()