interface Class

Summary

The class interface is the top level window class, which contains both menus and a hierarchy of panes and layouts. Interfaces can also themselves be contained within a layout, in which case they appear without their menu bar.

Package

capi

Superclasses

simple-pane
titled-object

Initargs

Accessors

interface-title
pane-layout
interface-menu-bar-items
interface-create-callback
interface-destroy-callback
interface-confirm-destroy-function
interface-geometry-change-callback
interface-activate-callback
interface-iconify-callback
interface-override-cursor
interface-message-area
interface-pointer-documentation-enabled
interface-tooltips-enabled
interface-help-callback
top-level-interface-color-mode-callback
top-level-interface-external-border
top-level-interface-transparency
interface-toolbar-items
interface-toolbar-states
interface-default-toolbar-states
interface-pathname
interface-drag-image

Readers

interface-window-styles

Description

Every interface can have a title title which when it is a top level interface is shown as a title on its window, and when it is contained within another layout is displayed as a decoration (see the class titled-object for more details).

The argument layout specifies a layout object that contains the children of the interface. To change this layout you can either use the writer pane-layout, or you can use the layout switchable-layout which allows you to easily switch the currently visible child.

The argument menu-bar-items specifies a list of menus to appear on the interface's menu bar.

auto-menus defaults to t, which means that an interface may have some automatic menus created by the environment in which it is running (for example the Works menu in the LispWorks IDE). To switch off these automatic menus, pass :auto-menus nil.

Note: On Cocoa, certain system menu commands such as Edit > Start Dictation are added automatically. auto-menus does not control this.

When you have an instance of an interface, you can display it either as an ordinary window or as a dialog using respectively display and display-dialog. The CAPI calls create-callback (if supplied) with the interface as its single argument, after all the widgets have been created but before the interface appears on screen. Then to remove the interface from the display, you use quit-interface and either exit-dialog or abort-dialog respectively. When the interface is about to be closed, the CAPI calls the confirm-destroy-function (if there is one) with the interface, and if this function returns non-nil the interface is closed as if by calling destroy. Once the interface is closed, the destroy-callback is called with the interface. Therefore, neither confirm-destroy-function nor destroy-callback should call destroy.

Note: create-callback should be used only for operations that must be done with the interface already created and cannot be done in interface-display. Otherwise they should be either done in initialize-instance or between your calls to make-instance and display. An operation that needs to run after the interface is created but just before displaying the interface as an ordinary window (typical cases are font queries and loading images) can be put in the interface-display :before method. An operation that needs to run just after displaying the interface as an ordinary window can be put in the interface-display :after method.

The interface also accepts a number of hints as to the size and position of the interface for when it is first displayed. The arguments best-x and best-y specify the position, while the arguments best-width and best-height specify the size. The values can be any hints accepted by :visible-max-width and :visible-max-height for elements (see 6.4.2 Hint values formats), except for the character, string or text based hints. If best-width or best-height is nil or not specified, then the interface is displayed at its minimum size based on its constraints.

Whether or not an interface window is resizable is indicated as allowed by the window system. For non-resizable windows on Cocoa the interface window's maximize button is disabled and the resize indicator is not shown, and on Microsoft Windows the maximize box is disabled.

geometry-change-callback may be nil, meaning there is no callback. This is the default value. Otherwise geometry-change-callback is a function of five arguments: the interface and the geometry. Its signature is:

geometry-change-callback interface x y width height

x and y are measured from the top-left of the screen rectangle representing the area of the primary monitor (the primary screen rectangle).

activate-callback may be nil, meaning there is no callback. This is the default value. Otherwise activate-callback is a function of two arguments: the interface and a boolean activatep which is true on activation and false on deactivation. Its signature is:

activate-callback interface activatep

iconify-callback may be nil, meaning there is no callback. This is the default value. Otherwise iconify-callback is a function of two arguments: the interface and a boolean iconify which is true when interface is iconified and false when it is restored. Its signature is:

iconify-callback interface iconifyp

