XCreateGC(3X11) X Version 11(Release 5) XCreateGC(3X11)
NAME
XCreateGC, XCopyGC, XChangeGC, XGetGCValues, XFreeGC, XGContextFromGC,
XGCValues - create or free graphics contexts and graphics context
structure
SYNTAX
GC XCreateGC(display, d, valuemask, values)
Display *display;
Drawable d;
unsigned long valuemask;
XGCValues *values;
XCopyGC(display, src, valuemask, dest)
Display *display;
GC src, dest;
unsigned long valuemask;
XChangeGC(display, gc, valuemask, values)
Display *display;
GC gc;
unsigned long valuemask;
XGCValues *values;
Status XGetGCValues(display, gc, valuemask, values_return)
Display *display;
GC gc;
unsigned long valuemask;
XGCValues *values_return;
XFreeGC(display, gc)
Display *display;
GC gc;
GContext XGContextFromGC(gc)
GC gc;
ARGUMENTS
d Specifies the drawable.
dest Specifies the destination GC.
display Specifies the connection to the X server.
gc Specifies the GC.
src Specifies the components of the source GC.
valuemask Specifies which components in the GC are to be set, copied,
changed, or returned . This argument is the bitwise inclusive
OR of zero or more of the valid GC component mask bits.
10/89 Page 1
XCreateGC(3X11) X Version 11(Release 5) XCreateGC(3X11)
values Specifies any values as specified by the valuemask.
values_return
Returns the GC values in the specified XGCValues structure.
DESCRIPTION
The XCreateGC function creates a graphics context and returns a GC. The
GC can be used with any destination drawable having the same root and
depth as the specified drawable. Use with other drawables results in a
BadMatch error.
XCreateGC can generate BadAlloc, BadDrawable, BadFont, BadMatch,
BadPixmap, and BadValue errors.
The XCopyGC function copies the specified components from the source GC
to the destination GC. The source and destination GCs must have the same
root and depth, or a BadMatch error results. The valuemask specifies
which component to copy, as for XCreateGC.
XCopyGC can generate BadAlloc, BadGC, and BadMatch errors.
The XChangeGC function changes the components specified by valuemask for
the specified GC. The values argument contains the values to be set.
The values and restrictions are the same as for XCreateGC. Changing the
clip-mask overrides any previous XSetClipRectangles request on the
context. Changing the dash-offset or dash-list overrides any previous
XSetDashes request on the context. The order in which components are
verified and altered is server-dependent. If an error is generated, a
subset of the components may have been altered.
XChangeGC can generate BadAlloc, BadFont, BadGC, BadMatch, BadPixmap, and
BadValue errors.
The XGetGCValues function returns the components specified by valuemask
for the specified GC. If the valuemask contains a valid set of GC mask
bits (GCFunction, GCPlaneMask, GCForeground, GCBackground, GCLineWidth,
GCLineStyle, GCCapStyle, GCJoinStyle, GCFillStyle, GCFillRule, GCTile,
GCStipple, GCTileStipXOrigin, GCTileStipYOrigin, GCFont, GCSubwindowMode,
GCGraphicsExposures, GCClipXOrigin, GCCLipYOrigin, GCDashOffset, or
GCArcMode) and no error occur, XGetGCValues sets the requested components
in values_return and returns a nonzero status. Otherwise, it returns a
zero status. Note that the clip-mask and dash-list (represented by the
GCClipMask and GCDashList bits, respectively, in the valuemask) cannot be
requested. Also note that an invalid resource ID (with one or more of
the three most-significant bits set to one) will be returned for GCFont,
GCTile, and GCStipple if the component has never been explicitly set by
the client.
The XFreeGC function destroys the specified GC as well as all the
associated storage.
Page 2 10/89
XCreateGC(3X11) X Version 11(Release 5) XCreateGC(3X11)
XFreeGC can generate a BadGC error.
STRUCTURES
The XGCValues structure contains:
/* GC attribute value mask bits */
#define GCFunction (1L<<0)
#define GCPlaneMask (1L<<1)
#define GCForeground (1L<<2)
#define GCBackground (1L<<3)
#define GCLineWidth (1L<<4)
#define GCLineStyle (1L<<5)
#define GCCapStyle (1L<<6)
#define GCJoinStyle (1L<<7)
#define GCFillStyle (1L<<8)
#define GCFillRule (1L<<9)
#define GCTile (1L<<10)
#define GCStipple (1L<<11)
#define GCTileStipXOrigin (1L<<12)
#define GCTileStipYOrigin (1L<<13)
#define GCFont (1L<<14)
#define GCSubwindowMode (1L<<15)
#define GCGraphicsExposures (1L<<16)
#define GCClipXOrigin (1L<<17)
#define GCClipYOrigin (1L<<18)
#define GCClipMask (1L<<19)
#define GCDashOffset (1L<<20)
#define GCDashList (1L<<21)
#define GCArcMode (1L<<22)
/* Values */
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 (in pixels) */
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 stipple operations */
int ts_y_origin;
Font font; /* default text font for text operations */
int subwindow_mode; /* ClipByChildren, IncludeInferiors */
Bool graphics_exposures; /* boolean, should exposures be generated */
int clip_x_origin; /* origin for clipping */
int clip_y_origin;
10/89 Page 3
XCreateGC(3X11) X Version 11(Release 5) XCreateGC(3X11)
Pixmap clip_mask; /* bitmap clipping; other calls for rects */
int dash_offset; /* patterned/dashed line information */
char dashes;
} XGCValues;
The function attributes of a GC are used when you update a section of a
drawable (the destination) with bits from somewhere else (the source).
The function in a GC defines how the new destination bits are to be
computed from the source bits and the old destination bits. GXcopy is
typically the most useful because it will work on a color display, but
special applications may use other functions, particularly in concert
with particular planes of a color display. The 16 GC functions, defined
in <X11/X.h>, are:
Xlib - C Language X Interface
Page 4 10/89