cg-stream

The class of all Common Graphics streams, which include windows, menus, bitmap-streams, printer streams, and the screen (see screen). These objects are instances of the Common Lisp stream class (specifically of the simple-stream class) because, like other output streams, these objects are opened and closed, and a stream of output may be written to them while they are open (and only then). (An exception is that stream output may not be written to a menu, but it still is usable only while it is open.)

While conventional streams deal with a one-dimensional sequence of characters or bytes, most cg-streams deal with two-dimensional graphical output. This output is still ordered in time though, and therefore can still be thought of as a flowing stream of graphical output.

In addition to using Common Graphics drawing functions such as draw-line and copy-to-stream to draw on cg-streams, the text output functions of Common Lisp such as print and format may also be used to draw text to a cg-stream. These functions will draw at the current-position of the stream and update the current-position to the end of the text. Text is simply one kind of graphical output that may be sent to a cg-stream.

All windows and the screen are always interactive streams (see interactive-stream-p), not because the user may prompt for stream input in them, but because output to these streams is often intended to be visible to the user immediately in interactive user interfaces. Since interactive streams always call force-output automatically after each call to text output functions, it should never be necessary for an application to call force-output or finish-output on a window or the screen. For other cg-streams, all of the Common Graphics graphical drawing functions will do a force-output just before they do their drawing, and so it should not be necessary to call force-output or finish-output between drawing Common Lisp text output and drawing Common Graphics graphical output to the same cg-stream in order to ensure that everything is drawn in the correct order.

The text-edit-pane (along with its subclasses such as rich-edit-pane) is the only cg-stream class that can do input. This window is actually a control. It is usually used only for text input and output, as a file stream might be used, but arbitrary graphical drawing may also be done to it as well. (Being a control, graphical output to a text-edit-pane must be surrounded by a call to with-device-context.)

A diagram of window and widget classes is shown in Widget and window classes 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.