mirror of
https://github.com/python/cpython.git
synced 2024-12-01 11:15:56 +01:00
121 lines
4.8 KiB
Plaintext
121 lines
4.8 KiB
Plaintext
Writing an IDLE extension
|
|
|
|
An IDLE extension can define new key bindings and menu entries for IDLE
|
|
edit windows. There is a simple mechanism to load extensions when IDLE
|
|
starts up and to attach them to each edit window. (It is also possible
|
|
to make other changes to IDLE, but this must be done by editing the IDLE
|
|
source code.)
|
|
|
|
The list of extensions loaded at startup time is configured by editing
|
|
the file config.txt; see below for details.
|
|
|
|
An IDLE extension is defined by a class. Methods of the class define
|
|
actions that are invoked by those bindings or menu entries. Class (or
|
|
instance) variables define the bindings and menu additions; these are
|
|
automatically applied by IDLE when the extension is linked to an edit
|
|
window.
|
|
|
|
An IDLE extension class is instantiated with a single argument,
|
|
`editwin', an EditorWindow instance. The extension cannot assume much
|
|
about this argument, but it is guarateed to have the following instance
|
|
variables:
|
|
|
|
text a Text instance (a widget)
|
|
io an IOBinding instance (more about this later)
|
|
flist the FileList instance (shared by all edit windows)
|
|
|
|
(There are a few more, but they are rarely useful.)
|
|
|
|
The extension class must not bind key events. Rather, it must define
|
|
one or more virtual events, e.g. <<zoom-height>>, and corresponding
|
|
methods, e.g. zoom_height_event(), and have one or more class (or instance)
|
|
variables that define mappings between virtual events and key sequences,
|
|
e.g. <Alt-F2>. When the extension is loaded, these key sequences will
|
|
be bound to the corresponding virtual events, and the virtual events
|
|
will be bound to the corresponding methods. (This indirection is done
|
|
so that the key bindings can easily be changed, and so that other
|
|
sources of virtual events can exist, such as menu entries.)
|
|
|
|
The following class or instance variables are used to define key
|
|
bindings for virtual events:
|
|
|
|
keydefs for all platforms
|
|
mac_keydefs for Macintosh
|
|
windows_keydefs for Windows
|
|
unix_keydefs for Unix (and other platforms)
|
|
|
|
Each of these variables, if it exists, must be a dictionary whose
|
|
keys are virtual events, and whose values are lists of key sequences.
|
|
|
|
An extension can define menu entries in a similar fashion. This is done
|
|
with a class or instance variable named menudefs; it should be a list of
|
|
pair, where each pair is a menu name (lowercase) and a list of menu
|
|
entries. Each menu entry is either None (to insert a separator entry) or
|
|
a pair of strings (menu_label, virtual_event). Here, menu_label is the
|
|
label of the menu entry, and virtual_event is the virtual event to be
|
|
generated when the entry is selected. An underscore in the menu label
|
|
is removed; the character following the underscore is displayed
|
|
underlined, to indicate the shortcut character (for Windows).
|
|
|
|
At the moment, extensions cannot define whole new menus; they must
|
|
define entries in existing menus. Some menus are not present on some
|
|
windows; such entry definitions are then ignored, but the key bindings
|
|
are still applied. (This should probably be refined in the future.)
|
|
|
|
Here is a complete example example:
|
|
|
|
class ZoomHeight:
|
|
|
|
menudefs = [
|
|
('edit', [
|
|
None, # Separator
|
|
('_Zoom Height', '<<zoom-height>>'),
|
|
])
|
|
]
|
|
|
|
windows_keydefs = {
|
|
'<<zoom-height>>': ['<Alt-F2>'],
|
|
}
|
|
unix_keydefs = {
|
|
'<<zoom-height>>': ['<Control-z><Control-z>'],
|
|
}
|
|
|
|
def __init__(self, editwin):
|
|
self.editwin = editwin
|
|
|
|
def zoom_height_event(self, event):
|
|
"...Do what you want here..."
|
|
|
|
The final piece of the puzzle is the file "config.txt", which is used
|
|
to to configure the loading of extensions. For each extension,
|
|
you must include a section in config.txt (or in any of the other
|
|
configuration files that are consulted at startup: config-unix.txt,
|
|
config-win.txt, or ~/.idle). A section is headed by the module name
|
|
in square brackets, e.g.
|
|
|
|
[ZoomHeight]
|
|
|
|
The section may be empty, or it may define configuration options for
|
|
the extension. (See ParenMatch.py for an example.) A special option
|
|
is 'enable': including
|
|
|
|
enable = 0
|
|
|
|
in a section disables that extension. More than one configuration
|
|
file may specify options for the same extension, so a user may disable
|
|
an extension that is loaded by default, or enable an extension that is
|
|
disabled by default.
|
|
|
|
Extensions can define key bindings and menu entries that reference
|
|
events they don't implement (including standard events); however this is
|
|
not recommended (and may be forbidden in the future).
|
|
|
|
Extensions are not required to define menu entries for all events they
|
|
implement.
|
|
|
|
Note: in order to change key bindings, you must currently edit the file
|
|
keydefs. It contains two dictionaries named and formatted like the
|
|
keydefs dictionaries described above, one for the Unix bindings and one
|
|
for the Windows bindings. In the future, a better mechanism will be
|
|
provided.
|