Lib/idlelib/extend.txt

   1 Writing an IDLE extension
   2
   3 An IDLE extension can define new key bindings and menu entries for IDLE
   4 edit windows.  There is a simple mechanism to load extensions when IDLE
   5 starts up and to attach them to each edit window. (It is also possible
   6 to make other changes to IDLE, but this must be done by editing the IDLE
   7 source code.)
   8
   9 The list of extensions loaded at startup time is configured by editing
  10 the file config.txt; see below for details.
  11
  12 An IDLE extension is defined by a class.  Methods of the class define
  13 actions that are invoked by those bindings or menu entries. Class (or
  14 instance) variables define the bindings and menu additions; these are
  15 automatically applied by IDLE when the extension is linked to an edit
  16 window.
  17
  18 An IDLE extension class is instantiated with a single argument,
  19 `editwin', an EditorWindow instance. The extension cannot assume much
  20 about this argument, but it is guarateed to have the following instance
  21 variables:
  22
  23     text        a Text instance (a widget)
  24     io          an IOBinding instance (more about this later)
  25     flist       the FileList instance (shared by all edit windows)
  26
  27 (There are a few more, but they are rarely useful.)
  28
  29 The extension class must not bind key events.  Rather, it must define
  30 one or more virtual events, e.g. <<zoom-height>>, and corresponding
  31 methods, e.g. zoom_height_event(), and have one or more class (or instance)
  32 variables that define mappings between virtual events and key sequences,
  33 e.g. <Alt-F2>.  When the extension is loaded, these key sequences will
  34 be bound to the corresponding virtual events, and the virtual events
  35 will be bound to the corresponding methods.  (This indirection is done
  36 so that the key bindings can easily be changed, and so that other
  37 sources of virtual events can exist, such as menu entries.)
  38
  39 The following class or instance variables are used to define key
  40 bindings for virtual events:
  41
  42     keydefs             for all platforms
  43     mac_keydefs         for Macintosh
  44     windows_keydefs     for Windows
  45     unix_keydefs        for Unix (and other platforms)
  46
  47 Each of these variables, if it exists, must be a dictionary whose
  48 keys are virtual events, and whose values are lists of key sequences.
  49
  50 An extension can define menu entries in a similar fashion.  This is done
  51 with a class or instance variable named menudefs; it should be a list of
  52 pair, where each pair is a menu name (lowercase) and a list of menu
  53 entries. Each menu entry is either None (to insert a separator entry) or
  54 a pair of strings (menu_label, virtual_event).  Here, menu_label is the
  55 label of the menu entry, and virtual_event is the virtual event to be
  56 generated when the entry is selected.  An underscore in the menu label
  57 is removed; the character following the underscore is displayed
  58 underlined, to indicate the shortcut character (for Windows).
  59
  60 At the moment, extensions cannot define whole new menus; they must
  61 define entries in existing menus.  Some menus are not present on some
  62 windows; such entry definitions are then ignored, but the key bindings
  63 are still applied.  (This should probably be refined in the future.)
  64
  65 Here is a complete example example:
  66
  67 class ZoomHeight:
  68
  69     menudefs = [
  70         ('edit', [
  71             None, # Separator
  72             ('_Zoom Height', '<<zoom-height>>'),
  73          ])
  74     ]
  75
  76     windows_keydefs = {
  77         '<<zoom-height>>': ['<Alt-F2>'],
  78     }
  79     unix_keydefs = {
  80         '<<zoom-height>>': ['<Control-z><Control-z>'],
  81     }
  82
  83     def __init__(self, editwin):
  84         self.editwin = editwin
  85
  86     def zoom_height_event(self, event):
  87         "...Do what you want here..."
  88
  89 The final piece of the puzzle is the file "config.txt", which is used
  90 to to configure the loading of extensions.  For each extension,
  91 you must include a section in config.txt (or in any of the other
  92 configuration files that are consulted at startup: config-unix.txt,
  93 config-win.txt, or ~/.idle).  A section is headed by the module name
  94 in square brackets, e.g.
  95
  96     [ZoomHeight]
  97
  98 The section may be empty, or it may define configuration options for
  99 the extension.  (See ParenMatch.py for an example.)  A special option
 100 is 'enable': including
 101
 102     enable = 0
 103
 104 in a section disables that extension.  More than one configuration
 105 file may specify options for the same extension, so a user may disable
 106 an extension that is loaded by default, or enable an extension that is
 107 disabled by default.
 108
 109 Extensions can define key bindings and menu entries that reference
 110 events they don't implement (including standard events); however this is
 111 not recommended (and may be forbidden in the future).
 112
 113 Extensions are not required to define menu entries for all events they
 114 implement.
 115
 116 Note: in order to change key bindings, you must currently edit the file
 117 keydefs.  It contains two dictionaries named and formatted like the
 118 keydefs dictionaries described above, one for the Unix bindings and one
 119 for the Windows bindings.  In the future, a better mechanism will be
 120 provided.