override-cursor, if non-nil, specifies a cursor that is used instead of the cursor of each pane inside the interface. The default value of override-cursor is nil. See below for an example of setting and unsetting the override cursor. override-cursor is not supported on Cocoa. override-cursor is ignored by text-input-pane on GTK+.

If message-area is true, then the interface is created with a message area at the bottom. The text of the message area can be accessed using the titled-object accessor titled-object-message. The default value of message-area is nil.

enable-pointer-documentation is a boolean controlling whether Pointer Documentation is enabled. The default value is t. The actual action is done by the help-callback. enable-pointer-documentation is supported only on Motif. It is possible to implement equivalent functionality for output-pane and subclasses such as pinboard-layout by using the focus-callback of output-pane.

enable-tooltips is a boolean controlling whether Tooltip Help is enabled. The default value is t. The actual action is done by the help-callback.

help-callback may be nil, meaning there is no callback. This is the default value. Otherwise help-callback is a function of four arguments: the interface, the pane inside interface where help is requested, the type of help requested, and the help key of the pane. Its signature is:

help-callback interface pane type help-key

Here type can be one of:

help-key is the help-key of pane, as described in element. There is an example illustrating help-callback in:

(example-edit-file "capi/elements/help")

and there is another example below.

top-level-hook can be used on Microsoft Windows and Motif to specify a hook function that is called around the interface's top level event handler. The hook is passed two arguments: a continuation function (with no arguments) and the interface. The hook must call the continuation, which normally does not return. top-level-hook is designed especially for error handling (see below for an example). It can also be used for other purposes, for instance to bind special variables around the top level function. :top-level-hook is not supported on Cocoa.

external-border controls how close to the edge of the screen the interface can be placed with explicit positioning using the best-x, best-y, best-height and best-width initargs or implicit positioning when a dialog is centered within its owner. The value nil allows the window to be anywhere, on or off the screen. The value 0 allows the window can be anywhere on the screen. If external-border is a positive integer then the window can be anywhere within external-border pixels from the edge of the screen. If external-border is a negative integer then the window be anywhere on the screen or up to external-border pixels off the edge of the screen. This does not affect whether the use can move the window after it has been displayed. It also does not affect the default positioning of interfaces, where the window system chooses the position.The default value of external-border is 0.

initial-focus specifies a pane which has the input focus when the interface is first displayed. See pane-initial-focus for more information about the initial focus pane.

display-state controls the initial display of the interface window, as described for top-level-interface-display-state.

color-mode controls the visual appearance the interface window, as described for top-level-interface-color-mode. Only effective on Cocoa.

If color-mode-callback is non-nil, it is called, with the interface as a single argument, when the global color mode (the Appearance on Cocoa, the Theme on Windows and GTK+) may have changed. It may take any action that is useful. Note that color-mode-callback may be called sometimes where there is no actual change.

transparency is the overall transparency of the whole interface, where 0 is fully transparent and 1 is fully opaque. This has no effect on whether the user can click on the window. This is implemented for Cocoa and Microsoft Windows. It also works on GTK+, provided that GTK+ and the X server support it. On GTK+ it is supported in version 2.12 and later. The X server needs compositing manager to do it.:transparency should only be used for top-level interfaces.

window-styles is a list of keywords controlling various aspects of the top level window's appearance and behavior. Each keyword is supported only on the Window systems explicitly mentioned below.

The following keywords apply to ordinary windows:

The following keywords are supported in window-styles when the interface is displayed as a dialog:

If toolbar-items is non-nil, then the interface will have a toolbar, which is typically displayed at the top of the window. The value of toolbar-items is a list of objects of type toolbar-button, toolbar-component or simple-pane, which are items that might be shown on the toolbar. The set of visible items, their order and their appearance is determined by the current toolbar-state, which can be changed if the user customizes the toolbar interactively. Each toolbar-button or simple-pane in the toolbar-items list (including those within a toolbar-component) should have a name that is not cl:eql to any other item in the list. Each toolbar-button should have image and text specified, to control the image and title that is shown for the item. Each simple-pane should have toolbar-title specified, to control the title that is shown for the item.

