All Manuals > CAPI User Guide and Reference Manual > 22 GRAPHICS-PORTS Reference Entries

graphics-state System Class

Summary

The graphics state object, holding default parameters for drawing operations on an associated port.

Package

graphics-ports

Superclasses

t

Accessors

graphics-state-transform
graphics-state-foreground
graphics-state-background
graphics-state-operation
graphics-state-stipple
graphics-state-pattern
graphics-state-thickness
graphics-state-scale-thickness
graphics-state-dashed
graphics-state-dash
graphics-state-fill-style
graphics-state-line-end-style
graphics-state-line-joint-style
graphics-state-mask
graphics-state-mask-x
graphics-state-mask-y
graphics-state-mask-transform
graphics-state-font
graphics-state-text-mode
graphics-state-shape-mode
graphics-state-compositing-mode

Description

The system class graphics-state contains the default values of graphics parameters for drawing operations. Each graphics port has a graphics-state object associated with it. The drawing operations such as draw-ellipse, draw-rectangle and draw-string can override specific parameters by passing them as keyword arguments.

graphics-state objects are used in the with-graphics-state macro and modified using the accessor functions listed above. See 13.3.1 Setting the graphics state for examples.

graphics-state contains the following properties:

transform
A transform object which determines the coordinate transformation applying to the graphics port. The default value is the unit transform which leaves the port coordinates unchanged from those used by the host window system — origin at top left, X increasing to the right and Y increasing down the screen. Allowed values are anything returned by the transform functions, described in 13.6 Graphics state transforms.
foreground
Determines the foreground color used in drawing functions. The value can be a converted color (result of convert-color), a color name symbol, a color name string or a color spec object. Using converted colors results in better performance, because it saves the system from doing the conversion each time it uses it. The default value is :black. The value :color_highlighttext is useful for drawing text with the system highlighting.
background

Determines the background color used in functions which draw text such as draw-string when block is true.

On X11/Motif, background also determines the background color used in drawing functions which use a stipple.

Valid values are the same as for foreground. The default value is :white. The value :color_highlight is useful for drawing text with the system highlighting.

operation
Determines the color combination used in the drawing primitives when the port's drawing-mode is :compatible. Valid values are 0 to 15, being the same logical values as the op arg to the Common Lisp function boole. The default value is boole-1. 13.7.1 Combining pixels with :compatible drawing shows how to use operation.
stipple
On X11/Motif stipple is a 1-bit pixmap ("bitmap") or nil (which is the default value). The bitmap is used in conjunction with the fill-style when drawing. Here, nil means that all pixels are drawn in the foreground color. A stipple is not transformed by the transform parameter. Its origin is assumed to coincide with the origin of the port. The stipple is tiled across the drawing. stipple is ignored if a pattern is given. If no fill-style is given, or it is specified as :solid, when a stipple is given, then fill-style defaults to :opaque-stippled.
fill-style

Determines how the drawing is done. The value should be one of :solid, :tiled, :opaque-stippled or :stippled. The default value :solid means that the foreground is used everywhere. :tiled means that the pattern is repeated over across the drawing.

Additionally on X11/Motif :opaque-stippled means that the stipple bitmap is used with stipple 1s giving the foreground and 0s the background. :stippled means that the stipple bitmap is used with foreground where there are 1s and where the are 0s, no drawing is done. If you specify a stipple but no fill-style, or a fill-style of :solid, it defaults to :opaque-stipple.

pattern

An image the same depth as the port, or nil. If non-nil, pattern is used as the source of color for drawing instead of the foreground and background parameters. A pattern is not transformed by the transform parameter. The pattern is tiled across the drawing. When pattern is specified, the stipple value is ignored.The default value of pattern is nil.

See 13.10 Working with images for information on creating an image.

thickness
A number (defaulting to 1) specifying the thickness of lines drawn. If scale-thickness is non-nil, the value thickness is in port (transformed) coordinates, otherwise thickness is in pixels.
scale-thickness
A boolean, defaulting to t which means interpret the thickness parameter in transformed port coordinates. If scale-thickness is nil, thickness is interpreted in pixels.
dashed
A boolean, defaulting to nil. If dashed is t then lines are drawn as a dashed line using dash as the mark-space specifier.
dash
A list of two or more integer, or nil. A list of integers specifies the alternate mark and space sizes for dashed lines. These mark and space values are interpreted in pixels only. The default value of dash is (4 4).
line-end-style
The value should be one of :butt, :round or :projecting and specifies how to draw the ends of lines. The default value is :butt.
line-joint-style
The value should be one of :bevel, :miter or :round and specifies how to draw the areas where the edges of polygons meet. The default value is :miter.
mask

nil, or a list specifying a shape. The mask clips the drawing, so that drawing occurs only inside it.

mask should be nil (the default), a list of the form (x y width height), defining a rectangle inside which the drawing is done or a list of the form (:path path :fill-rule fill-rule) specifying a path inside which the drawing is done. The mask is not tiled.

