88 lines
8.9 KiB
HTML
88 lines
8.9 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>PyGUI - Customising the Standard Menus</title></head>
|
|
<body>
|
|
<h1>Customising the Standard Menu Bar<br>
|
|
</h1>
|
|
By default, a PyGUI application comes with a standard set of menus
|
|
containing all the commands that the PyGUI framework itself knows about
|
|
- Open, Close, Save, Cut, Copy, Paste and so forth. It's likely that
|
|
you won't use all of these commands in your application, will want to
|
|
omit some of them. It's also likely that you will want to add new
|
|
commands of your own. PyGUI offers a variety of mechanisms to do these
|
|
things in a platform-independent way.<br><h2>Choosing standard menu items</h2>The <a href="StdMenus.html#basic_menus"><span style="font-family: monospace;">basic_menus()</span></a> function from the <a href="StdMenus.html"><span style="font-family: monospace;">StdMenus</span></a>
|
|
module provides a starting point for building your application's main
|
|
menu bar. Without any parameters, it returns a list of menus containing
|
|
all of the standard commands, arranged according to platform
|
|
conventions.<br><br>If you want to be more selective, there are a
|
|
couple of ways to go about it. One is to start with all the standard
|
|
items and take away the ones you don't want using the <span style="font-family: monospace;">exclude</span>
|
|
parameter, which takes a sequence or set of command names. The StdMenus
|
|
module exports a number of predefined command sets to make this easier.
|
|
For example, the following creates a menu bar containing all the
|
|
standard commands except those having to do with files or printing.<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">from GUI.StdMenus import basic_menus, file_cmds, print_cmds</span><br style="font-family: monospace;"><span style="font-family: monospace;">menus = basic_menus(exclude = file_cmds + print_cmds)</span><br></div><br>The menu bar is installed by assigning it to the <span style="font-family: monospace;">menus</span> property of the application.<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">app = MyApplication()<br>app.menus = menus<br></span></div>
|
|
<br>The other way is to start with a minimal set of commands and add the extra ones that you want using the <span style="font-family: monospace;">include</span> parameter. When you specify a value for <span style="font-family: monospace;">include</span>, the menu bar will include only those items, plus the <span style="font-family: monospace;">fundamental_cmds</span> and <span style="font-family: monospace;">edit_cmds</span>,
|
|
which are considered essential for most applications. The following
|
|
creates a menu bar containing only the file-related commands and the
|
|
"Preferences" command in addition to the essential ones.<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">menus = basic_menus(include = file_cmds + prefs_cmds)</span><br></div><br>You can use both <span style="font-family: monospace;">include</span> and <span style="font-family: monospace;">exclude</span>
|
|
together; this is the only way to omit items from the essential set.
|
|
The following includes all of the file-related commands except
|
|
"Revert", and also omits the "Redo" command, which would otherwise be
|
|
implicitly included because it is part of the <span style="font-family: monospace;">edit_cmds</span> set.<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">menus = basic_menus(include = file_cmds, exclude = ['revert_cmd', 'redo_cmd'])</span><br></div><br>Note,
|
|
however, that it is generally a bad idea to exclude items from the
|
|
essential set. On some platforms, for example, the editing commands
|
|
need to be present in the menus in order for their keyboard equivalents
|
|
to work in dialogs.<br><h2>Modifying standard menu items</h2>Sometimes
|
|
you will want to give different titles or keyboard equivalents to
|
|
standard menu commands. For example, in a game you might want the New,
|
|
Open and Save commands to be called "New Game", "Load Game" and "Save
|
|
Game", and give "Load Game" a keyboard equivalent of "L" instead of "O".<br><br>You can do this easily using the <span style="font-family: monospace;">substitutions</span> parameter to <span style="font-family: monospace;">basic_menus()</span>. It takes a dictionary whose keys are command names and values are replacement menu item strings. For example:<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">menus = basic_menus(substitutions = {</span><br style="font-family: monospace;"><span style="font-family: monospace;"> 'new_cmd': "New Game",</span><br style="font-family: monospace;"><span style="font-family: monospace;"> 'open_cmd': "Load Game.../L",</span><br style="font-family: monospace;"><span style="font-family: monospace;"> 'save_cmd': "Save Game",</span><br style="font-family: monospace;"><span style="font-family: monospace;"> 'save_as_cmd': "Save Game As..."})</span><br></div><br>Each
|
|
replacement can override just the title, just the keyboard equivalent,
|
|
or both. In the above example, the keyboard equivalent of <span style="font-family: monospace;">open_cmd</span> is overridden, but the other commands are left with their standard equivalents.<h2>Adding menus</h2>
|
|
The simplest way to add new commands is to create one or more extra menus containing your
|
|
commands, and add them to the end of the application's menu bar. Here's
|
|
an example of how to do this.<br>
|
|
<br>
|
|
<div style="margin-left: 40px;"><span style="font-family: monospace;">menus = basic_menus()</span><br style="font-family: monospace;">
|
|
<span style="font-family: monospace;">my_menu = Menu("Widget", [("Swizzle", 'swiz_cmd'), ("Defibrillate", 'defib_cmd')])</span><span style="font-family: monospace;"></span><span style="font-family: monospace;"></span><span style="font-family: monospace;"></span><br style="font-family: monospace;">
|
|
<span style="font-family: monospace;">menus.append(my_menu)</span><span style="font-family: monospace;"></span><br style="font-family: monospace;">
|
|
<span style="font-family: monospace;">app.menus = menus</span><br>
|
|
</div>
|
|
<br>
|
|
Note that the new menu is added to the menu list <span style="font-style: italic;">before</span> assigning the menu list to the application's <span style="font-family: monospace;">menus</span> property. This is important, to ensure that the menu bar is updated properly.<br>
|
|
<h2>Adding commands to standard menus</h2>
|
|
Adding your own menus is all well and good, but you may want more
|
|
control than that. For example, if you have some editing-related
|
|
commands, you might want to add them to the Edit menu instead of
|
|
putting them in a menu of their own.<br>
|
|
<br>
|
|
The problem with this is finding the right menu to add them to. PyGUI
|
|
tries to make as few assumptions as possible about the layout of the
|
|
standard menus, and if you want your application to be portable, you
|
|
should do the same. So you shouldn't assume, for example, that the Edit
|
|
menu is the second menu in the menu bar. (On the Mac, it's not!) You
|
|
shouldn't even assume that there will <span style="font-style: italic;">be</span> an Edit menu at all.<br>
|
|
<br>
|
|
Rather than a particular menu, it's better to think in terms of putting
|
|
your commands near existing commands. PyGUI helps you out here by means
|
|
of the <a href="MenuList.html">MenuList</a> class. A
|
|
MenuList is just like an ordinary list, except that it also has a
|
|
method that will take an internal command name and give you the menu
|
|
which contains that command. So we can find the menu containing, say,
|
|
the <span style="font-family: monospace;">'copy_cmd'</span> command,
|
|
and be fairly sure that it's the Edit menu, or whatever passes for it,
|
|
on the platform we're running on. Once we've found the menu, we can use
|
|
its <span style="font-family: monospace;">append</span> or <span style="font-family: monospace;">extend</span> methods to add our commands to it.<br>
|
|
<br>The <span style="font-family: monospace;">basic_menus()</span> function returns a MenuList, so here's how we can add some commands to the Edit menu:<br>
|
|
<br>
|
|
<div style="margin-left: 40px;"><span style="font-family: monospace;"></span><span style="font-family: monospace;">menus = basic_menus()</span><span style="font-family: monospace;"><br style="font-family: monospace;"></span>
|
|
<span style="font-family: monospace;">edit_menu = menus.menu_with_command('copy_cmd')</span><span style="font-family: monospace;"><br style="font-family: monospace;">
|
|
</span><span style="font-family: monospace;">edit_menu.extend(["-", ("Biggify", 'enlarge_cmd'), ("Smallify", 'reduce_cmd')])<br></span><span style="font-family: monospace;">app.menus = menus</span><br>
|
|
</div>
|
|
<h2>Future plans</h2>
|
|
One further thing you might want to do is insert commands in the
|
|
middle of a menu (to get them even closer to an existing command). This is
|
|
not currently supported, but is planned for a future version.<br>
|
|
<br>
|
|
---<br>
|
|
<br>
|
|
</body></html> |