XtAllocateGC()XtAllocateGC()NameXtAllocateGC - 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.
DescriptionXtAllocateGC() 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 argu‐
ments 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
appropriate 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.
UsageXtAllocateGC() is a generalization of XtGetGC(). Calling XtAllo‐
cateGC() with depth, dynamic_mask, and dont_care_mask all 0 is equiva‐
lent to calling XtGetGC() with the remaining arguments.
There are several common situations in which a modifiable GC is neces‐
sary. 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 XCre‐
ateGC().
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 wid‐
get, 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 com‐
pilation 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 XtGC‐
Mask. 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 AlsoXtGetGC(1), XtReleaseGC(1).
Xt - Graphics Context XtAllocateGC()
