28.5 Frame Managers

  • 28.5.1 Finding Frame Managers
  • 28.5.2 Frame Manager Operations
  • 28.5.3 Frame Manager Settings
  • Frames may be adopted by a frame manager, which involves invoking a protocol for generating the pane hierarchy of the frame. This protocol provides for selecting pane types for abstract gadget panes based on the style requirements imposed by the frame manager. That is, the frame manager is responsible for the "look and feel" of a frame. [annotate]

    [adopted, Concept← A Glossary]

    After a frame is adopted it can be in any of the three following states: enabled, disabled, or shrunk. An enabled frame is visible unless it is occluded by other frames or the user is browsing outside of the portion of the frame manager's space that the frame occupies. A shrunken frame provides a cue or handle for the frame, but generally will not show the entire contents of the frame. For example, the frame may be iconified or an item for the frame may be placed in a special suspended frame menu. A disabled frame is not visible, nor is there any user accessible handle for enabling the frame. [annotate]

    [enabled, Concept← A Glossary]

    Frames may also be disowned, which involves releasing the frame's panes as well as all associated foreign resources. [annotate]

    frame-manager   [Protocol Class]

    The protocol class that corresponds to a frame manager. If you want to create a new class that behaves like a frame manager, it should be a subclass of frame-manager. All instantiable subclasses of frame-manager must obey the frame manager protocol. [annotate]

    There are no advertised standard frame manager classes. Each port will implement one or more frame managers that correspond to the look and feel for the port. [annotate]


    frame-mananger-p  object [Protocol Predicate]

    Returns true if object is a frame manager, otherwise returns false. [annotate]


    28.5.1 Finding Frame Managers

    Most frames need only deal directly with frame managers to the extent that they need to find a frame manager into which they can insert themselves. Since frames will usually be invoked by some user action that is handled by some frame manager, finding an appropriate frame manager is usually straightforward. [annotate]

    Some frames will support the embedding of other frames within themselves. Such frames would not only use frames but also act as frame managers, so that other frames could insert frames. In this case, the embedded frames are mostly unaware that they are nested within other frames, but only know that they are controlled by a particular frame manager. [annotate]

    Minor issue: How does one write a frame that supports an embedded frame, such as an editor frame within a documentation-writing frame? --- SWM [annotate]

    The find-frame-manager function provides a flexible means for locating an frame manager to adopt an application's frames into. There are a variety of ways that the user or the application can influence where an application's frame is adopted. [annotate]

    An application can establish an application default frame manager using with-frame-manager. A frame's top-level loop automatically establishes the frame's frame manager. [annotate]

    The programmer or user can influence what frame manager is found by setting *default-frame-manager* or *default-server-path*. [annotate]

    Each frame manager is associated with one specific port. However, a single port may have multiple frame managers managing various frames associated with the port. [annotate]

    find-frame-manager  &rest options &key port &allow-other-keys  [Function]

    Finds an appropriate frame manager that conforms to the options, including the port argument. Furthermore, CLIM applications may set up dynamic contexts that affect what find-frame-manager will return. [annotate]

    port defaults to the value returned by find-port applied to the remaining options. [annotate]

    A frame manager is found using the following rules in the order listed: [annotate]

    1. If a current frame manager has been established via an invocation of with-frame-manager, as is the case within a frame's top-level, and that frame manager conforms to the options, it is returned. The exact definition of "conforming to the options" varies from one port to another, but it may include such things as matching the console number, color or resolution properties, and so forth. If the options are empty, then any frame manager will conform. [annotate]
    2. If *default-frame-manager* is bound to a currently active frame manager and it conforms to the options, it is returned. [annotate]
    3. If port is nil, a port is found and an appropriate frame manager is constructed using *default-server-path*. [annotate]


    *default-frame-manager*   [Variable]

    This variable provides a convenient point for allowing a programmer or user to override what frame manager type would normally be selected. Most users will not set this variable since they can set *default-server-path* to indicate which host window system they want to use and are willing to use whatever frame manager is the default for the particular port. However, some users may want to use a frame manager that isn't the typical frame manager. For example, a user may want to use both an OpenLook frame manager and a Motif frame manager on a single port. [annotate]


    with-frame-manager  (frame-manager) &body body [Macro]

    Generates a dynamic context that causes all calls to find-frame-manager to return frame-manager if the where argument passed to it conforms to frame-manager. Nested calls to with-frame-manager will shadow outer contexts. body may have zero or more declarations as its first forms. [annotate]


    28.5.2 Frame Manager Operations

    frame-manager  frame [Generic Function]

    Returns the current frame manager of frame if it is adopted, otherwise returns nil. [annotate]


    (setf frame-manager)  frame-manager frame [Generic Function]

    Changes the frame manager of frame to frame-manager. In effect, the frame is disowned from its old frame manager and is adopted into the new frame manager. Transferring a frame preserves its frame-state, for example, if the frame was previously enabled it will be enabled in the new frame manager. [annotate]


    frame-manager-frames  frame-manager [Generic Function]

    Returns a list of all of the frames being managed by frame-manager. This function returns objects that reveal CLIM's internal state; do not modify those objects. [annotate]


    adopt-frame  frame-manager frame [Generic Function]
    disown-frame  frame-manager frame [Generic Function]

    These functions insert or remove a frame from a frame manager's control. These functions allow a frame manager to allocate and deallocate resources associated with a frame. For example, removing a frame from a frame manager that is talking to a remote server allows it to release all remote resources used by the frame. [annotate]


    port  (frame standard-application-frame) [Method]

    If frame has been adopted by a frame manager, this returns the port with which frame is associated. Otherwise it returns nil. [annotate]


    frame-state  frame [Generic Function]

    Returns one of :disowned, :enabled, :disabled, or :shrunk, indicating the current state of frame. [annotate]


    enable-frame  frame [Generic Function]
    disable-frame  frame [Generic Function]
    shrink-frame  frame [Generic Function]

    These functions force a frame into the enabled, disabled, or shrunken (iconified) states. A frame in the enabled state may be visible if it is not occluded or placed out of the user's focus of attention. A disabled frame is never visible. A shrunk frame is accessible to the user for re-enabling, but may be represented in some abbreviated form, such as an icon or a menu item. [annotate]

    These functions call the notification functions describe below to notify the frame manager that the state of the frame changed. [annotate]


    note-frame-enabled  frame-manager frame [Generic Function]
    note-frame-disabled  frame-manager frame [Generic Function]
    note-frame-iconified  frame-manager frame [Generic Function]
    note-frame-deiconified  frame-manager frame [Generic Function]

    Notifies the frame manager frame-manager that the frame frame has changed its state to the enabled, disabled, iconified, or deiconified state, respectively. [annotate]


    note-command-enabled  frame-manager frame command-name [Generic Function]
    note-command-disabled  frame-manager frame command-name [Generic Function]

    Notifies the frame manager frame-manager that the command named by command-name has been enabled or disabled (respectively) in the frame frame. The frame manager can update the appearance of the user interface as appropriate, for instance, by "graying out" a newly disabled command from a command menu or menu bar. [annotate]


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

    This is the generic function used by notify-user. The arguments are as for notify-user. The default method on standard-frame-manager will display a dialog or an alert box that contains the message and has exit boxes that allow the user to dismiss the notification. [annotate]


    generate-panes  frame-manager frame [Generic Function]

    This function is invoked by a standard method of adopt-frame. define-application-frame automatically supplies a generate-panes method if either the :pane or :panes option is used in the define-application-frame. [annotate]

    It is the responsibility of this method to call setf on frame-panes on the frame in order to set the current [annotate]


    find-pane-for-frame  frame-manager frame [Generic Function]

    This function is invoked by a standard method of adopt-frame. It must return the root pane of the frame's layout. It is the responsibility of the frame implementor to provide a method that constructs the frame's top-level pane. define-application-frame automatically supplies a a method for this function if either the :pane or :panes option is used in the define-application-frame. [annotate]


    28.5.3 Frame Manager Settings

    CLIM provides frame manager settings in order to allow a frame to communicate information to its frame manager. [annotate]

    (setf client-setting)  value frame setting [Generic Function]

    Sets the setting setting to value for the frame frame. [annotate]


    reset-frame  frame &rest client-settings [Generic Function]

    Resets the settings of frame. reset-frame invokes a protocol that forces the frame manager to notice that the settings have changed, where the setf generic function just updates the frame data. For example, the width and height can be reset to force resizing of the window. [annotate]