toolbar-states is a plist containing information about the state of the toolbar. The user can also change this by customizing the toolbar, so you cannot assume that the value will be the same each time you read it. See interface-toolbar-state for a description of the keys and values in this plist.

default-toolbar-states is a plist containing information about the default state of the toolbar, which you can provide as the suggested toolbar state for the interface. The key :items will be used in the Customize Toolbar dialog as the "default" set of toolbar buttons. If both default-toolbar-states and toolbar-states are supplied, then the value of any key in toolbar-states takes precedence over that of the same key in default-toolbar-states. See interface-toolbar-state for a description of the keys and values in this plist.

pathname specifies the interface pathname. You can get and set this with the accessor interface-pathname. The pathname may be displayed in some way to the user, depending on the GUI library.

Currently, only Cocoa uses pathname, in two ways:

• It makes the interface display a drag image on the title bar (This is the same image that is set by interface-drag-image, and the drag-image takes precedence if it not nil). The user can drag from the drag image, and if there is no drag-callback or if the drag-callback returns :default it will drag the pathname as a one item in a :filenames-list. For information about drag-callback, see simple-pane's description of :drag-callback and simple-pane-drag-callback.
• The context menu (invoked by right-mouse-click) on the drag image or on the title raises a menu containing the components of the path. Selecting a component opens the Finder with it.

drag-image is currently only effective on Cocoa. A non-nil value specifies that the interface should have a drag image, which on Cocoa is a small image (16x16px) to the left of the window title.

When the user drags this image, if the interface has a drag-callback it is called and if this returns non-nil LispWorks performs drag-and-drop with the image. See simple-pane for details of the drag-callback.

It is possible to have the image for aesthetic purposes only by supplying drag-image and not specifying a drag-callback. When drag-callback is non-nil, it can dynamically decide whether to allow a dragging, or to disallow dragging (by returning nil).

The image specification can be an already converted image (made by load-image, convert-external-image, make-sub-image or make-image-from-port). The image will be freed automatically when the interface is destroyed or when drag-image is set by (setf interface-drag-image). Otherwise the system uses load-image to create a new image, which is also freed automatically.

The value t for drag-image is interpreted specially: it means display some image. If drag-image is set to t after an image has already been set, it just displays the previous image. This is useful if an image was displayed but then removed by (setf interface-drag-image) with nil. If there was no previous image, a default image is displayed.

Notes

1. create-callback can only be used for actions that are part of the creation of the pane, that is preparing the pane for display. The create-callback is called before the pane is actually displayed, and therefore cannot interact with the user.
2. On Microsoft Windows F1 always calls help-callback if it is non-nil.
3. (setf capi:interface-message-area) has an effect only before display. After display, this writer has no effect unless the interface is destroyed and re-created.
4. Even though interface is a subclass of titled-object, the accessor titled-object-message-font cannot be used to get and set the font of the interface's message.
5. On Cocoa in the presence of a cocoa-default-application-interface, an interface with no menus of its own and with :auto-menus nil uses the menu bar from the application interface.

Compatibility note

interface-iconize-callback is deprecated. Use the synonym interface-iconify-callback instead.

Examples

(capi:display (make-instance 'capi:interface
                             :title "Test Interface"))

(capi:display (make-instance
                'capi:interface
                :title "Test Interface"
                :destroy-callback
                  #'(lambda (interface)
                            (capi:display-message
                             "Quitting ~S"
                             interface))))

(capi:display (make-instance
                'capi:interface
                :title "Test Interface"
                :confirm-destroy-function
                #'(lambda (interface) 
                          (capi:confirm-yes-or-no
                           "Really quit ~S"
                           interface))))

