1Writing an IDLE extension 2========================= 3 4An IDLE extension can define new key bindings and menu entries for IDLE 5edit windows. There is a simple mechanism to load extensions when IDLE 6starts up and to attach them to each edit window. (It is also possible 7to make other changes to IDLE, but this must be done by editing the IDLE 8source code.) 9 10The list of extensions loaded at startup time is configured by editing 11the file config-extensions.def. See below for details. 12 13An IDLE extension is defined by a class. Methods of the class define 14actions that are invoked by event bindings or menu entries. Class (or 15instance) variables define the bindings and menu additions; these are 16automatically applied by IDLE when the extension is linked to an edit 17window. 18 19An IDLE extension class is instantiated with a single argument, 20`editwin', an EditorWindow instance. The extension cannot assume much 21about this argument, but it is guaranteed to have the following instance 22variables: 23 24 text a Text instance (a widget) 25 io an IOBinding instance (more about this later) 26 flist the FileList instance (shared by all edit windows) 27 28(There are a few more, but they are rarely useful.) 29 30The extension class must not directly bind Window Manager (e.g. X) events. 31Rather, it must define one or more virtual events, e.g. <<z-in>>, and 32corresponding methods, e.g. z_in_event(). The virtual events will be 33bound to the corresponding methods, and Window Manager events can then be bound 34to the virtual events. (This indirection is done so that the key bindings can 35easily be changed, and so that other sources of virtual events can exist, such 36as menu entries.) 37 38An extension can define menu entries. This is done with a class or instance 39variable named menudefs; it should be a list of pairs, where each pair is a 40menu name (lowercase) and a list of menu entries. Each menu entry is either 41None (to insert a separator entry) or a pair of strings (menu_label, 42virtual_event). Here, menu_label is the label of the menu entry, and 43virtual_event is the virtual event to be generated when the entry is selected. 44An underscore in the menu label is removed; the character following the 45underscore is displayed underlined, to indicate the shortcut character (for 46Windows). 47 48At the moment, extensions cannot define whole new menus; they must define 49entries in existing menus. Some menus are not present on some windows; such 50entry definitions are then ignored, but key bindings are still applied. (This 51should probably be refined in the future.) 52 53Extensions are not required to define menu entries for all the events they 54implement. (They are also not required to create keybindings, but in that 55case there must be empty bindings in cofig-extensions.def) 56 57Here is a partial example from zzdummy.py: 58 59class ZzDummy: 60 61 menudefs = [ 62 ('format', [ 63 ('Z in', '<<z-in>>'), 64 ('Z out', '<<z-out>>'), 65 ] ) 66 ] 67 68 def __init__(self, editwin): 69 self.editwin = editwin 70 71 def z_in_event(self, event=None): 72 "...Do what you want here..." 73 74The final piece of the puzzle is the file "config-extensions.def", which is 75used to configure the loading of extensions and to establish key (or, more 76generally, event) bindings to the virtual events defined in the extensions. 77 78See the comments at the top of config-extensions.def for information. It's 79currently necessary to manually modify that file to change IDLE's extension 80loading or extension key bindings. 81 82For further information on binding refer to the Tkinter Resources web page at 83python.org and to the Tk Command "bind" man page. 84