*******************
DUIM-Frames Library
*******************
.. current-library:: duim
.. current-module:: duim-frames
Overview
========
The DUIM-Frames library contains interfaces that define a wide variety
of frames for use in your GUI applications, as well as the necessary
functions, generic functions, and macros for creating and manipulating
them. The library contains a single module, *duim-frames*, from which
all the interfaces described in this chapter are exposed.
`DUIM-Frames Module`_ contains complete reference
entries for each exposed interface.
Frames are the basic components used to display DUIM objects on-screen.
An instance of type :class:`` or :class:``, or any of their subclasses, and an event
loop. The event loop associated with a frame is represented by an
instance of a subclass of :class:``. An overview of these subclasses is
provided in `Subclasses of \`_.
The class hierarchy for DUIM-Frames
===================================
This section presents an overview of the available classes of frame,
frame event, and command-related classes, and describes the class
hierarchy present.
The `. In addition, there are a number of
classes related to commands that are subclasses of :drm:``, together
with a number of classes related to events that occur in frames.
- :drm:``
- :class:``
- :class:`` - See :ref:`gadgets-subclasses-of-page`
- :class:``_
- :class:``
- :class:`` - See `Subclasses of \`_
- :class:``
- :class:``
- :class:``
- :class:``
The :class:``_.
The :class:`` class represents the base class for all events that can
occur. Although this class and the :class:`` subclass are exposed
by the DUIM-Sheets library, the subclasses of :class:`` itself are
exposed by the DUIM-Frames library. See `Subclasses of \`_ for an
introduction to these subclasses. See the :doc:`DUIM-Sheets Library `, for a
complete description of the DUIM-Sheets library.
The remaining four classes exposed by the DUIM-Frames library relate to
commands and their use in application menus.
:class:``
This class is used to create the most basic type of command. A
command is an operation that can be invoked as a callback from a menu
item, a button, or other suitable interface control.
:class:``
This class is used to define commands whose effects can be reversed.
Typically, the user chooses the command *Edit > Undo* to reverse the
effects of a command of this class.
:class:``
The :class:`` class is used to define the complete menu
structure of an application frame, from the menu bar and menus to the
menu items on each menu.
:class:``
This class represents a menu item on a menu defined in a command
table.
Subclasses of `
- :class:``
- :class:``
- :class:``
:class:``
This class is the most common sort of frame and is used to create
a standard window in an application.
:class:``
This class is used to create dialog boxes for use in an application.
:class:``
This class is used to create property sheets for use in an
application. Property sheets are a special type of dialog box which
make use of tab controls to display several pages of information
within the same dialog.
:class:``
This class is used to create wizards for use in an application.
Wizards are a special type of multi-page dialog in which the user is
guided through a series of sequential steps, filling out any
information requested and using *Next* and *Back* buttons to navigate
to the next or previous steps in the process.
Subclasses of
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :class:`` class provides a number of subclasses that describe
various events that can occur in frames.
- :class:``
- :class:``
- :class:``
- :class:``
- :class:``
- :class:``
- :class:``
- :class:``
The name of each of these subclasses accurately reflects the type of
event that they are used to represent. The classes
:class:`` and :class:``
represent a frame being created or destroyed. The classes
:class:`` and :class:``
represent the events that occur when a frame is displayed on the
computer screen or removed from it. The class :class:``
represents the act of exiting a frame, and the class
:class:`` represents the event where a frame has been
successfully exited.
In addition, the class :class:`` has a subclass
:class:``. This is reserved for the special case
where the frame that has been exited is actually the parent frame for
the whole application, in which case the whole application is exited,
together with any other frames that may have been spawned as a result of
using the application.
.. note:: The classes :class:`` and
:class:`` are distinct from the
classes :class:`` and
:class:``. A frame is not necessarily
mapped as soon as it is created, and any frame can be unmapped
from the screen without actually destroying it (for example,
a frame may be iconized).
.. _frames-subclasses-of-page:
Subclasses of
^^^^^^^^^^^^^^^^^^^^
Although the :class:`` class is itself a subclass of :class:``, and is
exposed by the DUIM-Gadgets library, two of its subclasses are exposed
by the DUIM-Frames library: :class:`` and :class:``. See
:ref:`gadgets-subclasses-of-page` for an introduction to these classes.
DUIM-Commands Library
=====================
All commands-related interfaces are now defined directly in the Commands
library. However, these same interfaces are imported to and re-exported
from DUIM-Frames, so they can be used in almost the same way as for
Harlequin Dylan 1.0. You should continue to look for commands-related
documentation in this chapter.
A consequence of the introduction of the Commands library is that a
slight change in syntax is required in the definition of commands in
command tables. In Harlequin Dylan 1.0, two approaches could be taken
when specifying a command in a table. For example, a menu item could be
specified by either of the following:
.. code-block:: dylan
menu-item "My Command" = make(, function: my-command),
menu-item "My Command" = my-command,
Beginning with Harlequin Dylan 1.1, only the last of these may be used.
This may require you to change some of your code.
DUIM-Frames Module
==================
This section contains a complete reference of all the interfaces that
are exported from the *duim-frames* module.
.. method:: =
:specializer:
Returns true if the specified commands are the same.
:signature: = *command1* *command2* => *equal?*
:param command1: An instance of type :class:``.
:param command2: An instance of type :class:``.
:value equal?: An instance of type :drm:``.
:description:
Returns true if *command1* and *command2* are the same.
.. generic-function:: add-command
Adds a command to the specified command table.
:signature: add-command *command-table* *command* #key *name* *menu image* *accelerator* *mnemonic* *error?* => ()
:param command-table: An instance of type :class:``.
:param command: An instance of type ``type-union(, )``.
:param #key name: An instance of type ``false-or()``.
:param #key menu: An instance of type ``false-or()``.
:param #key image: An instance of type ``false-or()``.
:param #key accelerator: An instance of type ``false-or()``.
:param #key mnemonic: An instance of type ``false-or()``.
:param #key error?: An instance of type :drm:``. Default value: ``#t``.
:description:
You can supply a keyboard accelerator or a mnemonic using the
*accelerator* and *mnemonic* arguments respectively.
Adds *command* to *command-table*.
The argument *name* is the command-line name for the command.
- When *name* is ``#f``, the command is not available via command-line
interactions.
- When *name* is a string, that string is the command-line name for the
command.
For the purposes of command-line name lookup, the character case of
*name* is ignored.
The argument *menu* is a menu for *command*.
- When *menu* is ``#f``, *command* is not available via menus.
- When *menu* is a string, the string is used as the menu name.
- When *menu* is ``#t`` and *name* is a string, then *name* is used as
the menu name.
- When *menu* is ``#t`` and *name* is not a string, a menu name is
automatically generated.
- When *menu* is a list of the form ``(string, menu-options)``,
*string* is the menu name and *menu-options* consists of a list of
keyword-value pairs. Each keyword-value pair is itself a list. The
valid keywords are ``after:``, ``documentation:``, and ``text-style:``,
which are interpreted as for :gf:`add-command-table-menu-item`.
You can supply an image that will appear on the menu next to the command
name using the *image* argument. When supplying an image, bear in mind
the size of the menu: you should only supply a small icon-sized image
for a menu command. There may also be other interface guidelines that
you wish to follow when using images in menu items.
The value for *accelerator* is either keyboard gesture or ``#f``. When it
is a gesture, this gesture represents the keystroke accelerator for the
command; otherwise the command is not available via keystroke
accelerators. Similarly, if mnemonic is supplied, this gesture is used
as a mnemonic for the command.
If *command* is already present in the command table and *error?* is
``#t``, an error is signalled. When *command* is already present in the
command table and *error?* is ``#f``, then the old command-line name,
menu, and keystroke accelerator are removed from the command table
before creating the new one.
:seealso:
- :gf:`remove-command`
.. generic-function:: add-command-table-menu-item
Adds a menu item to the specified command table.
:signature: add-command-table-menu-item *command-table* *string* *type* *value* #key
*documentation* *after* *accelerator* *mnemonic* *text-style* *error?*
*items* *label-key* *value-key* *test* *callback* => *menu-item*
:param command-table: An instance of type :class:``.
:param string: An instance of type ``false-or()``.
:param type: An instance of type ``one-of(#"command", #"function", #"menu", #"divider")``.
:param value: An instance of type :drm:``.
:param #key documentation: An instance of type :drm:``.
:param #key after: An instance of type ``one-of(#"start", #"end", #"sort")``, or
an instance of :drm:``. Default value: ``#"end"``.
:param #key accelerator: An instance of type ``false-or()``.
:param #key mnemonic: An instance of type ``false-or()``.
:param #key text-style: An instance of type :class:``.
:param #key error?: An instance of type :drm:``. Default value: ``#t``.
:param #key items: An instance of type ``limited(, of: )``.
:param #key label-key: An instance of type :drm:``.
:param #key value-key: An instance of type :drm:``.
:param #key test: An instance of type :drm:``.
:param #key callback: An instance of type :drm:``.
:value menu-item: An instance of type :class:``.
:description:
Adds a command menu item to the menu in *command-table*. The *string*
argument is the name of the command menu item; its character case is
ignored. The *type* of the item is either ``#"command"``, ``#"function"``,
``#"menu"``, or ``#"divider"``.
When *type* is ``#"command"``, *value* must be one of the following:
- A command (a list consisting of a command name followed by a list of
the arguments for the command).
- A command name. In this case, *value* behaves as though a command
with no arguments was supplied.
When all the required arguments for the command are supplied, clicking
on an item in the menu invokes the command immediately. Otherwise, the
user is prompted for the remaining required arguments.
When *type* is ``#"function"``, *value* must be a function having
indefinite extent that, when called, returns a command. The function is
called with two arguments:
- The gesture used to select the item (either a keyboard or button
press event).
- A "numeric argument".
When *type* is ``#"menu"``, this indicates that a sub-menu is required,
and *value* must be another command table or the name of another command
table.
When *type* is ``#"divider"``, some sort of a dividing line is displayed
in the menu at that point. If *string* is supplied, it will be drawn as
the divider instead of a line. If the look and feel provided by the
underlying window system has no corresponding concept, ``#"divider"``
items may be ignored. When *type* is ``#"divider"``, *value* is ignored.
The argument *documentation* specifies a documentation string, This can
be used to provide the user with some online documentation for the menu
item. Documentation strings are often displayed in a status bar at the
bottom of an application; highlighting the menu item using the mouse
pointer displays the documentation string in the status bar.
The *text-style* argument, if supplied, represents text style. This
specifies the font family, style, and weight with which to display the
menu item in the menu. For most menu items, you should just use the
default text style (that is, the one that the user chooses for all
applications). However, in certain cases, some variation is allowed.
The *text-style* argument is of most use in context sensitive pop-up
menus, which often have a default menu item. This is usually the command
that is invoked by pressing the RETURN key on the current selection: for
example, in a list of files, the default command usually opens the
selected file in the application associated with it. In Windows 95, the
default command is displayed using a bold font, to differentiate it from
other commands in the menu, and you should use the text-style argument
to specify this.
When altering the text style of a menu item, you should always try to
stick to any relevant interface guidelines.
The *items* argument is used to specify the gadgets that are to be
supplied to the command table as menu items. You can supply either push
boxes, check boxes, or radio boxes.
The *after* argument denotes where in the menu the new item is to be
added. It must be one of the following:
- ``#"start"`` Adds the new item to the beginning of the menu.
- ``#"end"`` Adds the new item to the end of the menu.
A string naming an existing entry
- Adds the new item after that entry.
- ``#"sort"`` Insert the item in such as way as to maintain the menu in
alphabetical order.
If *mnemonic* is supplied, the item is added to the keyboard mnemonic
table for the command table. The value of *mnemonic* must be a keyboard
gesture name.
When *mnemonic* is supplied and *type* is ``#"command"`` or ``#"function"``,
typing a key on the keyboard that matches the mnemonic invokes the
command specified by *value*.
When *type* is ``#"menu"``, the command is read from the submenu
indicated by *value* in a window system specific manner. This usually
means that the submenu itself is displayed, allowing the user to see the
available options at that point.
When *accelerator* is supplied, typing a key sequence on the keyboard
that matches the accelerator invokes the command specified by *value*,
no matter what *type* is.
If the item named by *string* is already present in the command table
and *error?* is ``#t``, then an error is signalled. When the item is
already present in the command table and *error?* is ``#f``, the old item
is removed from the menu before adding the new item. Note that the
character case of *string* is ignored when searching the command table.
:seealso:
- :class:``
- :gf:`remove-command-table-menu-item`
.. class::
:sealed:
:instantiable:
The class of events signalled when an application exits.
:superclasses: :class:``
:description:
The class of events signalled when an application exits. An instance of
this class is distributed when your application is exited, for instance
by choosing *File > Exit* from its main menu bar.
:seealso:
- :gf:`exit-frame`
- :class:``
.. generic-function:: apply-in-frame
Applies the specified function to the given arguments in the main thread
of the frame.
:signature: apply-in-frame *frame function arg* #rest *args* => ()
:param frame: An instance of type :class:``.
:param arg: An instance of type :drm:``.
:param #rest args: Instances of type :drm:``.
:description:
Applies *function* to the given arguments in the main thread of *frame*.
You must supply at least one argument (*arg*), though you can
optionally supply as many additional arguments as you like.
:seealso:
- :gf:`call-in-frame`
.. generic-function:: call-in-frame
Calls the specified function with the given arguments in the main thread
of the frame.
:signature: call-in-frame *frame function* #rest *args* => ()
:param frame: An instance of type :class:``.
:param #rest args: Instances of type :drm:``.
:description:
Calls *function* with the given arguments in the main thread of *frame*.
:seealso:
- :gf:`apply-in-frame`
.. generic-function:: cancel-dialog
Cancels the specified dialog.
:signature: cancel-dialog *dialog* #key *destroy?* => ()
:param dialog: An instance of type :class:``.
:param destroy?: An instance of type :drm:``. Default value: ``#t``.
:description:
Cancels *dialog* and removes it from the screen. Any changes that the
user has made to information displayed in the dialog is discarded.
If *destroy?* is ``#t`` then the dialog is unmapped from the screen.
This is the default callback used for the cancel button in a dialog.
:example:
The following example defines a button, ``*no-button*``, that calls
:gf:`cancel-dialog` as its activate-callback. This button is then used in a
dialog that simply replaces the standard cancel button for the newly
defined dialog. Note that the example assumes the existence of a similar
``*yes-button*`` to replace the exit button.
.. code-block:: dylan
define variable *no-button*
= make(, label: "No",
activate-callback: cancel-dialog,
max-width: $fill);
define variable *dialog*
= make(,
exit-button?: #f,
cancel-button?: #f,
layout: vertically ()
make(,
label: "Simple dialog");
horizontally ()
*yes-button*;
*no-button*;
end
end);
start-frame(*dialog*);
:seealso:
- :gf:`dialog-cancel-callback`
- :class:``
- :gf:`start-dialog`
- :gf:`exit-dialog`
.. generic-function:: clear-progress-note
Clears the specified progress note.
:signature: clear-progress-note *framem* *progress-note* => ()
:param framem: An instance of type :class:``.
:param progress-note: An instance of type :class:``.
:description:
Clears the specified progress note.
.. class::
:open:
:abstract:
:instantiable:
The class of commands.
:superclasses: :drm:``
:keyword function: An instance of type :drm:``.
:keyword arguments: An instance of type :drm:``. Default value: ``#[]``.
:description:
The class of commands. These are commands that can be grouped together
in a command table to form the set of commands available to an
application (available, for example, from the menu bar of the
application). The resulting command object can then be executed by
calling :gf:`execute-command`.
The ``function:`` init-keyword is the command function that is called by
the command object. A command function is rather like a callback to a
```` object: a command can be executed via :gf:`execute-command`,
which then invokes the command function. Command functions take at least
one argument: a :class:``
.. generic-function:: command?
Returns true if the specified object is a command.
:signature: command? *object* => *command?*
:param object: An instance of type :drm:``.
:value command?: An instance of type :drm:``.
:description:
Returns true if *object* is an instance of :class:``.
:seealso:
- :class:``
.. generic-function:: command-arguments
Returns the arguments to the specified command.
:signature: command-arguments *command* => *arguments*
:param command: An instance of type :class:``.
:value arguments: An instance of type :drm:``.
:description:
Returns the arguments to *command*.
:seealso:
- :class:``
.. generic-function:: command-enabled?
Returns true if the specified command is enabled.
:signature: command-enabled? *command* *frame* #key => *enabled?*
:param command: An instance of type ``type-union(, )``.
:param frame: An instance of type :class:``.
:description:
Returns true if *command* in *frame* is enabled.
:seealso:
- :class:``
- :gf:`command-enabled?-setter`
.. generic-function:: command-enabled?-setter
Enables or disables the specified command.
:signature: command-enabled?-setter *enabled?* *command* *frame* => *enabled?*
:param enabled?: An instance of type :drm:``.
:param command: An instance of type ``type-union(, )``.
:param frame: An instance of type :class:``.
:description:
Enables or disables *command* in *frame*. If *enabled?* is true, then
*command* is enabled, otherwise it is disabled. Enabling and disabling a
command enables and disables all the gadgets that are associated with
the command, such as menu items and tool bar buttons.
This function is useful when manipulating the disabled commands in
*frame*. For example, it is common to disable the *Save* menu command
immediately after saving a file, enabling it again only when the file
has been modified.
:seealso:
- :gf:`command-enabled?`
.. generic-function:: command-function
Returns the function associated with the specified command.
:signature: command-function *command* => *function*
:param command: An instance of type :class:``.
:value function: An instance of type :drm:``.
:description:
Returns the function associated with *command*. A command function is
the function that is called by a :class:`` object. Command functions
are similar to callbacks, in that they are user functions that are
invoked in order to perform some action. Command functions take at least
one argument: a :class:``
- :gf:`execute-command`
.. class::
:open:
:abstract:
:instantiable:
The class of command tables.
:superclasses: :drm:``
:keyword name: An instance of type :drm:``. Required.
:keyword inherit-from: An instance of type ``limited(, of: )``. Required.
:keyword resource-id: An instance of type ``false-or()``. Default
value: ``#f``.
:description:
The class of command tables. The command table for an application gives
a complete specification of the commands available to that application,
through its menus, tool bars, mnemonics, and accelerators.
The ``name:`` init-keyword is a symbol that names the current command
table.
The ``inherit-from:`` init-keyword is a sequence of command tables whose
behavior the current command table should inherit. All command tables
inherit the behavior of the command table specified by
:var:`*global-command-table*`, and can also inherit the
behavior specified by :var:`*user-command-table*`.
You do not normally need to specify a unique ``resource-id:`` yourself. As
with most other DUIM classes, the ``name:`` init-keyword serves as a
sufficient unique identifier.
:operations:
- :gf:`add-command`
- :gf:`add-command-table-menu-item`
- :gf:`command-table-accelerators`
- :gf:`command-table-commands`
- :gf:`command-table-menu`
- :gf:`command-table-name`
- :gf:`frame-command-table-setter`
- :meth:`make(`.
:value command-table?: An instance of type :drm:``.
:description:
Returns true if *object* is a command table.
:seealso:
- :class:``
.. generic-function:: command-table-accelerators
Returns the keyboard accelerators for the specified command table.
:signature: command-table-accelerators *command-table* => *accelerators*
:param command-table: An instance of type :class:``.
:value accelerators: An instance of type ``limited(, of: )``.
:description:
Returns the keyboard accelerators for *command-table*.
:seealso:
- :gf:`command-table-commands`
.. generic-function:: command-table-commands
Returns the commands for the specified command table.
:signature: command-table-commands *command-table* => *commands*
:param command-table: An instance of type :class:``.
:value commands: An instance of type ``limited(, of: )``.
:description:
Returns the commands defined for *command-table*.
:seealso:
- :gf:`command-table-accelerators`
- :gf:`command-table-menu`
.. generic-function:: command-table-menu
Returns the menu items in the specified command table.
:signature: command-table-menu *command-table* => *menu-items*
:param command-table: An instance of type :class:``.
:value menu-items: An instance of type :drm:``.
:description:
Returns the menu items in *command-table*.
:seealso:
- :gf:`command-table-commands`
- :gf:`command-table-name`
.. class::
:sealed:
:instantiable:
The class of menu items in command tables.
:superclasses: :drm:``
:keyword name: An instance of type ``false-or()``. Default value:
``#f``.
:keyword image: An instance of type ``false-or(type-union(, ))``.
Default value: ``#f``
:keyword type: An instance of type ``one-of(#"command", #"function", #"menu", #"divider")``.
:keyword value: An instance of type :drm:``. Default value: ``#f``.
:keyword options: An instance of type :drm:``. Default value: ``#()``.
:keyword accelerator: An instance of type ``false-or()``. Default value: ``#f``.
:keyword mnemonic: An instance of type ``false-or()``. Default value: ``#f``.
:description:
The class of menu items in command tables. This class models menu items,
tool bar items, accelerators, and mnemonics for a command table entry.
The ``type:`` init-keyword denotes what type of menu item has been
created. This is either ``#"command"``, ``#"function"``, ``#"menu"``, or
``#"divider"``.
When ``type:`` is ``#"command"``, ``value:`` must be one of the following:
- A command (a list consisting of a command name followed by a list of
the arguments for the command).
- A command name. In this case, ``value:`` behaves as though a command
with no arguments was supplied.
When all the required arguments for the command are supplied, clicking
on an item in the menu invokes the command immediately. Otherwise, the
user is prompted for the remaining required arguments.
When ``type:`` is ``#"function"``, ``value:`` must be a function having
indefinite extent that, when called, returns a command. The function is
called with two arguments:
- The gesture used to select the item (either a keyboard or button
press event).
- A "numeric argument".
When ``type:`` is ``#"menu"``, this indicates that a sub-menu is required,
and ``value:`` must be another command table or the name of another command
table.
When ``type:`` is ``#"divider"``, some sort of a dividing line is displayed
in the menu at that point. If a string is supplied using the ``options:``
init-keyword, it will be drawn as the divider instead of a line. If the
look and feel provided by the underlying window system has no
corresponding concept, ``#"divider"`` items may be ignored. When ``type:``
is ``#"divider"``, ``value:`` is ignored.
The ``accelerator:`` and ``mnemonic:`` init-keywords let you specify a
keyboard accelerator and mnemonic for the menu item.
:operations:
- :gf:`add-command-table-menu-item`
- :gf:`menu-item-accelerator`
- :gf:`menu-item-mnemonic`
- :gf:`menu-item-name`
- :gf:`menu-item-options`
- :gf:`menu-item-type`
- :gf:`menu-item-value`
:seealso:
- :gf:`add-command-table-menu-item`
.. generic-function:: command-table-name
Returns the name of the specified command table.
:signature: command-table-name *command-table* => *name*
:param command-table: An instance of type :class:``.
:value name: An instance of type :drm:``.
:description:
Returns the name of *command-table*, as defined by the ``name:``
init-keyword for :class:``.
:seealso:
- :class:``
- :gf:`command-table-menu`
.. generic-function:: command-undoable?
Returns true if the specified command is undoable.
:signature: command-undoable? *command* => *undoable?*
:param command: An instance of type :class:``.
:param undoable?: An instance of type :drm:``.
:description:
Returns true if *command* is undoable, that is, there is a specified
command that the user can choose (for instance, by choosing *Edit >
Undo*) that will reverse the effects of command.
:seealso:
- :gf:`undo-command`
.. generic-function:: complete-from-generator
Completes a string based on a generated list of completions.
:signature: complete-from-generator *string generator delimiters*
#key *action predicate*
=> *string success object nmatches completions*
:param string: An instance of type :drm:``.
:param generator: An instance of type :drm:``.
:param delimiters: An instance of type ``limited(, of: )``.
:param action: An instance of type ``one-of(#"complete",
#"complete-limited", #"complete-maximal", #"completions",
#"apropos-completions")``. Default value ``#"complete"``.
:param predicate: An instance of type ``false-or()``. Default
value ``#f``.
:value string: An instance of type ``false-or()``.
:value success: An instance of type :drm:``.
:value object: An instance of type :drm:``.
:value nmatches: An instance of type :drm:``.
:value completions: An instance of type :drm:``.
:description:
Completes *string* chunk-wise against a list of possibilities derived
from *generator*, using the specified *delimiters* to break both
*string* and the generated possibilities into chunks. This function is
identical to :gf:`complete-from-sequence`, except
that the list of possibilities is derived from the *generator* function,
rather than passed explicitly. The *generator* is a function of two
arguments: the string to be completed and a continuation co-routine to
call that performs the completion. It should call the continuation with
two arguments: the completion string and an object.
The argument *predicate* (if supplied) is applied to filter out unwanted
objects.
The function returns five values: the completed string (if there is
one), whether or not the completion successfully matched, the object
associated with the completion, the number of things that matched, and
(if *action* is ``#"completions"``) a sequence of possible completions.
The *action* argument can take any of the following values:
- ``#"complete"`` Completes the input as much as possible, except that if
the user's input exactly matches one of the possibilities, the
shorter possibility is returned as the result, even if it is a left
substring of another possibility.
- ``#"complete-limited"`` Completes the input up to the next partial
delimiter.
- ``#"complete-maximal"`` Completes the input as much as possible.
- ``#"completions"`` or ``#"apropos-completions"`` Returns a sequence
of the possible completions.
:example:
.. code-block:: dylan
complete-from-generator
("th", method (string, completer)
for (b in #["one", "two", "three", "four"])
completer(b, b)
end
end method, #[' ', '-'])
:seealso:
- :gf:`complete-from-sequence`
.. generic-function:: complete-from-sequence
Completes a string based on a list of possible completions.
:signature: complete-from-sequence *string possibilities delimiters*
#key *action predicate label-key value-key*
=> *string success object nmatches completions*
:param string: An instance of type :drm:``.
:param possibilities: An instance of type ``limited(, of: )``.
:param delimiters: An instance of type ``limited(, of: )``.
:param #key action: An instance of type ``one-of(#"complete",
#"complete-limited", #"complete-maximal", #"completions",
#"apropos-completions")``. Default value ``#"complete"``.
:param #key predicate: An instance of type ``false-or()``. Default
value ``#f``.
:param #key label-key: An instance of type :drm:``. Default value :drm:`first`.
:param #key value-key: An instance of type :drm:``. Default value :drm:`second`.
:value string: An instance of type ``false-or()``.
:value success: An instance of type :drm:``.
:value object: An instance of type :drm:``.
:value nmatches: An instance of type :drm:``.
:valuecompletions: An instance of type :drm:``.
:description:
Completes *string* chunk-wise against the list of *possibilities*,
using the specified *delimiters* to break both *string* and the strings
in *possibilities* into chunks.
*The label-key* and *value-key* arguments are used to extract the
completion string and object from the entries in *possibilities*, and
*predicate* (if supplied) is applied to filter out unwanted objects.
The function returns five values: the completed string (if there is
one), whether or not the completion successfully matched, the object
associated with the completion, the number of things that matched, and
(if *action* is ``#"completions"``) a sequence of possible completions.
The *action* argument can take any of the following values:
- ``#"complete"`` Completes the input as much as possible, except that if
the user's input exactly matches one of the possibilities, the
shorter possibility is returned as the result, even if it is a left
substring of another possibility.
- ``#"complete-limited"`` Completes the input up to the next partial
delimiter.
- ``#"complete-maximal"`` Completes the input as much as possible.
- ``#"completions"`` or ``#"apropos-completions"`` Returns a sequence of
the possible completions.
:example:
.. code-block:: dylan
complete-from-sequence("s w ma",
#["one fish two fish",
"red fish blue fish",
"single white male",
"on beyond zebra"],
#[' ', '-'],
label-key: identity,
value-key: identity)
:seealso:
- :gf:`complete-from-generator`
.. generic-function:: compute-next-page
Returns the next page in the specified wizard frame.
:signature: compute-next-page *dialog* => *next-page*
:param dialog: An instance of type :class:``.
:next-page: An instance of type ``false-or()``.
:description:
Returns the next page in *dialog*, which must be a wizard.
:seealso:
- :gf:`compute-previous-page`
- :class:``
.. generic-function:: compute-previous-page
Returns the previous page in the specified wizard frame.
:signature: compute-previous-page *dialog* => *prev-page*
:param dialog: An instance of type :class:``.
:value prev-page: An instance of type ``false-or()``.
:description:
Returns the previous page in *dialog*, which must be a wizard.
:seealso:
- :gf:`compute-next-page`
- :class:``
.. generic-function:: contain
Creates and returns a frame containing the specified object.
:signature: contain *object* #rest *initargs* #key *own-thread?* #all-keys => *sheet* *frame*
:param object: An instance of type ``type-union(, , `.
:param #key own-thread?: An instance of type :drm:``.
:value sheet: An instance of type :class:``.
:value frame: An instance of type :class:`));
This is equivalent to the fuller expression:
.. code-block:: dylan
begin
let frame = make(,
title: "container",
layout: make());
start-frame(frame);
end;
As can be seen, when testing short pieces of code interactively in the
environment, the former section of code is easier to use than the
latter.
:example:
Assigning the result of a contain expression allows you to manipulate
the DUIM objects being contained interactively, as shown in the example
below.
You should assume the following code is typed into the Dylan Interactor,
and that each expression is evaluated by pressing the RETURN key at the
points indicated.
.. code-block:: dylan
*g* := contain
(make
(,
items: #(#"One", #"Two", #"Three"),
label-key:
method (symbol) as-lowercase
(as(, symbol))
end)); // RETURN
gadget-items(*g*); // RETURN
As you would expect, evaluating the call to
:gf:`gadget-items` returns the following result:
.. code-block:: dylan
#(#"one", #"two", #"three")
In a similar way, you can destructively modify the slot values of any
contained DUIM objects
.. function:: current-frame
Returns the current frame
:signature: current-frame => *frame*
:value frame: An instance of type :class:``,
but with additional options.
The *supers* argument specifies a comma-separated list of command tables
from which the command table you are creating should inherit. If you are
not explicitly inheriting the behavior of other command tables, then
*supers* should have the value :var:`*global-command-table*`.
Each one of the *options* supplied describes a command for the command
table. This can be either a menu item, a separator, or another command
table to be included in the command table. You can supply any number of
options. Each option take one of the following forms:
.. code-block:: dylan
menu-item *menu-item-descriptor* ;
include *command-table-name* ;
separator;
To add a menu item or menu to a command table, include an option of the
following form:
.. code-block:: dylan
menu-item *label* = *command-function* #key *accelerator documentation*
*label*
An instance of :drm:``. This is the label that appears in
the menu.
*command-function*
An instance of ``type-union(, , )``.
The command function is the callback that is invoked to perform the
intended operation for the menu item. Note that this can itself be
a command table.
*accelerator*
An instance of ``false-or()``. Default value: ``#f``. This
defines a keyboard accelerator that can be used to invoke *command-function*
in preference to the menu item itself.
*documentation*
An instance of ``false-or()``. Default value:
``#f``. This specifies a documentation string for the menu item that
can be used to provide online help to the user. For menu items,
documentation strings are usually displayed in the status bar of your
application, when the mouse pointer is placed over the menu item
itself.
To add a separator to a menu, just include the following option at the
point you want the separator to appear:
.. code-block:: dylan
separator;
To include another command table in the current table, include the
following option at the point you want the command table to appear:
.. code-block:: dylan
include *command-table-name* ;
The commands defined in *command-table-name* are added to the current
command table at the appropriate point.
:example:
The following example shows how you might create a command table for the
standard Windows *File* menu, and how this could be integrated into the
menu bar for an application. The example assumes that the appropriate
command functions have already been defined for each command in the
command table.
.. code-block:: dylan
define command-table
*file-menu-command-table* (*global-command-table*)
menu-item "New..." = frame-new-file,
accelerator:
make-keyboard-gesture(#"n", #"control"),
documentation: "Creates a new document."
menu-item "Open..." = frame-open-file,
accelerator:
make-keyboard-gesture(#"o", #"control"),
documentation: "Opens an existing document.";
menu-item "Close" = frame-close-file,
documentation: "Closes an open document.";
separator;
include *save-files-command-table*;
separator;
menu-item "Exit"
= make(,
function: exit-frame);
end command-table *file-menu-command-table*;
define command-table
*application-command-table* (*global-command-table*)
menu-item "File" = *file-menu-command-table*;
menu-item "Edit" = *edit-menu-command-table*;
menu-item "View" = *view-menu-command-table*;
menu-item "Windows" = *windows-menu-command-table*;
menu-item "Help" = *help-menu-command-table*;
end command-table *application-command-table*;
:seealso:
- :var:`*global-command-table*`
.. macro:: define frame
:defining:
Defines a new class of frame with the specified properties.
:macrocall:
.. code-block:: dylan
define frame *name* ({*supers* }, *) {*slots-panes-options* } end
:param name: A Dylan name *bnf*.
:param supers: A Dylan name *bnf*.
:param slots-panes-options: A Dylan body *bnf*.
:description:
Defines a new class of frame called *name* with the specified
properties. This macro is equivalent to :drm:`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 :class:`` or :class:``.
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 :drm:`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 :class:``.
*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 :macro:`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
:gf:`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
:class:``.
*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 :class:`` 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:
.. code-block:: dylan
define frame ()
...
pages (frame)
vector(frame.page-1, frame.page-2, frame.page-3);
end frame
The *name*, *supers*, and slot arguments are not evaluated. The values
of each of the options are evaluated.
:example:
.. code-block:: dylan
define frame ()
pane label-pane (frame)
make(, items: #("&Red", "&Green",
"&Blue"));
pane check-one (frame)
make(, label: "Check box test text");
pane check-two (frame)
make(, label: "Check box test text");
pane radio-box (frame)
make(,
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:");
horizontally (spacing: 4,
y-alignment: #"center")
frame.label-pane;
make(, 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 ;
:seealso:
- :class:``
- :class:``
.. generic-function:: deiconify-frame
Displays a frame that has previously been iconified on screen.
:signature: deiconify-frame *frame* => ()
:param frame: An instance of type :class:`, title: "A frame",
layout: make());
start-frame(*frame*);
iconify-frame(*frame*);
deiconify-frame(*frame*);
:seealso:
- :gf:`destroy-frame`
- :gf:`exit-frame`
- :gf:`frame-icon`
- :gf:`iconify-frame`
.. generic-function:: destroy-frame
Unmaps the specified frame and destroys it.
:signature: destroy-frame *frame* => ()
:param frame: An instance of type :class:``
- :gf:`iconify-frame`
- :gf:`lower-frame`
- :gf:`raise-frame`
.. generic-function:: dialog-apply-button
Returns the Apply button in the specified dialog.
:signature: dialog-apply-button *dialog* => *apply-button*
:param dialog: An instance of type :class:``.
:value apply-button: An instance of type ``false-or()``.
:description:
Returns the Apply button in *dialog*. As well as having OK and Cancel
buttons, many dialogs also have an Apply button that lets the user apply
the changes that have been made in the dialog, without removing the
dialog from the screen itself.
:seealso:
- :gf:`dialog-cancel-button`
- :gf:`dialog-apply-button-setter`
- :gf:`dialog-apply-callback`
- :gf:`dialog-help-button`
.. generic-function:: dialog-apply-button-setter
Specifies the Apply button in the specified dialog.
:signature: dialog-apply-button-setter *apply-button dialog* => *apply-button*
:param apply-button: An instance of type ``false-or()``.
:param dialog: An instance of type :class:``.
:value apply-button: An instance of type ``false-or()``.
:description:
Specifies the Apply button in *dialog*. As well as having OK and Cancel
buttons, many dialogs also have an Apply button that lets the user apply
the changes that have been made in the dialog, without removing the
dialog from the screen itself.
:seealso:
- :gf:`dialog-cancel-button`
- :gf:`dialog-apply-button`
- :gf:`dialog-apply-callback`
- :gf:`dialog-help-button`
.. generic-function:: dialog-apply-callback
Returns the callback invoked when the Apply button is clicked in the
specified dialog.
:signature: dialog-apply-callback *dialog* => *callback*
:param dialog: An instance of type :class:``.
:value callback: An instance of type ``false-or(, )``.
:description:
Returns the callback invoked when the Apply button is clicked in
*dialog*. As well as having OK and Cancel buttons, many dialogs also
have an Apply button that lets the user apply the changes that have been
made in the dialog, without removing the dialog from the screen itself.
.. note:: If you supply ``#f`` as the callback, then the button does not
appear.
:seealso:
- :gf:`dialog-cancel-button`
- :gf:`dialog-apply-button`
- :gf:`dialog-apply-button-setter`
- :gf:`dialog-help-button`
.. generic-function:: dialog-back-button
Returns the Back button in the specified multi-page dialog.
:signature: dialog-back-button *dialog* => *back-button*
:param dialog: An instance of type :class:``.
:value back-button: An instance of type ``false-or()``.
:description:
Returns the Back button in *dialog*. This is most useful in multi-page
dialogs such as property frames and wizard frames, which typically have
Back and Next buttons that let the user navigate forward and backward
through the sequence of pages that comprise the dialog.
:seealso:
- :gf:`dialog-back-button-setter`
- :gf:`dialog-back-callback`
- :gf:`dialog-exit-button`
- :gf:`dialog-help-button`
.. generic-function:: dialog-back-button-setter
Specifies the Back button in the specified multi-page dialog.
:signature: dialog-back-button-setter *back-button dialog* => *back-button*
:param back-button: An instance of type :class:``.
:param dialog: An instance of type :class:``.
:value back-button: An instance of type :class:``.
:description:
Specifies the Back button in *dialog*. This is most useful in wizard
frames, which typically have Back and Next buttons that let the user
navigate forward and backward through the sequence of pages that
comprise the dialog.
:seealso:
- :gf:`dialog-back-button`
- :gf:`dialog-back-callback`
- :gf:`dialog-exit-button-setter`
- :gf:`dialog-help-button`
.. generic-function:: dialog-back-callback
Returns the callback invoked when the Back button is clicked in the
specified multi-page dialog.
:signature: dialog-apply-callback *dialog* => *callback*
:param dialog: An instance of type :class:``.
:value callback: An instance of type ``false-or(, )``.
:description:
Returns the callback invoked when the Back button is clicked in *dialog*.
This is most useful in wizard frames, which typically have Back and
Next buttons that let the user navigate forward and backward through the
sequence of pages that comprise the dialog.
.. note:: If you do not explicitly supply this callback, the previous page
in the sequence for the multi-page dialog is displayed when the Back
button is clicked. Specifying your own callback gives you flexibility in
describing how the user can navigate through the sequence of pages in
the dialog.
:seealso:
- :gf:`dialog-back-button`
- :gf:`dialog-back-button-setter`
- :gf:`dialog-exit-callback`
- :gf:`dialog-help-button`
.. generic-function:: dialog-cancel-button
Returns the Cancel button in the specified dialog.
:signature: dialog-cancel-button *dialog* => *cancel-button*
:param dialog: An instance of type :class:`