29.2 Basic Pane Construction

  • 29.2.1 Pane Initialization Options
  • 29.2.2 Pane Properties
  • Applications typically define the hierarchy of panes used in their frames using the :pane or :panes options of define-application-frame. These options generate the body of methods on functions that are invoked when the frame is being adopted into a particular frame manager, so the frame manager can select the specific implementations of the abstract panes. [annotate]

    There are two basic interfaces to constructing a pane: make-pane of an abstract pane class name, or make-instance of a "concrete" pane class. The former approach is generally preferable, since it results in more portable code. However, in some cases the programmer may wish to instantiate panes of a specific class (such as an hbox-pane or a vbox-pane). In this case, using make-instance directly circumvents the abstract pane selection mechanism. However, the make-instance approach requires the application programmer to know the name of the specific pane implementation class that is desired, and so is inherently less portable. By convention, all of the concrete pane class names, including those of the implementations of abstract pane protocol specifications, end in "-pane". [annotate]

    Using make-pane instead of make-instance invokes the "look and feel" realization process to select and construct a pane. Normally this process is implemented by the frame manager, but it is possible for other "realizers" to implement this process. make-pane is typically invoked using an abstract pane class name, which by convention is a symbol in the CLIM package that doesn't include the "-pane" suffix. (This naming convention distinguishes the names of the abstract pane protocols from the names of classes that implement them.) Programmers, however, are allowed to pass any pane class name to make-pane, in which case the frame manager will generally instantiate that specific class. [annotate]

    pane   [Protocol Class]

    The protocol class that corresponds to a pane, a subclass of sheet. A pane is a special kind of sheet that implements the pane protocols, including the layout protocols. If you want to create a new class that behaves like a pane, it should be a subclass of pane. All instantiable subclasses of pane must obey the pane protocol. [annotate]

    All of the subclasses of pane are mutable. [annotate]


    panep  object [Protocol Predicate]

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


    basic-pane   [Class]

    The basic class on which all CLIM panes are built, a subclass of pane. This class is an abstract class, intended only to be subclassed, not instantiated. [annotate]


    make-pane  abstract-class-name &rest initargs [Function]

    Selects a class that implements the behavior of the abstract pane abstract-class-name and constructs a pane of that class. make-pane must be used either within the scope of a call to with-look-and-feel-realization, or within the :pane or :panes options of a define-application-frame (which implicitly invokes with-look-and-feel-realization). [annotate]

    It is permitted for this function to have lexical scope, and be defined only within the body of with-look-and-feel-realization. [annotate]


    make-pane-1  realizer frame abstract-class-name &rest initargs [Generic Function]

    The generic function that is invoked by a call to make-pane. The object that realizes the pane, realizer, is established by with-look-and-feel-realization. Usually, realizer is a frame manager, but it could be another object that implements the pane realization protocol. frame is the frame for which the pane will be created, and abstract-class-name is the type of pane to create. [annotate]


    with-look-and-feel-realization  (realizer frame) &body forms [Macro]

    Establishes a dynamic context that installs realizer as the object responsible for realizing panes. All calls to make-pane within the context of with-look-and-feel-realization result in make-pane-1 being invoked on realizer. This macro can be nested dynamically; inner uses shadow outer uses. body may have zero or more declarations as its first forms. [annotate]

    Typically realizer is a frame manager, but in some cases realizer may be some other object. For example, within the implementation of pane that is uses its own subpanes to achieve its functionality, this form might be used with realizer being the pane itself. [annotate]


    29.2.1 Pane Initialization Options

    The following options must be accepted by all pane classes. [annotate]

    :foreground   [Option]
    :background   [Option]

    These options specify the default foreground and background inks for a pane. These will normally default from window manager resources. If there are no such resources, the defaults are black and white, respectively. [annotate]

    Client code should be cautious about passing values for these two options, since the window manager's look and feel or the user's preferences should usually determine these values. [annotate]


    :text-style   [Option]

    This option specifies the default text style that should be used for any sort of pane that supports text output. Panes that do not support text output ignore this option. [annotate]

    Client code should be cautious about passing values for this option, since the window manager's look and feel or the user's preferences should usually determine this value. [annotate]


    :name   [Option]

    This option specifies the name of the pane. It defaults to nil. [annotate]


    29.2.2 Pane Properties

    pane-frame  pane [Generic Function]

    Returns the frame that "owns" the pane. pane-frame can be invoked on any pane in a frame's pane hierarchy, but it can only be invoked on "active" panes, that is, those panes that are currently adopted into the frame's pane hierarchy. [annotate]


    pane-name  pane [Generic Function]

    Returns the name of the pane. [annotate]


    pane-foreground  pane [Generic Function]
    pane-background  pane [Generic Function]
    pane-text-style  pane [Generic Function]

    Return the default foreground and background inks and the default text style, respectively, for the pane pane. These will be used as the default value for medium-foreground and medium-background when a medium is grafted to the pane. [annotate]