Programmer's Reference

Creating graphics contexts

Graphics contexts are created by sending the createGC:values: message to a CgDrawable. The GC attributes are initialized to preset values, listed in Table 16. The two arguments of the message specify modifications to the preset values. The first argument, valuemask, specifies which components of the second argument, values, should override the preset values.

Creating a graphics context with default values

In the following example, the temporary variable gc is assigned a graphics context. By passing the CgConstants constant None as the valuemask and nil as the values, the graphics context is initialized using default values.

| gc |
gc := CgWindow default
    createGC: None
    values: nil.

Creating a graphics context using the CgGCValues object

Graphics contexts can be configured using a CgGCValues object. The CgGCValues object is a convenient way of storing graphics attributes without having to store the graphics context and its associated overhead. The CgGCValues object is used to configure a GC or to query its attributes.

In the following example, a CgGCValues object is created, the function: message sets the desired raster operation (GXhighlight), and the lineWidth: message sets a line width value (2 pixels) in the CgGCValues object. The CgGCValues object is then passed to the drawable using the createGC:values: message. The valuemasks GCFunction and GCLineWidth are ORed together to create a mask that identifies which attributes are being modified. The gcValues variable contains the new values for the attributes.

| gc gcValues |
gcValues := CgGCValues new
    function: GXhighlight;
    lineWidth: 2.
gc := CgWindow default
    createGC: GCFunction | GCLineWidth
    values: gcValues.

Retrieving several values from a graphics context using the CgGCValues object

You can also use a CgGCValues object to retrieve attribute values from a graphics context. In the following example, the GCLineWidth valuemask is used to retrieve the current line width. The information is returned in a new CgGCValues object.

| gcValues lineWidth |
CgGC default
    getGCValues: GCLineWidth
    valuesReturn: (gcValues := CgGCValues new).
lineWidth := gcValues lineWidth.
Note:
The GCClipMask and GCDashList components of a GC cannot be retrieved.

Table 16 contains the complete list of attributes that can be initialized or modified. In most cases, the attribute is either an integer value or a constant from the CgConstants pool dictionary. For a detailed explanation, consult the method comment for the createGC:values: method of CgDrawable.

Table 16. Graphics context attributes

Value mask Value expected Default value
GCForeground specifies the foreground drawing color Integer pixel value (index of color in colormap) 0
GCBackground specifies the background drawing color Integer pixel value (index of color in colormap) 1
GCLineWidth specifies the thickness of the drawing line Integer value of line width in pixels 1 pixel
GCLineStyle specifies how a line should be drawn. Dash pattern is specified using a dash list (see "dashes" below) LineSolid (foreground color)

LineOnOffDash (foreground color)

LineDoubleDash (fore- and background color)


sp006015

LineSolid
GCCapStyle specifies how a line should be ended CapNotLast
CapButt
CapRound
CapProjecting

sp006020

CapButt
CGJoinStyle specifies how two lines should be joined JoinMiter


JoinRound


JoinBevel


sp006025

JoinMiter
GCFillStyle specifies how to fill an object such as an arc, rectangle, or polygon FillSolid
(foreground color)
FillStippled
(foreground color)
FillOpaqueStippled
(fore- and background
colors)
FillTiled
(a multicolored pixmap)

sp006030

FillSolid
GCFillRule specifies how a polygon should be drawn when it intersects itself EvenOddRule (hollow where areas intersect)

WindingRule (solid where areas intersect)


sp006035

EvenOddRule
GCArcMode specifies how an arc should be drawn. To fill an arc, the GCFillStyle would also have to be set correctly. ArcChord (connects start and end points directly)

ArcPieslice (connects start and end points through the arc center point)


sp006040

ArcChord
GCFunction specifies the raster operation to be used GXcopy
(draws shape directly from source)
GXhighlight
(draws shape, replacing foreground with
background and vice-versa. Drawing
the same shape again will restore
drawable to previous state)
GXcopy
GCFont specifies the font to be used in text drawing operations A CgFont Standard system font
GCSubwindowMode specifies whether drawing in a parent window is clipped by or draws over child windows ClipByChildren
(allows drawing only in the parent window; child
windows are not affected)
IncludeInferiors
(child boundaries are ignored; drawing in the
parent window will draw over child windows)
ClipByChildren
GCTileStripXOrigin specifies the x offset of the tile or stipple pattern allowing you to position the pattern evenly Integer value
sp006045

0
GCTileStipYOrigin specifies the y offset of the stipple or tile pattern allowing you to position the pattern evenly Integer value
sp006050

0
GCClipXOrigin x integer coordinate for clipping 0
GCClipYOrigin y integer coordinate for clipping 0
GCClipMask specifies the CgPixmap used as a clipping mask A CgPixmap of depth 1, or nil nil
GCDashOffset specifies in pixels where to begin within a dash pattern Integer value 0
tile specifies a CgPixmap to be used as a multiplane, multicolor fill pattern A CgPixmap of the same depth as the drawable A tile CgPixmap containing all zeros
stipple specifies a CgPixmap to be used as a 1-plane, 2-color fill pattern A CgPixmap of depth 1 A stipple CgPixmap containing all ones
dashes specifies the lengths of segments in the dash list Array of integers specifying the length of each dash in number of pixels
sp006055

#(4 4)
Tip:
Some platforms impose constraints on the implementation of the graphics context attributes. These limitations are described in Appendix D, "Common graphics platform differences".

Configuring a graphics context using convenience methods

Convenience (set) methods have been provided for setting graphics context attributes. These methods are sent directly to the graphics context and are simpler to use than specifying CgGCValues and valuemasks.

In the following example, a GC is created using default values, then immediately modified using two convenience methods.

| gc |
gc := CgWindow default
    createGC: None
    values: nil.
gc setFunction: GXcopy.
gc
    setLineAttributes: 2
    lineStyle: LineSolid
    capStyle: CapButt
    joinStyle: JoinMiter.

The following table lists frequently used convenience methods that can be sent to a graphics context.

Table 17. Graphics context convenience (set) methods

Method Values modified Example
setBackground: Background color
gc setBackground:
    CgWindow default whitePixel
setDashes:
dashList:
Dash offset and pattern
gc setDashes: 0 dashList: #(100 20)
setForeground: Foreground color
gc setForeground:
    CgWindow default blackPixel
setFunction: Raster operation
gc setFunction: GXhighlight
setLineAttributes:
  lineStyle:
  capStyle:
  joinStyle:
Width, style, endcap style, and join style of a line, all at once
gc
 setLineAttributes: 2
   lineStyle: LineOnOffDash
   capStyle: CapButt
   joinStyle: JoinMiter
setState:
background:
function:
planeMask:
Foreground and background colors, the raster operation function, and the planeMask all at once
gc
 setState: CgWindow default blackPixel
 background: CgWindow default whitePixel
 function: GXcopy
 planeMask: nil


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]