28.3 Application Frame Functions

  • 28.3.1 Interface with Presentation Types
  • The generic functions described in this section are the functions that can be used to read or modify the attributes of a frame. All classes that inherit from application-frame must inherit or implement methods for all of these functions. [annotate]

    frame-name  frame [Generic Function]
              

    Returns the name of the frame frame, which is a symbol. [annotate]

    [annotate]

    frame-pretty-name  frame [Generic Function]
              

    Returns the "pretty name" of the frame frame, which is a string. [annotate]

    [annotate]

    (setf frame-pretty-name)  name frame [Generic Function]
              

    Sets the pretty name of the frame frame to name, which must be a string. Changing the pretty name of a frame notifies its frame manager, which in turn may change some aspects of the appearance of the frame, such as its title bar. [annotate]

    [annotate]

    frame-command-table  frame [Generic Function]
              

    Returns the command table for the frame frame. [annotate]

    [annotate]

    (setf frame-command-table)  command-table frame [Generic Function]
              

    Sets the command table for the frame frame to command-table. Changing the frame's command table will redisplay the command menus (or menu bar) as needed. command-table is a command table designator. [annotate]

    [annotate]

    frame-standard-output  frame [Generic Function]
              

    Returns the stream that will be used for *standard-output* for the frame frame. The default method (on standard-application-frame) returns the first named pane of type application-pane that is visible in the current layout; if there is no such pane, it returns the first pane of type interactor-pane that is exposed in the current layout. [annotate]

    [annotate]

    Note:

    What do we mean by *first named pane*? Are we talking about the order mandated by a definition time (i.e in `:PANES'), or the order of putting things on the display (i.e which it is in the current layout in `:LAYOUTS')?

    McCLIM takes the former interpretation, that is "First defined pane of type ... that is visible in the current layout", because it seems more intuitive (to me:).

    [edit]-- Daniel Kochmanski 2016-11-30 16:23Z
     

    frame-standard-input  frame [Generic Function]
              

    Returns the stream that will be used for *standard-input* for the frame frame. The default method (on standard-application-frame) returns the first named pane of type interactor-pane that is visible in the current layout; if there is no such pane, the value returned by frame-standard-output is used. [annotate]

    [annotate]

    frame-query-io  frame [Generic Function]
              

    Returns the stream that will be used for *query-io* for the frame frame. The default method (on standard-application-frame) returns the value returned by frame-standard-input; if that is nil, it returns the value returned by frame-standard-output. [annotate]

    [annotate]

    frame-error-output  frame [Generic Function]
              

    Returns the stream that will be used for *error-output* for the frame frame. The default method (on standard-application-frame) returns the same value as frame-standard-output. [annotate]

    [annotate]

    *pointer-documentation-output*   [Variable]
              

    This will be bound either to nil or to a stream on which pointer documentation will be displayed. [annotate]

    [annotate]

    frame-pointer-documentation-output  frame [Generic Function]
              

    Returns the stream that will be used for *pointer-documentation-output* for the frame frame. The default method (on standard-application-frame) returns the first pane of type pointer-documentation-pane. If this returns nil, no pointer documentation will be generated for this frame. [annotate]

    [annotate]

    frame-calling-frame  frame [Generic Function]
              

    Returns the application frame that invoked the frame frame. [annotate]

    [annotate]

    frame-parent  frame [Generic Function]
              

    Returns the object that acts as the parent for the frame frame. This often, but not always, returns the same value as frame-manager. [annotate]

    [annotate]

    frame-panes  frame [Generic Function]
              

    Returns the pane that is the top-level pane in the current layout of the frame frame's named panes. This will typically be some sort of a layout pane. [annotate]

    [annotate]

    Note: As hinted in generate-panes this should be setf-able (probably an ommision). [edit]-- DK 2016-12-23 16:31Z
     

    frame-top-level-sheet  frame [Generic Function]
              

    Returns the sheet that is the top-level sheet for the frame frame. This is the sheet that has as its descendents all of the panes of frame. [annotate]

    The value returned by frame-panes will be a descendents of the value of frame-top-level-sheet. [annotate]

    [annotate]

    frame-current-panes  frame [Generic Function]
              

    Returns a list of those named panes in the frame frame's current layout. If there are no named panes (for example, the :pane option was used), only the single, top level pane is returned. This function returns objects that reveal CLIM's internal state; do not modify those objects. [annotate]

    [annotate]

    get-frame-pane  frame pane-name [Generic Function]
              

    Returns the named CLIM stream pane in the frame frame whose name is pane-name. [annotate]

    [annotate]

    find-pane-named  frame pane-name [Generic Function]
              

    Returns the pane in the frame frame whose name is pane-name. This can return any type of pane, not just CLIM stream panes. [annotate]

    [annotate]

    Note: Nothing is said about what happens if a name is given that does not correspond to any pane. [edit]-- Robert Strandh 2016-09-01 08:43Z
     
    Note: Does it impose any problem? I'd assume that in such case it behaves like FIND – returns NIL. FWIW that's what McCLIM does. [edit]-- Daniel Kochmanski 2016-11-28 12:27Z
     

    frame-current-layout  frame [Generic Function]
              

    Returns the current layout for the frame frame. The layout is named by a symbol. [annotate]

    [annotate]

    (setf frame-current-layout)  layout frame [Generic Function]
              

    Sets the layout of the frame frame to be the new layout specified by new-layout. layout must be a symbol that names one of the possible layouts. [annotate]

    Changing the layout of the frame must recompute what panes are used for the bindings of the standard stream variables (such as *standard-input*). Some implementations of CLIM may cause the application to "throw" all the way back to run-frame-top-level in order to do this. After the new layout has been computed, the contents of each of the panes must be displayed to the degree necessary to ensure that all output is visible. [annotate]

    [annotate]

    frame-all-layouts  frame [Generic Function]
              

    Returns a list of the names of all of the possible layouts for the frame. [annotate]

    [annotate]

    layout-frame  frame &optional width height [Generic Function]
              

    Resizes the frame and lays out the current pane hierarchy using the layout specified by frame-current-layout, according to the layout protocol. The basics of the layout protocols are described in Section 29.3.4. This function is automatically invoked on a frame when it is adopted, after its pane hierarchy has been generated. [annotate]

    Note: Well, if the pane _hierarchy_ is already generated, the reference to frame-current-layout is superfluous. [edit]-- Gilbert Baumann 2017-07-28 17:11Z
     

    If width and height are provided, then this function resizes the frame to the specified size. It is an error to provide just width. [annotate]

    If no optional arguments are provided, this function resizes the frame to the preferred size of the top-level pane as determined by the space composition pass of the layout protocol. [annotate]

    In either case, after the frame is resized, the space allocation pass of the layout protocol is invoked on the top-level pane. [annotate]

    [annotate]

    frame-exit   [Condition]
              

    The condition that is signalled when frame-exit is called. This condition will handle the :frame initarg, which is used to supply the frame that is being exited from. [annotate]

    [annotate]

    frame-exit-frame  condition [Generic Function]
              

    Returns the frame that is being exited from associated with the frame-exit condition. [annotate]

    [annotate]

    frame-exit  frame [Generic Function]
              

    Exits from the frame frame. The default method (on standard-application-frame) signals a frame-exit condition, supplying frame as the :frame initarg. [annotate]

    [annotate]

    pane-needs-redisplay  pane [Generic Function]
              

    Returns two values, the first indicating whether the pane pane needs to be redisplayed, and the second indicating whether the pane needs to be cleared before being redisplayed. The first value is true when the pane is to be redisplayed. The second value is true when the pane is to be cleared. [annotate]

    [annotate]

    (setf pane-needs-redisplay)  value pane [Generic Function]
              

    Indicates that the pane pane should (or should not) be redisplayed the next time the owning frame executes the redisplay part of its command loop. [annotate]

    When value is nil, the pane will not require redisplay. When value is t, the pane will be cleared and redisplayed exactly once. When value is :command-loop, the pane will be cleared and redisplayed in each successive pass through the command loop. When value is :no-clear, the pane will be redisplayed exactly once without clearing it. [annotate]

    [annotate]

    redisplay-frame-pane  frame pane &key force-p [Generic Function]
              

    Causes the pane pane within the frame frame to be redisplayed immediately. pane is either a pane or the name of a named pane. When the boolean force-p is true, the maximum level of redisplay is forced (that is, the pane is displayed "from scratch"). [annotate]

    [annotate]

    redisplay-frame-panes  frame &key force-p [Generic Function]
              

    redisplay-frame-panes causes all of the panes in the frame frame to be redisplayed immediately by calling redisplay-frame-pane on each of the panes in frame that are visible in the current layout. When the boolean force-p is true, the maximum level of redisplay is forced (that is, the pane is displayed "from scratch"). [annotate]

    [annotate]

    Note:

    (previous annotation: It looks to me like redisplay-frame-panes should check whether the pane needs redisplay before calling redisplay-frame-pane)

    I take that back. The wording in the description of REDISPLAY-FRAME-PANES is very similar to that of REDISPLAY-FRAME-PANE, so I don't think it is reasonable to have REDISPLAY-FRAME-PANES check such things first.

    The only conclusion possible is that the default command loop does not call REDISPLAY-FRAME-PANES and instead uses a different mechanism. Re-reading the description of the default command loop confirms this impression. Nowhere in that description is a call to REDISPLAY-FRAME-PANES mentioned.

    [edit]-- Robert Strandh 2017-05-04 2017-05-07 18:18Z
     

    frame-replay  frame stream &optional region [Generic Function]
              

    Replays the contents of stream in the frame frame within the region specified by the region region, which defaults to viewport of stream. [annotate]

    [annotate]

    notify-user  frame message &key associated-window title documentation exit-boxes name style text-style [Generic Function]
              

    Notifies the user of some event on behalf of the frame frame. message is a message string. This function provides a look and feel independent way for applications to communicate messages to the user. [annotate]

    associated-window is the window with which the notification will be associated, as it is for menu-choose. title is a title string to include in the notification. text-style is the text style in which to display the notification. exit-boxes is as for accepting-values; it indicates what sort of exit boxes should appear in the notification. style is the style in which to display the notification, and is implementation-dependent. [annotate]

    [annotate]

    frame-properties  frame property [Generic Function]
    (setf frame-properties)  value frame property [Generic Function]
              

    Frame properties can be used to associate frame specific data with frames without adding additional slots to the frame's class. CLIM may use frame properties internally to store information for its own purposes. [annotate]

    [annotate]

    28.3.1 Interface with Presentation Types

    This section describes the functions that connect application frames to the presentation type system. All classes that inherit from application-frame must inherit or implement methods for all of these functions. [annotate]

    frame-maintain-presentation-histories  frame [Generic Function]
              

    Returns true if the frame frame maintains histories for its presentations, otherwise returns false. The default method (on standard-application-frame) returns true if and only if the frame has at least one interactor pane. [annotate]

    [annotate]

    frame-find-innermost-applicable-presentation  frame input-context stream x y &key event [Generic Function]
              

    Locates and returns the innermost applicable presentation on the window stream whose sensitivity region contains the point (x,y), on behalf of the frame frame in the input context input-context. event defaults to nil, and is as for find-innermost-applicable-presentation [annotate]

    The default method (on standard-application-frame) will simply call find-innermost-applicable-presentation. [annotate]

    [annotate]

    frame-input-context-button-press-handler  frame stream button-press-event [Generic Function]
              

    This function is responsible for handling user pointer events on behalf of the frame frame in the input context *input-context*. stream is the window on which button-press-event took place. [annotate]

    The default implementation (on standard-application-frame) unhighlights any highlighted presentations, finds the applicable presentation by calling frame-find-innermost-applicable-presentation-at-position, and then calls throw-highlighted-presentation to execute the translator on that presentation that corresponds to the user's gesture. [annotate]

    If frame-input-context-button-press-handler is called when the pointer is not over any applicable presentation, throw-highlighted-presentation must be called with a presentation of *null-presentation*. [annotate]

    [annotate]

    frame-document-highlighted-presentation  frame presentation input-context window x y stream [Generic Function]
              

    This function is responsible for producing pointer documentation on behalf of the frame frame in the input context input-context on the window window at the point (x,y). The documentation is displayed on the stream stream. [annotate]

    The default method (on standard-application-frame) should produce documentation that corresponds to calling document-presentation-translator on all of the applicable translators in the input context input-context. presentation, window, x, y, and stream are as for document-presentation-translator. [annotate]

    Typically pointer documentation will consist of a brief description of each translator that is applicable to the specified presentation in the specified input context given the current modifier state for the window. For example, the following documentation might be produced when the pointer is pointing to a Lisp expression when the input context is form: [annotate]

    Left: '(1 2 3); Middle: (DESCRIBE '(1 2 3)); Right: Menu
    

    [annotate]

    frame-drag-and-drop-feedback  frame presentation stream initial-x initial-y new-x new-y state [Generic Function]
              

    The default feedback function for translators defined by define-drag-and-drop-translator, which provides visual feedback during the dragging phase of such translators on behalf of the frame frame. presentation is the presentation being dragged on the stream stream. The pointing device was initially at the position specified by initial-x and initial-y, and is at the position specified by new-x and new-y when frame-drag-and-drop-feedback is invoked. (Both positions are supplied for "rubber-banding", if that is the sort of desired feedback.) state will be either :highlight, meaning that the feedback should be drawn, or :unhighlight, meaning that the feedback should be erased. [annotate]

    [annotate]

    Note: I have a small question for you [edit]-- Olaf 2021-06-26 22:29Z
     

    frame-drag-and-drop-highlighting  frame presentation stream state [Generic Function]
              

    The default highlighting function for translators defined by define-drag-and-drop-translator, which is invoked when a "to object" should be highlighted during the dragging phase of such translators on behalf of the frame frame. presentation is the presentation over which the pointing device is located on the stream stream. state will be either :highlight, meaning that the highlighting for the presentation should be drawn, or :unhighlight, meaning that the highlighting should be erased. [annotate]

    [annotate]