29.4 CLIM Stream Panes

  • 29.4.1 CLIM Stream Pane Options
  • 29.4.2 CLIM Stream Pane Classes
  • 29.4.3 Making CLIM Stream Panes
  • 29.4.4 CLIM Stream Pane Functions
  • 29.4.5 Creating a Standalone CLIM Window
  • 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]

    29.4.1 CLIM Stream Pane Options

    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]

    Note: surely "CLIM stream panes", not "CLIM application frames", accept these arguments. [edit]-- DK 2023-07-28 12:43Z
     

    In addition to the above, CLIM stream panes accept the following options: [annotate]

    :display-function   [Option]
              

    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]

    [annotate]

    :display-time   [Option]
              

    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]

    [annotate]

    :incremental-redisplay   [Option]
              

    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]

    [annotate]

    :text-margin   [Option]
    :vertical-spacing   [Option]
              

    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
     

    [annotate]

    :end-of-line-action   [Option]
    :end-of-page-action   [Option]
              

    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]

    [annotate]

    :output-record   [Option]
              

    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]

    [annotate]

    :draw   [Option]
    :record   [Option]
              

    These options specify whether the pane should initially allow drawing and output recording. The default for both options is t. [annotate]

    [annotate]

    29.4.2 CLIM Stream Pane Classes

    clim-stream-pane   [Service Pane]
              

    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]

    [annotate]

    interactor-pane   [Service Pane]
              

    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]

    [annotate]

    application-pane   [Service Pane]
              

    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]

    [annotate]

    command-menu-pane   [Service Pane]
              

    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]

    [annotate]

    title-pane   [Service Pane]
              

    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]

    [annotate]

    pointer-documentation-pane   [Service Pane]
              

    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]

    [annotate]

    29.4.3 Making CLIM Stream Panes

    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]

    [annotate]

    make-clim-interactor-pane  &rest options [Function]
              

    Like make-clim-stream-pane, except that the type is forced to be interactor-pane. [annotate]

    [annotate]

    make-clim-application-pane  &rest options [Function]
              

    Like make-clim-stream-pane, except that the type is forced to be application-pane. [annotate]

    [annotate]

    29.4.4 CLIM Stream Pane Functions

    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]

    window-clear  window [Generic Function]
              

    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]

    [annotate]

    window-refresh  window [Generic Function]
              

    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]

    [annotate]

    window-viewport  window [Generic Function]
              

    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]

    The returned region will generally be a standard-bounding-rectangle. [annotate]

    [annotate]

    window-erase-viewport  window [Generic Function]
              

    Clears the visible part of the drawing plane of the CLIM stream pane window by filling it with the background design. [annotate]

    [annotate]

    window-viewport-position  window [Generic Function]
              

    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]

    [annotate]

    (setf* window-viewport-position)  x y window [Generic Function]
              

    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]

    [annotate]

    29.4.5 Creating a Standalone CLIM Window

    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]

    Note: Please see comment for make-clim-stream-pane. [edit]-- Gilbert Baumann 2005-11-29 10:32Z
     

    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
     

    [annotate]