Common Lisp Interface Manager 2.0 User's Guide > Chapter 3 The CLIM Drawing Environment

NextPrevUpTopContentsIndex

3.3 CLIM Line Styles

A line is a one-dimensional object. In order to be visible, however, the rendering of a line must occupy some non-zero area on the display hardware. CLIM uses a line style object to represent the advice supplied to the rendering substrate on how to perform the rendering.

It is often useful to create a line style object that represents a style you wish to use frequently, rather than continually specifying the corresponding line style suboptions.

line-style [Protocol Class]	

Summary: The protocol class for line styles. If you want to create a new class that behaves like a line style, it should be a subclass of line-style . Subclasses of line-style must obey the line style protocol.

line-style-p [Function]	

Arguments: object

Summary: Returns t if object is a line style; otherwise, it returns nil .

standard-line-style

Summary: An instantiable class that implements line styles. A subclass of line-style , this is the class that make-line-style instantiates. Members of this class are immutable.

make-line-style [Function]	

Arguments: &key unit thickness joint-shape cap-shape dashes

Summary: Returns an object of class standard-line-style with the supplied characteristics. The arguments and their default values are described in 3.3, CLIM Line Styles

Each of the following suboptions has a corresponding reader that can be used to extract a particular component from a line style. The following generic functions comprise the line style protocol; all subclasses of line-style implement methods for these generic functions.

:line-unit 

line-style-unit [Generic Function]

Arguments: line-style

Summary: Gives the unit used for measuring line thickness and dash pattern length for the line style. Possible values are as follows:

:normal --thicknesses and lengths are given in a relative measure in terms of the usual or "normal" line thickness, which is the thickness of the "comfortably visible thin line," a property of the underlying rendering substrate. (This is the default value.)

:point --thicknesses and lengths are given in an absolute measure in terms of printer's points (approximately 1/72 of an inch). This measure was chosen so that CLIM implementors who interface CLIM to an underlying rendering engine (the window system) may legitimately choose to make it render as 1 pixel on current (1992) display devices.

:coordinate --the same units should be used for line thickness as are used for coordinates. In this case, the line thickness is scaled by the medium's current transformation, whereas :normal and :point do not scale the line thickness.

:line-thickness 

line-style-thickness [Generic Function]

Arguments: line-style

Summary: The thickness, in the units indicated by line-style-unit , of the lines or arcs drawn by a drawing function. The thickness must be a real number. The default is 1, which, when combined with the default unit of :normal , means that the default line drawn is the "comfortably visible thin line."

:line-joint-shape 

line-style-joint-shape [Generic Function]

Arguments: line-style

Summary: Specifies the shape of joints between segments of unfilled figures. The possible shapes are :miter , :bevel , :round , and :none ; the default is :miter . Note that the joint shape is implemented by the host window system, so not all platforms will necessarily fully support it.

 
Figure 14. Line Joint Shapes
:line-cap-shape 

line-style-cap-shape [Generic Function]

Arguments: line-style

Summary: Specifies the shape for the ends of lines and arcs drawn by a drawing function, one of :butt , : square , :round , or :no-end-point ; the default is :butt . Note that the cap shape is implemented by the host window system, so not all platforms will necessarily fully support it.

 

Figure 15. Line Cap Shapes
:line-dashes  

line-style-dashes [Generic Function]

Arguments: line-style

Summary: Controls whether lines or arcs are drawn as dashed figures, and if so, what the dashing pattern is. Possible values are:

nil --lines are drawn solid, with no dashing. This is the default.

t --lines are drawn dashed, with a dash pattern that is unspecified and may vary with the rendering engine. This allows the underlying display substrate to provide a default dashed line for the programmer whose only requirement is to draw a line that is visually distinguishable from the default solid line.

A sequence--specifies a sequence, usually a vector, controlling the dash pattern of a drawing function. It is an error if the sequence does not contain an even number of elements. The elements of the sequence are lengths (as real numbers) of individual components of the dashed line or arc. The odd elements specify the length of inked components; the even elements specify the gaps. All lengths are expressed in the units described by line-style-unit .

make-contrasting-dash-patterns [Function]	

Arguments: n &optional k

Summary: If k is not supplied, this returns a vector of n dash patterns with recognizably different appearance. Elements of the vector are guaranteed to be acceptable values for :dashes , and do not include nil , but their class is not otherwise specified. The vector is a fresh object that may be modified.

If k is supplied, it must be an integer between 0 and n -1 (inclusive), in which case make-contrasting-dash-patterns returns the k th dash-pattern rather than returning a vector of dash-patterns.

CLIM has at least 8 different contrasting dash patterns. If n is greater than 8, make-contrasting-dash-patterns signals an error.

contrasting-dash-pattern-limit [Generic Function]

Arguments: port

Summary: Returns the number of contrasting dash patterns that can be rendered on any medium on the port port . It is at least 8. All classes that obey the port protocol implement a method for this generic function.


Common Lisp Interface Manager 2.0 User's Guide - 22 Dec 2009

NextPrevUpTopContentsIndex