| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
Arguments: stream string start end box horizontal-justification vertical-justification &optional string-vertical-p wrap-p calculate-height no-clip
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.
stream
should be a cg-stream
.
The remaining arguments are as follows:
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 transparent-character-background for information on how the background pixels of each character cell are drawn.
An alternative to draw-string-in-box is to call Common Lisp stream output functions such as format or princ, which work on Common Graphics windows and other graphical-streams because they are set up as lisp streams. These functions will position the upper-left corner of the string at the current-position of the stream. In particular, draw-string-in-box is not suitable when the current font of the stream has a non-zero font-angle, because the text will be rotated about its upper-left corner and will therefore extend outside the specified box. If you call the lower-level functions write-string, write-char, and write-sequence on a Common Graphics stream, then you should call force-output or finish-output before subsequently calling any graphics-related functions; see the note at the end of Common Graphics Streams in cgide.htm.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |