Creating graphics contexts

Common Graphics : Using graphics contexts : Creating graphics contexts

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)

$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006015.gif$

LineSolid

GCCapStyle specifies how a line should be ended

CapNotLast
CapButt
CapRound
CapProjecting

$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006020.gif$

CapButt

CGJoinStyle specifies how two lines should be joined

JoinMiter

JoinRound

JoinBevel

$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006025.gif$

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)

$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006030.gif$

FillSolid

GCFillRule specifies how a polygon should be drawn when it intersects itself

EvenOddRule (hollow where areas intersect)

WindingRule (solid where areas intersect)

$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006035.gif$

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)

$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006040.gif$

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

$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006045.gif$ $C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006045.gif$

0

GCTileStipYOrigin specifies the y offset of the stipple or tile pattern allowing you to position the pattern evenly

Integer value

$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006050.gif$ $C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006050.gif$

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

$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006055.gif$

#(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

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)	$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006015.gif$	LineSolid
GCCapStyle specifies how a line should be ended	CapNotLast CapButt CapRound CapProjecting	$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006020.gif$	CapButt
CGJoinStyle specifies how two lines should be joined	JoinMiter JoinRound JoinBevel	$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006025.gif$	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)	$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006030.gif$	FillSolid
GCFillRule specifies how a polygon should be drawn when it intersects itself	EvenOddRule (hollow where areas intersect) WindingRule (solid where areas intersect)	$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006035.gif$	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)	$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006040.gif$	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	$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006045.gif$ $C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006045.gif$	0
GCTileStipYOrigin specifies the y offset of the stipple or tile pattern allowing you to position the pattern evenly	Integer value	$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006050.gif$ $C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006050.gif$	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	$C:\Users\documentation\Documents\vastePublisher\stable\VAS Documentation Word\images\sp006055.gif$	#(4 4)

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