(capi:display (make-instance
                'capi:interface
                :menu-bar-items
                  (list
                    (make-instance 'capi:menu
                                   :title "Menu"
                                   :items '(1 2 3)))
                :title "Menu Test"))

(setq interface 
      (capi:display
       (make-instance
        'capi:interface
        :title "Test Interface"
        :layout
        (make-instance 'capi:simple-layout 
                       :description 
                       (list (make-instance 
                              'capi:text-input-pane
                              :text "Text Pane"))))))
 
(capi:execute-with-interface interface
 #'(setf capi:pane-layout) (make-instance 
                            'capi:simple-layout
                            :description
                            (list (make-instance 
                                   'capi:editor-pane 
                                   :text "Editor Pane")))

interface)
(capi:display 
(make-instance
 'capi:interface
 :title "Test"
 :best-x 200
 :best-y 200
 :best-width '(/ :screen-width 2)
 :best-height 300))

The following forms illustrate the use of help-callback:

(capi:define-interface my-interface ()
  ()
  (:panes
   (a-pane
    capi:text-input-pane
    :help-key 'input)
   (another-pane
    capi:display-pane
    :help-key 'output
    :text "some text"))
  (:menu-bar a-menu)
  (:menus
   (A-menu
    "A menu"
    (("An item" :help-key "item 1")
     ("Another item" :help-key "item 2"))
    :help-key "a menu"))
  (:layouts
   (main-layout
    capi:column-layout
    '(a-pane another-pane)))
 
  (:default-initargs
   :help-callback 'my-help-callback
   :message-area t))
 
(defun do-detailed-help (interface)
  (capi:contain 
   (make-instance 
    'capi:display-pane
    :text "Detailed help for my interface")
   :title 
   (format nil "Help for ~a" 
           (capi:capi-object-name interface))))
 
(defun my-help-callback (interface pane type key)
  (declare (ignore pane))
  (case type
    (:tooltip (if (eq key 'input)
                  "enter something"
                (when (stringp key) key)))
    (:pointer-documentation-enter
     (when (stringp key)
       (setf (capi:titled-object-message interface)
             key)))
    (:pointer-documentation-leave
     (setf (capi:titled-object-message interface)
           "Something else"))
    (:help (do-detailed-help interface ))))
 
(capi:display 
 (make-instance 'my-interface :name "Helpful"))

The following forms illustrate the use of override-cursor to set and then remove an override cursor.

Create an interface with panes that have various different cursors. Move the pointer across each pane.

(setf interface 
      (capi:element-interface 
       (car 
        (capi:contain 
         (loop for cursor 
               in '(:crosshair :hand :v-double-arrow)
               collect 
               (make-instance 'capi:editor-pane 
                              :cursor cursor 
                              :text 
                              (format nil "~A CURSOR" 
                                      cursor)))))))

Override the pane cursors by setting the override cursor on the interface, and move the pointer across each pane again.

(setf (capi:interface-override-cursor interface) 
      :i-beam)

Remove the override cursor.

(setf (capi:interface-override-cursor interface) 
      :default)

This example illustrates top-level-hook. Evaluate this form and then get an error by the interrupt gesture in the editor pane. (For example, the interrupt gesture is Meta+Control+C on Motif and Control+Break on Microsoft Windows). Then select the Destroy Interface restart.

(capi:display
 (capi:make-container 
  (make-instance
   'capi:editor-pane)
  :top-level-hook
  #'(lambda (func interface)
      (restart-case (funcall func)
        (nil ()
             :report 
             (list "Destroy Interface ~a" interface)
             (capi:destroy interface))))))

For an example of using color-mode and color-mode-callback, see:

(example-edit-file "capi/applications/interface-color-mode")

This example illustrates the use of toolbar-items:

(example-edit-file "capi/applications/simple-symbol-browser")

See also

layout
switchable-layout
menu
display
display-dialog
interface-display
quit-interface
define-interface
activate-pane
titled-object
interface-document-modified-p
interface-toolbar-state
interface-customize-toolbar
top-level-interface-display-state
top-level-interface-color-mode
top-level-interface-dark-mode-p
1.2.1 CAPI elements
2 Getting Started
3.3.2.1 Window titles
3.12.2 Tooltips for collections, elements and menu items
6 Laying Out CAPI Panes
9 Adding Toolbars
11 Defining Interface Classes - top level windows
12 Creating Panes with Your Own Drawing and Input
13 Drawing - Graphics Ports
17 Drag and Drop