XtGetGC(3x) — HP-UX 9.05

NAME

XtGetGC − obtain a read-only, sharable GC.

Synopsis

GC XtGetGC(object, value_mask, values)

    Widget object;
    XtGCMask value_mask;
    XGCValues *values;

Inputs

objectSpecifies 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.

valuesSpecifies 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 widget 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;

Museum

Related Articles