9.4 DUIM-Frames Module

define frame

Definition macro

Summary

Defines a new class of frame with the specified properties.

Macro call

define frame name ({supers},*) {slots-panes-options} end

Arguments

name: A Dylan name_bnf.
supers: A Dylan name_bnf.
slots-panes-options: A Dylan body_bnf.

Values

None.

Library

duim-frames

Module

duim-frames

Description

Defines a new class of frame called name with the specified properties. This macro is equivalent to define class, but with additional options.

The supers argument lets you specify any classes from which the frame you are creating should inherit. You must include at least one concrete frame class, such as <simple-frame> or <dialog-frame>.

The slots-panes-options supplied describe the state variables of the frame class; that is, the total composition of the frame. This includes, but is not necessarily limited to, any panes, layouts, tool bar, menus, and status bar contained in the frame. You can specify arbitrary slots in the definition of the frame. You may specify any of the following:

A number of slots for defining per-instance values of the frame state.
A number of named panes. Each pane defines a sheet of some sort.
A single layout.
A tool bar.
A status bar.
A menu bar.
A command table.
A number of sequential pages for inclusion in a multi-page frame such as a wizard or property dialog.

Note: If the frame has a menu bar, either define the menu bar and its panes, or a command table, but not both. See the discussion below for more details.

The syntax for each of these options is described below.

The slot option allows you to define any slot values that the new frame class should allow. This option has the same syntax as slot specifiers in define class, allowing you to define init-keywords, required init-keywords, init-functions and so on for the frame class.

For each of the remaining options, the syntax is as follows:

option name (owner) body;

The argument option is the name of the option used, taken from the list described below, name is the name you assign to the option for use within your code, owner is the owner of the option, usually the frame itself, and body contains the definition of value returned by the option.

pane specifies a single pane in the frame. The default is #f, meaning that there is no single pane. This is the simplest way to define a pane hierarchy.

layout specifies the layout of the frame. The default is to lay out all of the named panes in horizontal strips. The value of this option must evaluate to an instance of a layout.

command-table defines a command table for the frame. The default is to create a command table with the same name as the frame. The value of this option must evaluate to an instance of <command-table>.

menu-bar is used to specify the commands that will in the menu bar of the frame. The default is #t. If used, it typically specifies the top-level commands of the frame. The value of this option can evaluate to any of the following:

#f

The frame has no menu bar.

#t,

The menu bar for the frame is defined by the value of the command-table option.

A command table

The menu bar for the frame is defined by this command table.

A body of code

This is interpreted the same way as the menu-item options to define command-table.

disabled-commands is used to specify a list of command names that are initially disabled in the application frame. The default is #[]. The set of enabled and disabled commands can be modified via command-enabled?-setter.

tool-bar is used to specify a tool bar for the frame. The default is #f. The value of this option must evaluate to an instance of <tool-bar>.

top-level specifies a function that executes the top level loop of the frame. It has as its argument a list whose first element is the name of a function to be called to execute the top-level loop. The function must take at least one argument, which is the frame itself. The rest of the list consists of additional arguments to be passed to the function.

icon specifies an <image><image> to be used in the window decoration for the frame. This icon may be used in the title bar of the frame, or when the frame is iconized, for example.

geometry specifies the geometry for the frame.

pages is used to define the pages of a wizard or property frame. This evaluates to a list of pages, each of which can be defined as panes within the frame definition itself. For example:

define frame <wizard-type> (<wizard-frame>)
  ...
  pages (frame)
    vector(frame.page-1, frame.page-2, frame.page-3);
end frame <wizard-type>

The name, supers, and slot arguments are not evaluated. The values of each of the options are evaluated.

Example

define frame <multiple-values-dialog> (<dialog-frame>)
  pane label-pane (frame)
    make(<option-box>, items: #("&Red", "&Green",
                                "&Blue"));
  pane check-one (frame)
    make(<check-button>, label: "Check box test text");
  pane check-two (frame)
    make(<check-button>, label: "Check box test text");
  pane radio-box (frame)
    make(<radio-box>,
         items: #("Option &1", "Option &2", 
                  "Option &3", "Option &4"),
         orientation: #"vertical");
  pane first-group-box (frame)
    grouping ("Group box", max-width: $fill)
      vertically (spacing: 4)
        make(<label>, label: "Label:");
        horizontally (spacing: 4, 
                      y-alignment: #"center")
          frame.label-pane;
          make(<button>, label: "Button");
        end;
        frame.check-one;
        frame.check-two;
      end
    end;
  pane second-group-box (frame)
    grouping ("Group box", max-width: $fill)
      frame.radio-box
    end;
  layout (frame)
    vertically (spacing: 4)
      frame.first-group-box;
      frame.second-group-box;
    end;
end frame <multiple-values-dialog>;