graphics-state

Slots

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

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.

shape-mode

A keyword controlling the mode of drawing shapes (that is, anything except text).

compositing-mode

A keyword controlling the combining of new drawing with existing drawing.

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

Each graphics port has a graphics-state object associated with it, providing the default values of graphics parameters for drawing operations. 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 Setting the graphics state for examples.

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

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.

graphics-state

`Structure Class`

Summary

Package

Slots

Accessors

Description

Notes

Examples

See also