Generic FunctionPackage: cgToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.2
Unrevised from 8.1 to 8.2.
8.1 version

draw-string-in-box

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.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.2
Unrevised from 8.1 to 8.2.
8.1 version