hpux man page for xtallocategc

XtAllocateGC()															    XtAllocateGC()

Name
  XtAllocateGC - obtain a sharable GC with modifiable fields.

Synopsis
  GC XtAllocateGC(object, depth, value_mask, values, dynamic_mask, dont_care_mask)
	 Widget object;
	 Cardinal depth;
	 XtGCMask value_mask;
	 XGCValues *values;
	 XtGCMask dynamic_mask;
	 XtGCMask dont_care_mask;

Inputs
  object    Specifies an object; may be of class Object or any subclass thereof.

  depth     Specifies the depth for which the returned GC is valid, or 0.

  value_mask
	    Specifies the fields of the GC which must have fixed values.

  values    Specifies the values for the fields in value_mask.

  dynamic_mask
	    Specifies fields of the GC which may be modified.

  dont_care_mask
	    Specifies fields of the GC which will never be used.

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

Availability
  Release 5 and later.

Description
  XtAllocateGC()  returns  a sharable GC with values as specified in values for each field set in value_mask.  The GC is valid for the screen
  of the specified object (the screen of the nearest widget ancestor if the specified object is not itself a widget) and for  drawable	depth
  depth.  If depth is 0, the depth is taken from the XtNdepth resource of the object (or from its nearest widget ancestor).  The dynamic_mask
  and dont_care_mask arguments specify more information about the intended usage of the GC which influences how the GC may be shared.	These
  arguments are explained below.

  When	returned,  the GC may already be in use by other widgets, and it may be passed to other widgets in the future.	For this reason, none
  of the fields specified in value_mask should ever be modified.  The dynamic_mask argument specifies fields of the GC that may  be  modified
  by  the  widget.   Because  this  is	a  shared  GC, other widgets may also modify those fields, and a widget cannot rely on them to remain
  unchanged.  For this reason, these fields must be explicitly set prior to every use.

  The dont_care_mask argument specifies fields of the GC that the widget does not care about (i.e., fields that will never be used by any  of
  the graphic functions called with this GC).  The returned GC may have any values for these fields.

  GC  fields  that are not specified in value_mask, dynamic_mask, or dont_care_mask will always have their default values in the returned GC.
  If a field is specified in both value_mask, and in dynamic_mask, then the field is modifiable, but will also be initialized to  the  appro-
  priate  value  specified  in	values.  If a field is set in dont_care_mask and is also set in one of the other masks, the dont_care_mask is
  ignored for that field.

Usage
  XtAllocateGC() is a generalization of XtGetGC().  Calling XtAllocateGC() with depth, dynamic_mask, and dont_care_mask all 0  is  equivalent
  to calling XtGetGC() with the remaining arguments.

  There  are  several  common  situations  in which a modifiable GC is necessary.  If you are drawing complex text with XDrawText(), the font
  field of your GC will be automatically changed to each of the font values in your text description.  Also, if you use clip masks to protect
  or  speed  up  drawing  in  a  widget's  expose method, you will need to modify the clipping fields of the GC.  Using XtAllocateGC() with a
  dynamic_mask argument means that you can share a GC, with other instances of the same widget at least, instead of allocating a  private  GC
  with XCreateGC().

  Furthermore,	specifying  a dont_care_mask when allocating a shared GC can make that GC much more sharable.  For example, if a widget draws
  text with XDrawString() only, then it is only interested in the font and foreground fields of a GC.  If it allocates its GC  and  specifies
  that	it  doesn't care about the background field, then it can share its GC with another widget that uses the same font and foreground, but
  draws with XDrawImageString() and so does care about the background field.  This kind of sharing is not possible with XtGetGC().

  Note that XtAllocateGC() is new in Release 5.  If you use it in a widget, you will lose portability to Release 4.  If you have a Release  4
  widget  that	uses a private GC, you may be able to add conditional compilation directives to make it use the more efficient XtAllocateGC()
  when compiled with X11R5.

  When done with a GC obtained with XtAllocateGC(), it should be freed with XtReleaseGC().

Structures
  The XtGCMask type is simply an unsigned long:

     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, dynamic_mask, and  dont_care_mask  arguments  are
  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 has one field for each of 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
  XtGetGC(1), XtReleaseGC(1).

Xt - Graphics Context														    XtAllocateGC()