In addition to the various layout panes and gadgets, an application usually needs some space to display application-specific output and receive application-specific input from the user. For example, a paint program needs a "canvas" pane on which to display the picture and handle the "mouse strokes". An application frame can use the basic CLIM input and output services in an application-specific way through use of a CLIM stream pane. [annotate]
This section describes the basic CLIM stream pane types. Programmers are free to customize pane behavior by defining subclasses of these pane classes writing methods to change the repaint or event-handling behavior. [annotate]
CLIM application frames accept the :foreground, :background, :text-style, and layout pane options. The space requirement options (:width, :height, and so forth) can also take a size specification of :compute, which causes CLIM to run the display function for the pane, and make the pane large enough to hold the output of the display function. [annotate]
In addition to the above, CLIM stream panes accept the following options: [annotate]
This is used to specify a function to be called in order to display the contents of a CLIM stream pane. CLIM's default top level function, default-frame-top-level, function will invoke the pane's display function at the appropriate time (see the :display-time option). The value of this option is either the name of a function to invoke, or a cons whose car is the name of a function and whose cdr is additional arguments to the function. The function will be invoked on the frame, the pane, and the additional function arguments, if any. The default for this option is nil. [annotate] |
This is used to indicate to CLIM when the pane's display function should be run. If it is :command-loop, CLIM will clear the pane and run the display function after each time a frame command is executed. If it is t, the pane will be displayed once and not again until (setf pane-needs-redisplay) is called on the pane. If it is nil, CLIM will never run the display function until it is explicitly requested, either via pane-needs-redisplay or redisplay-frame-pane. The default for this option varies depending on the type of the pane. [annotate] [← 29.4.3 Making CLIM Stream Panes, make-clim-stream-pane] [← 29.4.2 CLIM Stream Pane Classes, pointer-documentation-pane] [← 29.4.2 CLIM Stream Pane Classes, title-pane] [← 29.4.2 CLIM Stream Pane Classes, command-menu-pane] [← 29.4.2 CLIM Stream Pane Classes, application-pane] [← 29.4.2 CLIM Stream Pane Classes, interactor-pane] [← 29.4.1 CLIM Stream Pane Options, :display-function] |
When true, the redisplay function will initially be executed inside of an invocation to updating-output and the resulting output record will be saved. Subsequent calls to redisplay-frame-pane will simply use redisplay to redisplay the pane. The default for this option is nil. [annotate] |
These options specify the default text margin (that is, how much space is left around the inside edge of the pane) and vertical spacing (that is, how much space is between each text line) for the pane. The default for :text-margin is the width of the window, and the default for :vertical-spacing is 2. [annotate] Note: text-margin wording indicates that margin should be split between left edge and right edge what gives us area which is centered to the middle of the pane. text-margin default value wording is confusing - it should be 0 given the first sentence. Width of the window indicates y coordinate of a default right margin vertical line. Would it make sense to add text-left-margin and text-right-margin initargs too? Both would be mutually exclusive with text-margin when supplied together and default to 0. [edit]-- Daniel Kochmanski 2019-01-09 10:11Z |
These options specify the end-of-line and end-of-page actions to be used for the pane. The default for these options are :wrap and :scroll, respectively. [annotate] |
This option names the output record class to be used for the output history of the pane. The default is standard-tree-output-history. [annotate] |
These options specify whether the pane should initially allow drawing and output recording. The default for both options is t. [annotate] |
This class implements a pane that supports the CLIM graphics, extended input and output, and output recording protocols. Most CLIM stream panes will be subclasses of this class. [annotate] |
The pane class that is used to implement "interactor" panes. The default method for frame-standard-input will return the first pane of this type. [annotate] For interactor-pane, the default for :display-time is nil and the default for :scroll-bars is :vertical. [annotate] |
The pane class that is used to implement "application" panes. The default method for frame-standard-output will return the first pane of this type. [annotate] Note: Is there somewhere in the spec where the superclasses of application-pane are listed? In McCLIM, it is a subclass of clim-stream-pane, but it doesn't seem that the spec says that this has to be the case. [edit]-- Cyrus Harmon 2018-08-26 22:01Z For application-pane, the default for :display-time is :command-loop and the default for :scroll-bars is t. [annotate] |
The pane class that is used to implement command menu panes that are not menu bars. The default display function for panes of this type is display-command-menu. [annotate] For command-menu-pane, the default for :display-time is :command-loop, the default for :incremental-redisplay is t, and the default for :scroll-bars is t. [annotate] |
The pane class that is used to implement a title pane. The default display function for panes of this type is display-title. [annotate] For title-pane, the default for :display-time is t and the default for :scroll-bars is nil. [annotate] |
The pane class that is used to implement the pointer documentation pane. [annotate] For pointer-documentation-pane, the default for :display-time is nil and the default for :scroll-bars is nil. [annotate] |
Most CLIM stream panes will contain more information than can be displayed in the allocated space, so scroll bars are nearly always desirable. CLIM therefore provides a convenient form for creating composite panes that include the CLIM stream pane, scroll bars, labels, and so forth. [annotate]
| make-clim-stream-pane | &rest options &key type label label-alignment scroll-bars borders display-after-commands &allow-other-keys | [Function] |
Creates a pane of type type, which defaults to clim-stream-pane. [annotate] If label is supplied, it is a string used to label the pane. label-alignment is as for the labelling macro. [annotate] scroll-bars may be t to indicate that both vertical and horizontal scroll bars should be included, :vertical (the default) to indicate that vertical scroll bars should be included, or :horizontal to indicate that horizontal scroll bars should be included. [annotate] Note: There seems to be some confusion about the :scroll-bars option. If you
compare this to open-window-stream, you see that what is
t here is :both over there. And
open-window-stream also takes nil, while this one
does not. [edit]-- Gilbert Baumman 2005-11-29 10:30Z Note: The Franz User Guide (CLIM 2.2) says that :both is used here as well. I would consider it an oversight in the CLIM spec, and I believe we should use :both as well (though probably also support T with a warning, since most people probably use the CLIM 2.0 spec as their reference). [edit]-- Troels "Athas" Henriksen 2006-12-04 21:37Z If borders is true, the default, a border is drawn around the pane. [annotate] display-after-commands is used to initialize the :display-time property of the pane. It may be t (for :display-time :command-loop), :no-clear (for :display-time :no-clear), or nil (for :display-time nil). [annotate] The other options may include all of the valid CLIM stream pane options. [annotate] |
Like make-clim-stream-pane, except that the type is forced to be interactor-pane. [annotate] |
Like make-clim-stream-pane, except that the type is forced to be application-pane. [annotate] |
The following functions can be called on any pane that is a subclass of clim-stream-pane. (Such a pane is often simply referred to as a window.) These are provided purely as a convenience for programmers. [annotate]
Clears the entire drawing plane by filling it with the background design of the CLIM stream pane window. If window has an output history, that is cleared as well. The text cursor position of window, if there is one, is reset to the upper left corner. [annotate] |
Clears the visible part of the drawing plane of the CLIM stream pane window, and then if the window stream is an output recording stream, the output records in the visible part of the window are replayed. [annotate] |
Returns the viewport region of the CLIM stream pane window. If the window is not scrollable, and hence has no viewport, this will region sheet-region of window. [annotate] Note: This implies two different coordinate systems; the parent's if there's a viewport, otherwise the window's local system. In McCLIM, the related PANE-VIEWPORT-REGION downshifts a found region (which must always be a viewport) to the pane's local system. [edit]-- Michael South 2024-08-10 12:42Z Note: What is "the viewport of the pane"? Are we talking about the direct parent, or any ancestor? For example, what if we have scroller/viewport/vbox/stream-pane? McCLIM walks up the chain, and so finds the viewport. Now the other ambiguity/glitch/foot-gun--which coordinate system should be used--becomes a bigger problem. "If the window is not scrollable" kind of implies we should only look at the direct parent. [edit]-- Michael South 2024-08-10 13:01ZThe returned region will generally be a standard-bounding-rectangle. [annotate] |
Clears the visible part of the drawing plane of the CLIM stream pane window by filling it with the background design. [annotate] |
Returns two values, the x and y position of the top-left corner of the CLIM stream pane window's viewport. If the window is not scrollable, this will return the two values 0 and 0. [annotate] |
Sets the position of the CLIM stream pane window's viewport to x and y. If the window is not scrollable, this will do nothing. [annotate] For CLIM implementations that do not support setf*, the "setter" function for this is window-set-viewport-position. [annotate] |
The following function can be used to create a standalone window that obeys CLIM's extended input and output stream and output recording protocols. [annotate]
| open-window-stream | &key port left top right bottom width height foreground background text-style (vertical-spacing 2) end-of-line-action end-of-page-action output-record (draw t) (record t) (initial-cursor-visibility :off) text-margin save-under input-buffer (scroll-bars :vertical) borders label | [Function] |
Creates and returns a sheet that can be used as a standalone window that obeys CLIM's extended input and output stream and output recording protocols. [annotate] The window will be created on the port port at the position specified by left and top, which default to 0. right, bottom, width, and height default in such a way that the default width will be 100 and the default height will be 100. [annotate] foreground, background, and text-style are used to specify the window's default foreground and background inks, and text style. vertical-spacing, text-margin, end-of-line-action, end-of-page-action, output-record, draw, and record are described in Section 29.4.1. [annotate] scroll-bars specifies whether scroll bars should be included in the resulting window. It may be one of nil, :vertical (the default), :horizontal, or :both. [annotate] borders is a booleans that specifies whether or not the resulting window should have a border drawn around it. The default is t. label is either nil or a string to use as a label for the window. [annotate] initial-cursor-visibility is used to specify whether the window should have a text cursor. :off (the default) means to make the cursor visible if the window is waiting for input. :on means to make the cursor visible immediately. nil means the cursor will not be visible at all. [annotate] When save-under is true, the result window will be given a "bit save array". The default is nil. [annotate] If input-buffer is supplied, it is an input buffer or event queue to use for the resulting window. Programmers will generally supply this when they want the new window to share its input buffer with an existing application. The default is to create a new input buffer. [annotate] Note: Mixing input-buffers and event-queues here is not helpful. Event queues are for sheets while input buffers are for streams. Former may insert to the latter. [edit]-- Daniel Kochmanski 2019-06-21 12:25Z |