draw-string-in-box

Generic Function

Package: common-graphics

Arguments: stream string start end box horizontal-justification vertical-justification &optional string-vertical-p wrap-p calculate-height

If calculate-height is nil (the default), this function draws all or part of string in box on stream with the specified formatting options. The string is clipped as necessary to prevent it from extending outside the box. The string is wrapped at spaces if wrap-p is true. See below for more information on wrap-p. This function returns the height of the wrapped text that was drawn, in pixels. This value is useful when the wrap-p argument is true, since it is hard to predict how many lines of text will result from the wrapping.

If calculate-height is specified true, then the text is not drawn, but the height necessary if it were drawn is returned. This information may be useful for determining how much space is needed to draw particular pieces of text.

The start and end arguments specify the starting and ending locations of the portion of the string to be drawn. These are not optional arguments. The values must be non-negative integers or nil. To get the whole string drawn, specify 0 or nil and (length string) or nil as the values.

box should be a box object (as made with make-box). It denotes the rectangular region of the stream into which to fit the string.

The remaining arguments are as follows:

horizontal-justification can be one of :left, :right, :center, :fill. Any other value (including nil) is taken to mean :left. If :fill, then the wrap-p argument is coerced to nil and extra space is added at the space characters in the string to stretch the string as a single line of text to fill the entire width of the specified box.

vertical-justification can be one of :top, :bottom, :center. Any other value (including nil) is taken to mean :top. If the wrap-p optional argument is specified and true, vertical-justification is :top regardless of what value is specified.

string-vertical-p: the functionality associated with this argument is unimplemented and the value is ignored.

wrap-p: this optional argument is a Boolean which specifies whether text should be wrapped in the box. If specified true, then the string will be wrapped (at space characters) into multiple lines, each fitting horizontally into the specified box. All wrapping occurs at spaces. When this argument is true, vertical-justification is :top (regardless of what is specified). Note that newline characters in string always cause a wrap to the next line whatever the value of wrap-p.

Each character printed can be surrounded by a rectangle large enough to contain the character. When a character is printed, what should happen to this surrounding rectangle? There are two choices: it should be colored in with the window background-color, or it should be untouched, so that only the pixels associated with the character itself are modified. See See transparent-character-background for information on how the background pixels of each character cell are drawn.

Note: incompatible change in release 6.0: in releases prior to 6.0, when a frame-with-single-child instance was passed to this operator, the operator was actually applied to the child (the result of applying frame-child to the frame-with-single-child instance). In release 6.0, this redirection no longer occurs. If you intend this operator to apply to the frame-child, pass that to this operator rather than the parent. This is a non-backward-compatible-change. See the release notes for more information.

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.