Adding Menus To The Application#
Now it is time to consider adding some menus to your application. There are two basic ways that you can create a system of menus for your application:
Design a hierarchical series of panes using the
<menu-bar>,<menu>, and various menu buttons classes, and glue the elements of this design together in the correct order.Use a command table.
In this chapter, the first of these methods is demonstrated. For information about command tables, refer to Using Command Tables. Before discussing the first method listed above, the overall design of the menu system for the task list manager is discussed.
A description of the menu system#
Before implementing the menus for the task list manager, it is worth describing what you are going to implement. The menu system of the task list manager comprises four menus: a File menu, Edit menu, Task menu, and Help. Each of these menus contains a number of commands, as follows:
File menu The File menu contains four commands that operate on the files loaded into the task list manager. The Open command opens a new file. The Save command saves the currently loaded file to disk. The Save As command saves the currently loaded file to disk under a new name. The Exit command quits the task application completely.
Edit menu The Edit menu contains the standard clipboard commands: Cut, Copy, and Paste.
Task menu The Task menu contains two commands that operate on individual tasks. The Add command adds a new task to the list. The Remove command removes the selected task from the list.
Help menu In a full-blown application, you would use commands in the Help menu as one hook into your online help system (other hooks being provided by buttons in dialog boxes and the F1 key). In this application, the Help menu contains a single command that simply displays a simple About dialog for the application.
Creating a menu hierarchy#
As you might expect, creating a menu hierarchy in a frame definition is
a matter of defining a series of panes for the frame. At the top-most
level in the menu hierarchy is the menu bar itself. The menu bar
contains each menu defined for the application and each menu contains
the menu commands that themselves perform operations. Once the panes
have been defined, the menu bar needs to be included in the frame using
the menu-bar clause.
First of all, you can create a pane that defines the menu bar itself as follows:
pane task-menu-bar (frame)
make(<menu-bar>,
children: vector(frame.file-menu,
frame.edit-menu,
frame.task-menu,
frame.help-menu));
Next, define the File and Tasks menus themselves:
pane file-menu (frame)
make(<menu>, label: "File",
children: vector(frame.open-menu-button,
frame.save-menu-button,
frame.save-as-menu-button,
frame.exit-menu-button));
pane edit-menu (frame)
make(<menu>, label: "Edit",
children: vector(frame.cut-menu-button,
frame.copy-menu-button,
frame.paste-menu-button));
pane task-menu (frame)
make(<menu>, label: "Task",
children: vector(frame.add-menu-button,
frame.remove-menu-button));
pane help-menu (frame)
make(<menu>, label: "Help",
children: vector(frame.about-menu-button));
Finally, you need to define the menu commands themselves. A command that
appears on a menu is defined as an instance of <menu-button>, and so
there is a strong similarity between these buttons and some of the
buttons already defined. DUIM also generates mnemonics for each menu
item; thus, the items appear as File and Edit, and so forth. (Note
that the make-keyboard-gesture function that appears below is defined
in Keyboard accelerators.)
// Commands in the File menu
pane open-menu-button (frame)
make(<menu-button>, label: "Open...",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"o", #"control"),
documentation: "Opens an existing file.");
pane save-menu-button (frame)
make(<menu-button>, label: "Save",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"s", #"control"),
documentation: "Saves the current file to disk.");
pane save-as-menu-button (frame)
make(<menu-button>, label: "Save As...",
activate-callback: save-as-file,
documentation: "Saves the current file with a new name.");
pane exit-menu-button (frame)
make(<menu-button>, label: "Exit",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"f4", #"alt"),
documentation: "Exits the application.");
//Commands in the Edit menu
pane cut-menu-button (frame)
make(<menu-button>, label: "Cut",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"x", #"control"),
documentation: "Cut the selection to the clipboard.");
pane copy-menu-button (frame)
make(<menu-button>, label: "Copy",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"c", #"control"),
documentation: "Copy the selection to the clipboard.");
pane paste-menu-button (frame)
make(<menu-button>, label: "Paste",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"v", #"control"),
documentation: "Paste the selection in the clipboard at the current position.");
//Commands in the Task menu
pane add-menu-button (frame)
make(<menu-button>, label: "Add...",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture
(#"a", #"control", #"shift"),
documentation: "Add a new task.");
pane remove-menu-button (frame)
make(<menu-button>, label: "Remove",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture
(#"d", #"control", #"shift"),
documentation: "Remove the selected task from the list.");
//Commands in the Help menu
pane about-menu-button (frame)
make(<menu-button>, label: "About",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"f1"),
documentation:
"Display information about the application.");
Once you have defined the menu bar and all the children that it is to contain, you need to activate the menu bar in the frame by including the following towards the end of the frame definition.
menu-bar (frame) frame.task-menu-bar;
The definitions of these menu buttons demonstrate two interesting new features: the use of keyboard accelerators, and the use of documentation strings.
Documentation strings#
Documentation strings let you provide brief online help for gadgets such
as menu buttons. You can specify a documentation string for any gadget
using the documentation: init-keyword. Although you can make whatever
use you want of these strings, using the gadget-documentation and
gadget-documentation-setter methods, documentation strings for menu
buttons are used in status bars without any need for special action on
your part. If you display a menu and move the mouse pointer over the
items in the menu, then the documentation string defined for each item
is displayed in the status bar of the frame for as long as the mouse
pointer is over the menu item. It is generally good practice to supply
documentation strings for all the menu items in a frame. Documentation
strings for other gadgets become tooltips in Windows.
Keyboard accelerators#
Keyboard accelerators let you define a combination of keys that can be pressed in order to invoke the activate callback of a gadget. This means that you can access the functionality of an application without having to choose commands from menus using the mouse, and can make it much quicker to use an application you are familiar with.
To specify a keyboard accelerator, you need to specify an alphanumeric
character, or a function key, together with any modifier keys (such as
the CONTROL or ALT keys) that should be held down while the alphanumeric
character is pressed. You actually create a keyboard accelerator by
calling the make method on <keyboard-gesture>, though to make it a
little easier, define the function below, which is used in the
definition of each menu button.
define function make-keyboard-gesture
(keysym :: <symbol>, #rest modifiers)
=> (gesture :: <keyboard-gesture>)
make(<keyboard-gesture>, keysym: keysym, modifiers: modifiers)
end function make-keyboard-gesture;
Add this definition to the file frame.dylan.
The keyboard accelerators defined demonstrate the several useful points about keyboard accelerators:
Whenever possible, use standard keyboard accelerators for standard application commands on your platform. Here, you use CONTROL+O to open a file, CONTROL+S to save a file, and CONTROL+X, CONTROL+C, and CONTROL+V respectively for Cut, Copy, and Paste.
As well as standard alphanumeric characters, you can use function keys as keyboard accelerators.
As well as the more common CONTROL key, you can use the ALT and SHIFT keys as modifiers, though you should not use the SHIFT key as the sole modifier.
You can use more than one modifier key at once.
If you wish, you need not use any modifier keys at all, as is the case with the (slightly non-standard) keyboard accelerator for the About command.
Gluing the final design together#
You can now add the definitions of the menu bar, menus, and menu
buttons, to the definition of the <task-frame> class, to give the code
shown below. At this stage, the only thing missing from the final
application are real callback functions. Callbacks are dealt with in
Adding Callbacks to the Application.
Note that the final definition of <task-frame> includes the
definition of a slot: frame-task-list. This takes an instance of
the class <task-list> as a value, the default value being an empty
<task-list>. Although it has not been referred to so far, this
class will be used as the basic data structure in which task lists are
stored, and a more complete description of these data structures is
given in Defining the underlying data structures for tasks. It
transpires that defining the frame-task-list slot is essential for
some of the file handling routines that are described in Handling
files in the task list manager.
define frame <task-frame> (<simple-frame>)
slot frame-task-list :: <task-list> = make(<task-list>);
// definition of menu bar
pane task-menu-bar (frame)
make(<menu-bar>,
children: vector(frame.file-menu,
frame.edit-menu,
frame.task-menu,
frame.help-menu));
// definition of menus
pane file-menu (frame)
make(<menu>, label: "File",
children: vector(frame.open-menu-button,
frame.save-menu-button,
frame.save-as-menu-button,
frame.exit-menu-button));
pane edit-menu (frame)
make(<menu>, label: "Edit",
children: vector(frame.cut-menu-button,
frame.copy-menu-button,
frame.paste-menu-button));
pane task-menu (frame)
make(<menu>, label: "Task",
children: vector(frame.add-menu-button,
frame.remove-menu-button));
pane help-menu (frame)
make(<menu>, label: "Help",
children: vector(frame.about-menu-button));
// definition of menu buttons
// Commands in the File menu
pane open-menu-button (frame)
make(<menu-button>, label: "Open...",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"o", #"control"),
documentation: "Opens an existing file.");
pane save-menu-button (frame)
make(<menu-button>, label: "Save",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"s", #"control"),
documentation: "Saves the current file to disk.");
pane save-as-menu-button (frame)
make(<menu-button>, label: "Save As...",
activate-callback: save-as-file,
documentation:
"Saves the current file with a new name.");
pane exit-menu-button (frame)
make(<menu-button>, label: "Exit",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"f4", #"alt"),
documentation: "Exits the application.");
//Commands in the Edit menu
pane cut-menu-button (frame)
make(<menu-button>, label: "Cut",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"x", #"control"),
documentation: "Cut the selection to the clipboard.");
pane copy-menu-button (frame)
make(<menu-button>, label: "Copy",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"c", #"control"),
documentation: "Copy the selection to the clipboard.");
pane paste-menu-button (frame)
make(<menu-button>, label: "Paste",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"v", #"control"),
documentation:
"Paste the selection in the clipboard at the current position.");
//Commands in the Task menu
pane add-menu-button (frame)
make(<menu-button>, label: "Add...",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture
(#"a", #"control", #"shift"),
documentation: "Add a new task.");
pane remove-menu-button (frame)
make(<menu-button>, label: "Remove",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture
(#"d", #"control", #"shift"),
documentation:
"Remove the selected task from the list.");
//Commands in the Help menu
pane about-menu-button (frame)
make(<menu-button>, label: "About",
activate-callback: not-yet-implemented,
accelerator: make-keyboard-gesture(#"f1"),
documentation:
"Display information about the application.");
// definition of buttons
pane add-button (frame)
make(<push-button>, label: "Add task",
activate-callback: not-yet-implemented);
pane remove-button (frame)
make(<push-button>, label: "Remove task",
activate-callback: not-yet-implemented);
pane open-button (frame)
make(<push-button>, label: "Open file",
activate-callback: not-yet-implemented);
pane save-button (frame)
make(<push-button>, label: "Save file",
activate-callback: not-yet-implemented);
// definition of radio box
pane priority-box (frame)
make (<radio-box>,
items: $priority-items,
orientation: #"horizontal",
label-key: first,
value-key: second,
value: #"medium",
activate-callback: not-yet-implemented);
// definition of tool bar
pane task-tool-bar (frame)
make(<tool-bar>,
child: horizontally ()
frame.open-button;
frame.save-button;
frame.add-button;
frame.remove-button
end);
// definition of status bar
pane task-status-bar (frame)
make(<status-bar>, label: "Task Manager");
// definition of list
pane task-list (frame)
make (<list-box>, items: #(), lines: 15,
activate-callback: not-yet-implemented);
// main layout
pane task-layout (frame)
vertically ()
frame.task-list;
frame.priority-box;
end;
// activation of frame elements
layout (frame) frame.task-layout;
tool-bar (frame) frame.task-tool-bar;
status-bar (frame) frame.task-status-bar;
menu-bar (frame) frame.task-menu-bar;
// frame title
keyword title: = "Task List Manager";
end frame <task-frame>;