In the latter case path should be a path specification (see draw-path). The fill-rule specifies how overlapping regions are filled. Possible values are :even-odd and :winding. The mask will be transformed by the mask-transform parameter.

There some examples of path masks in:

(example-edit-file "capi/graphics/paths")
mask-x

An integer specifying in window coordinates where in the port the X coordinate of the mask origin is to be considered to be. The default value is 0.

The mask-x parameter works only when the drawing-mode is :compatible and the platform is GTK+ or X11/Motif.

mask-x is deprecated.

mask-y

An integer specifying in window coordinates where in the port the Y coordinate of the mask origin is to be considered to be. The default value is 0.

The mask-y parameter works only when the drawing-mode is :compatible and the platform is GTK+ or X11/Motif.

mask-y is deprecated.

mask-transform

A transform object which determines the coordinate transformation use for the mask in drawing-mode :quality.

mask-transform is used only in drawing-mode :quality. It is ignored in drawing-mode :compatible. The default value is the unit transform, which can also be specified as nil. Other allowed values include anything returned by the transform functions, described in 13.6 Graphics state transforms. The other allowed value of mask-transform is the keyword :dynamic which is replaced by the current value of the transform graphics state parameter when the drawing operation uses the mask.

font

Either nil or a font object to be used by the draw-character and draw-string functions. The default value is nil.

Note that font cannot be a font-description. Use find-best-font to convert a font-description to a font.

text-mode
A keyword controlling the mode of rendering text, most importantly anti-aliasing (see below).
shape-mode
A keyword controlling the mode of drawing shapes, that is, anything except text (see below).
compositing-mode

A keyword controlling the combining of new drawing with existing drawing (see below).

Each of text-mode and shape-mode can be one of:

:plain
No anti-aliasing.
:antialias
With anti-aliasing.
:fastest
Fastest rendering. The same as :plain except on Windows.
:best
Best display.
:default
The system default (which is :antialias).

Additionally text-mode can be :compatible, which causes text to be drawn the way it would be drawn if drawing-mode was :compatible. This makes a difference only on Microsoft Windows, because on other platforms the default text-mode draws like the :compatible one.

The default of both text-mode and shape-mode is :default.

compositing-mode is a keyword or an integer controlling the compositing mode, that is the way that a new drawing is combined with the existing value in the target of the drawing to generate the result.

Two values of compositing-mode are supported on all platforms other than Motif:

:over
Draw over the existing values. If the source is a solid color, then the result is simply the source. If the source has alpha value alpha, then it is blended with the destination, with the destination multiplied by the remainder of the alpha, that is (- 1 alpha).
:copy
The source is written to the destination ignoring the existing values. If the source has alpha and the target does not, that has the effect of converting semi-transparent source to solid.

The default value of compositing-mode is :over.

The value :copy of compositing-mode is especially useful for creating a transparent or semi-transparent pixmap-port, which can be displayed directly or converted to an image by make-image-from-port.

On Cocoa 10.5 and later and GTK+ 2.8 or later, these additional keyword values of compositing-mode are supported: :clear, :over, :in, :out, :atop, :dest-over, :dest-in, :dest-out, :dest-atop, :xor and :add. These correspond to the CAIRO_OPERATOR_* operators in Cairo, which are documented in cairographics.org/operators and the CGBlendMode values which are documented in the CGContext Reference at developer.apple.com .

Note: on GTK+, the "unbounded" operators (:in, :out, :dest-in and :dest-atop) do not work properly for shape drawings. They can only be used for image drawing and copying operations.

Both Cocoa and GTK+ also allow compositing-mode to be an integer, which is simply passed through to the underlying system. This allows using modes that are not available via keywords, but it is not portable. For Cocoa, it is a CGBlendMode as documented in the CGContext Reference. For GTK+ it is cairo_operator_t, as documented in the entry for cairo_t in the Gnome documentation for Cairo.

Note: For drawing images on Cocoa, only values that corresponding to available keywords work properly.

Notes
  1. operation is not supported for drawing text on Microsoft Windows.
  2. stipple is supported only on X11/Motif.
  3. mask-x and mask-y are supported only on GTK+ and X11/Motif, and only when the drawing-mode is :compatible.
  4. pattern is supported only on Microsoft Windows, GTK+ and X11/Motif.
  5. operation is not supported by Cocoa/Core Graphics so this slot or argument is ignored on Cocoa.
  6. operation is ignored when the port's drawing-mode is :quality.
  7. text-mode and shape-mode are supported only on Cocoa, Cairo and GDI+, which are used on Macintosh, GTK and Windows respectively when the drawing-mode is :quality. For more information about drawing-mode, see 13.2.1 The drawing mode and anti-aliasing.
Examples
(example-edit-file "capi/graphics/compositing-mode-simple")
(example-edit-file "capi/graphics/compositing-mode")
See also

make-graphics-state
set-graphics-state
with-graphics-state
13 Drawing - Graphics Ports


CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:44