Generic Function | Package: cg | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 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:

- 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.
- no-clip: if true, then the string is not clipped as usual at the edges of the specified box, and so the string will extend off the right or bottom edge of the box if it is too long to fit within the box. Even if the general non-clipping behavior is not a problem, using this option may also be useful for avoiding an apparent Windows glitch where part an uppercase W will be clipped off the left edge of the box in certain fonts.

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-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version