Tools/idle/extend.txt

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.