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 extend.py; 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 "extend.py", which contains a
  90 simple table used to configure the loading of extensions.  This file
  91 currently contains a single list variable named "standard", which is a
  92 list of extension names that are to be loaded.  (In the future, other
  93 configuration variables may be added to this module.)
  94
  95 Extensions can define key bindings and menu entries that reference
  96 events they don't implement (including standard events); however this is
  97 not recommended (and may be forbidden in the future).
  98
  99 Extensions are not required to define menu entries for all events they
 100 implement.
 101
 102 Note: in order to change key bindings, you must currently edit the file
 103 keydefs.  It contains two dictionaries named and formatted like the
 104 keydefs dictionaries described above, one for the Unix bindings and one
 105 for the Windows bindings.  In the future, a better mechanism will be
 106 provided.