In addition to the various layout panes and gadgets, an application usually needs some space to display textual and graphic output as well as to receive application-specific input from the user. For example, a paint program needs a "canvas" pane for displaying the picture and handling "mouse strokes." This can be accomplished in CLIM through the use of extended stream panes.
This section describes the basic CLIM extended 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 is a possible starting place.
CLIM extended stream panes accept the :foreground, :background, and :text-style options as well as those options applicable to layout panes. 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.
In addition to those listed previously, CLIM extended stream frames accept the following options:
:display-after-commands Option
Summary: This specifies how the display function will be run. If t, the "print" part of the read-eval-print loop runs the display function; this is the default for most pane types. If nil, you are responsible for implementing the display after commands.
Do not use :display-after-commands with accept-values panes, as the redisplay for those panes is managed at a slightly lower level for efficiency. Avoid code such as the following:
(in-package :clim-user)
(define-application-frame test-frame () ()
(:command-table (test-frame :inherit-from
(clim:accept-values-pane)))
(:command-definer t)
(:panes
(test-input-pane :accept-values :display-function
'(clim:accept-values-pane-displayer
:displayer test-input)
;; THIS WILL NOT WORK
:display-after-commands t)
(dummy :application)
(menu :command-menu
:display-function '(display-command-menu :n-rows 1))
(mouse :pointer-documentation))
(:layouts (:default
(vertically ()
menu test-input-pane DUMMY mouse))))
(defmethod test-input ((frame test-frame) stream)
(accept 'integer :stream stream :prompt "prompt" :default 1)
(terpri stream)
(accept 'integer :stream stream :prompt "foo" :default 1)
(terpri stream))
(defun test-it (&key (port (find-port)))
(run-frame-top-level
(make-application-frame 'test-frame
:frame-manager
(find-frame-manager :port port))))
Summary: This specifies 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, 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.
Summary: This tells CLIM when the pane's display function should be run. If it is :command-loop, CLIM erases the pane's contents and runs the display function after each time a frame command is executed. If it is t, the pane is displayed once but not again until pane-needs-redisplay is called on the pane. If it is nil, CLIM waits until it is explicitly requested, either via pane-needs-redisplay or redisplay-frame-pane. The default value varies according to the pane type.
Summary: For title-panes only, you can use this option instead of :display-function to specify a constant string to be displayed in the title-pane.
Summary: When t, 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.
Summary: This specifies the default text margin, that is, how much space is left around the inside edge of the pane. The default for :text-margin is the width of the window.
Summary: This specifies the default vertical spacing for the pane, that is, how much space there is between each text line. The default for :vertical-spacing is 2.
Summary: This specifies the end-of-line action to be used. The default is :wrap. (The other possible value is :allow.)
Summary: This specifies the end-of-page action to be used. The default is :scroll. (The other possible value is :allow.)
Summary: This names the output record class to be used for the output history of the pane. The default is standard-tree-output-history.
Summary: These options specify whether the pane should initially allow drawing and output recording, respectively. The default for both options is t.
Summary: This class implements a pane that supports the CLIM graphics, extended input and output, and output recording protocols. Any extended stream panes used will most commonly be subclasses of this class.
The five following panes classes are subclasses of clim-stream-pane. Fundamentally, these panes have the same capabilities; however, by convention, the different pane classes have distinct roles. For instance, interactor panes are used for standard input, whereas application panes, by default, specify the destination for standard output.
Summary: The pane class that implements "interactor" panes. The default method for frame-standard-input will return the first pane of this type.
The default for :display-time is nil and for :scroll-bars is :vertical.
Summary: The pane class that implements "application" panes. The default method for frame-standard-output will return the first pane of this type.
The default for :display-time is :command-loop and for :scroll-bars is t.
Summary: The pane class that implements command menu panes that are not menu bars. The default display function for panes of this type is display-command-menu.
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.
Summary: The pane class that implements a title pane. The default display function for panes of this type is display-title. If the title to be displayed will not change, it can be supplied using the option :display-string described in 10.3.1 Extended Stream Pane Options. If neither :display-function or :display-string is supplied, the title will be taken from frame-pretty-name (see 9.9.1 Finding Frame Managers).
The default for :display-time is t and for :scroll-bars is nil.
pointer-documentation-pane Leaf Pane
Summary: The pane class that implements the pointer documentation pane.
The default for :display-time is nil and for :scroll-bars is nil.
Most CLIM extended stream panes will contain more information than can be displayed in the allocated screen space, so scroll bars are nearly always desirable. CLIM therefore provides a convenient form for creating composite panes that include a CLIM stream pane, scroll bars, labels, and so forth. For window stream pane functions, see 13.7 CLIM Window Stream Pane Functions.
make-clim-stream-pane Function
make-clim-stream-pane &rest options &key type label scroll-bars &allow-other-keys
Summary: Creates a pane of type type, which defaults to clim-stream-pane. If label is supplied, it is a string used to label the pane. 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.
The other options may include all the valid CLIM extended stream pane options.
make-clim-interactor-pane Function
make-clim-interactor-pane &rest options
Summary: Like make-clim-stream-pane, but the type is forced to be interactor-pane.
make-clim-application-pane Function
make-clim-application-pane &rest options
Summary: Like make-clim-stream-pane, but the type is forced to be application-pane.
CLIM 2.0 User Guide - 01 Dec 2021 19:38:58