mirror of https://github.com/python/cpython
84 lines
3.5 KiB
Plaintext
84 lines
3.5 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-extensions.def. See below for details.
|
|
|
|
An IDLE extension is defined by a class. Methods of the class define
|
|
actions that are invoked by event 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 directly bind Window Manager (e.g. X) events.
|
|
Rather, it must define one or more virtual events, e.g. <<zoom-height>>, and
|
|
corresponding methods, e.g. zoom_height_event(). The virtual events will be
|
|
bound to the corresponding methods, and Window Manager events can then be bound
|
|
to the virtual events. (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.)
|
|
|
|
An extension can define menu entries. This is done with a class or instance
|
|
variable named menudefs; it should be a list of pairs, 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 key bindings are still applied. (This
|
|
should probably be refined in the future.)
|
|
|
|
Extensions are not required to define menu entries for all the events they
|
|
implement. (XXX KBK 15Jul03: But it appears they must have keybindings for each
|
|
virtual event?)
|
|
|
|
Here is a complete example example:
|
|
|
|
class ZoomHeight:
|
|
|
|
menudefs = [
|
|
('edit', [
|
|
None, # Separator
|
|
('_Zoom Height', '<<zoom-height>>'),
|
|
])
|
|
]
|
|
|
|
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-extensions.def", which is
|
|
used to to configure the loading of extensions and to establish key (or, more
|
|
generally, event) bindings to the virtual events defined in the extensions.
|
|
|
|
See the comments at the top of config-extensions.def for information. It's
|
|
currently necessary to manually modify that file to change IDLE's extension
|
|
loading or extension key bindings.
|
|
|
|
For further information on binding refer to the Tkinter Resources web page at
|
|
python.org and to the Tk Command "bind" man page.
|