11.2 An example interface

Here is a simple example of interface definition done with define-interface:

(define-interface demo ()
  ()
  (:panes
   (page-up push-button 
            :text "Page Up")
   (page-down push-button
              :text "Page Down")
   (open-file push-button
              :text "Open File"))
  (:layouts
   (row-of-buttons row-layout
                   '(page-up page-down open-file)))
  (:default-initargs :title "Demo"))

An instance of this interface can be displayed as follows:

(display (make-instance 'demo))

At the moment the buttons do nothing, but they will eventually do the following:

• Open File will bring up a file prompter and allow you to select a filename from a directory. Later on, we will add an editor pane to display the chosen file's contents.
• Page Down will scroll downwards so that you can view the lower parts of the file that cannot be seen initially.
• Page Up will scroll upwards so that you can return to parts of the file seen before.

  A demonstration of a CAPI interface

  

Later on, we will specify callbacks for these buttons to provide this functionality.

The (:default-initargs :title "Demo") part at the end is necessary to give the interface a title. If no title is given, the default name is "Untitled CAPI Interface".

11.2.1 How the example works

Examine the define-interface form to see how this interface was built. The first part of this form is shown below:

(define-interface demo ()
   ()

This part of the macro is identical to defclass — you provide:

• The name of the interface class being defined.
• The superclasses of the interface (defaulting to interface).
• The slot descriptions.

The interesting part of the define-interface form occurs after these defclass-like preliminaries, where it lists the elements that define the interface's appearance. Here is the :panes part of the definition:

(:panes
 (page-up push-button 
          :text "Page Up")
 (page-down push-button
            :text "Page Down")
 (open-file push-button
            :text "Open File"))

Two arguments — the name and the class — are required to produce a pane. You can supply slot values as you would for any CLOS object.

The :panes list specifies panes that are made when the interface is made. However it does not specify which panes are displayed: that is controlled dynamically by the interface's layout which may contain all, some or none of the panes in the :panes list. The interface may also display other panes that are made explicitly, though this is less common.

Here is the :layouts part of the definition:

(:layouts
 (row-of-buttons row-layout
                 '(page-up page-down open-file)))

Three arguments — the name, the class, and any child layouts — are required to produce a layout. Notice how the children of the layout are specified by using their component names.

The interface information supplied in this section is a series of specifications for panes and layouts. It could also specify menus and a menu bar. In this case, three buttons are defined. The layout chosen is a row layout, which displays the buttons side by side at the top of the pane.