Initial revision

Lib/idlelib/extend.txt

@@ -0,0 +1,106 @@
+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 extend.py; 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 "extend.py", which contains a
+simple table used to configure the loading of extensions.  This file
+currently contains a single list variable named "standard", which is a
+list of extension names that are to be loaded.  (In the future, other
+configuration variables may be added to this module.)
+
+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.