15.4 Text Protocol

  • 15.4.1 Mixing Text and Graphics
  • 15.4.2 Wrapping of Text Lines
  • The following generic functions comprise the text protocol. Any extended output stream class must implement methods for these generic functions. [annotate]

    stream-character-width  stream character &key text-style [Generic Function]
              

    Returns a rational number corresponding to the amount of horizontal motion of the cursor position that would occur if the character character were output to the extended output stream stream in the text style text-style (which defaults to the current text style for the stream). This ignores the stream's text margin. [annotate]

    [annotate]

    stream-string-width  stream character &key start end text-style [Generic Function]
              

    Computes how the cursor position would move horizontally if the string string were output to the extended output stream stream in the text style text-style (which defaults to the current text style for the stream) starting at the left margin. This ignores the stream's text margin. [annotate]

    The first returned value is the x coordinate that the cursor position would move to. The second returned value is the maximum x coordinate the cursor would visit during the output. (This is the same as the first value unless the string contains a #\Newline character.) [annotate]

    start and end are integers, and default to 0 and the length of the string, respectively. [annotate]

    [annotate]

    Note: Arguments probably should be "stream string &key start end text-style" -- tztztz, this copy and paste bookwriting style [edit]-- Deliana Foutekova 2005-11-21 19:09Z
     

    stream-text-margin  stream [Generic Function]
    (setf stream-text-margin)  margin stream [Generic Function]
              

    The x coordinate at which text wraps around on the extended output stream stream (see stream-end-of-line-action). The default setting is the width of the viewport, which is the right-hand edge of the viewport when it is horizontally scrolled to the "initial position". [annotate]

    You can use setf with stream-text-margin to establish a new text margin. If margin is nil, then the width of the viewport will be used. If the width of the viewport is later changed, the text margin will change, too. [annotate]

    [annotate]

    Note: For output backends (like postscript) stream may have no viewport and stream's region may be +everywhere+ – that means in particular, that width is infinite and there is no margin. [edit]-- Daniel Kochmanski 2018-10-31 07:29Z
     

    stream-line-height  stream &key text-style [Generic Function]
              

    Returns what the line height of a line on the extended output stream stream containing text in the text style text-style would be, as a rational number. The height of the line is measured from the baseline of the text style to its ascent. text-style defaults to the current text style for the stream. [annotate]

    [annotate]

    stream-vertical-spacing  stream [Generic Function]
              

    Returns the current inter-line spacing (as a rational number) for the extended output stream stream. [annotate]

    [annotate]

    stream-baseline  stream [Generic Function]
              

    Returns the current text baseline (as a rational number) for the extended output stream stream. [annotate]

    [annotate]

    15.4.1 Mixing Text and Graphics

    The following macro provides a convenient way to mix text and graphics on the same output stream. [annotate]

    with-room-for-graphics  (&optional stream &key (first-quadrant t) height (move-cursor t) record-type) &body body [Macro]
              

    Binds the dynamic environment to establish a local coordinate system for doing graphics output onto the extended output stream designated by stream. If first-quadrant is true (the default), a local Cartesian coordinate system is established with the origin (0,0) of the local coordinate system placed at the current cursor position; (0,0) is in the lower left corner of the area created. If the boolean move-cursor is true (the default), then after the graphic output is completed, the cursor is positioned past (immediately below) this origin. The bottom of the vertical block allocated is at this location (that is, just below point (0,0), not necessarily at the bottom of the output done). [annotate]

    The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t (the default), *standard-output* is used. body may have zero or more declarations as its first forms. [annotate]

    If height is supplied, it must be a rational number that specifies the amount of vertical space to allocate for the output, in device units. If it is not supplied, the height is computed from the output. [annotate]

    record-type specifies the class of output record to create to hold the graphical output. The default is standard-sequence-output-record. [annotate]

    [annotate]

    15.4.2 Wrapping of Text Lines

    stream-end-of-line-action  stream [Generic Function]
    (setf stream-end-of-line-action)  action stream [Generic Function]
              

    The end-of-line action controls what happens if the text cursor position moves horizontally out of the viewport, or if text output reaches the text margin. (By default the text margin is the width of the viewport, so these are usually the same thing.) [annotate]

    stream-end-of-line-action returns the end-of-line action for the extended output stream stream. It can be changed by using setf on stream-end-of-line-action. [annotate]

    The end-of-line action is one of: [annotate]

    • :wrap---when doing text output, wrap the text around (that is, break the text line and start another line). When setting the cursor position, scroll the window horizontally to keep the cursor position inside the viewport. This is the default. [annotate]
    • :scroll---scroll the window horizontally to keep the cursor position inside the viewport, then keep doing the output. [annotate]
    • :allow---ignore the text margin and do the output on the drawing plane beyond the visible part of the viewport. [annotate]

    [annotate]

    with-end-of-line-action  (stream action) &body body [Macro]
              

    Temporarily changes stream's end-of-line action for the duration of execution of body. action must be one of the actions described in stream-end-of-line-action. [annotate]

    The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t, *standard-output* is used. body may have zero or more declarations as its first forms. [annotate]

    [annotate]

    stream-end-of-page-action  stream [Generic Function]
    (setf stream-end-of-page-action)  action stream [Generic Function]
              

    The end-of-page action controls what happens if the text cursor position moves vertically out of the viewport. [annotate]

    stream-end-of-page-action returns the end-of-page action for the extended output stream stream. It can be changed by using setf on stream-end-of-page-action. [annotate]

    The end-of-page action is one of: [annotate]

    • :scroll---scroll the window vertically to keep the cursor position inside the viewport, then keep doing output. This is the default. [annotate]
    • :allow---ignore the viewport and do the output on the drawing plane beyond the visible part of the viewport. [annotate]
    • :wrap---when doing text output, wrap the text around (that is, go back to the top of the viewport). [annotate]

    [annotate]

    Note:

    Wow, :WRAP end-of-page-action seems useless. I can't think of a single practical purpose of it.

    Maybe it should clean the viewport? Then it would be a "modulo" output sort of thing. In that case it could pause waiting for user key press like on ITS (according to Elias).

    Or maybe it is specified with vertical text in mind?

    Also, there should be note-stream-end-of-page (in that case programmer could implement desired behavior themselves).

    [edit]-- Daniel Kochmanski 2019-01-08 11:04Z
     

    with-end-of-page-action  (stream action) &body body [Macro]
              

    Temporarily changes stream's end-of-page action for the duration of execution of body. action must be one of the actions described in stream-end-of-page-action. [annotate]

    The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t, *standard-output* is used. body may have zero or more declarations as its first forms. [annotate]

    [annotate]