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
source code.)
The list of extensions loaded at startup time is configured by editing
-the file config.txt; see below for details.
+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 those bindings or menu entries. Class (or
+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.
(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.)
+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:
])
]
- 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).
+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.
-Extensions are not required to define menu entries for all events they
-implement.
+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.
-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.
+For further information on binding refer to the Tkinter Resources web page at
+python.org and to the Tk Command "bind" man page.
projects / python / commitdiff