blob: f5fb3e0409c7529e67fed77a5a0f57ac4aab2db8 [file] [log] [blame]
David Scherer7aced172000-08-15 01:13:23 +00001Writing an IDLE extension
Kurt B. Kaisercca91222003-07-16 03:10:43 +00002=========================
David Scherer7aced172000-08-15 01:13:23 +00003
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
Kurt B. Kaisercca91222003-07-16 03:10:43 +000011the file config-extensions.def. See below for details.
David Scherer7aced172000-08-15 01:13:23 +000012
13An IDLE extension is defined by a class. Methods of the class define
Kurt B. Kaisercca91222003-07-16 03:10:43 +000014actions that are invoked by event bindings or menu entries. Class (or
David Scherer7aced172000-08-15 01:13:23 +000015instance) 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 guarateed 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
Kurt B. Kaisercca91222003-07-16 03:10:43 +000030The extension class must not directly bind Window Manager (e.g. X) events.
31Rather, it must define one or more virtual events, e.g. <<zoom-height>>, and
32corresponding methods, e.g. zoom_height_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.)
David Scherer7aced172000-08-15 01:13:23 +000037
Kurt B. Kaisercca91222003-07-16 03:10:43 +000038An 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).
David Scherer7aced172000-08-15 01:13:23 +000047
Kurt B. Kaisercca91222003-07-16 03:10:43 +000048At 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.)
David Scherer7aced172000-08-15 01:13:23 +000052
Kurt B. Kaisercca91222003-07-16 03:10:43 +000053Extensions are not required to define menu entries for all the events they
Kurt B. Kaiser610c7e02004-04-24 03:01:48 +000054implement. (They are also not required to create keybindings, but in that
55case there must be empty bindings in cofig-extensions.def)
David Scherer7aced172000-08-15 01:13:23 +000056
57Here is a complete example example:
58
59class ZoomHeight:
60
61 menudefs = [
62 ('edit', [
63 None, # Separator
64 ('_Zoom Height', '<<zoom-height>>'),
65 ])
66 ]
67
David Scherer7aced172000-08-15 01:13:23 +000068 def __init__(self, editwin):
69 self.editwin = editwin
70
71 def zoom_height_event(self, event):
72 "...Do what you want here..."
73
Kurt B. Kaisercca91222003-07-16 03:10:43 +000074The final piece of the puzzle is the file "config-extensions.def", which is
75used to to configure the loading of extensions and to establish key (or, more
76generally, event) bindings to the virtual events defined in the extensions.
Kurt B. Kaiser40610542001-07-14 05:18:59 +000077
Kurt B. Kaisercca91222003-07-16 03:10:43 +000078See 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.
Kurt B. Kaiser40610542001-07-14 05:18:59 +000081
Kurt B. Kaisercca91222003-07-16 03:10:43 +000082For further information on binding refer to the Tkinter Resources web page at
83python.org and to the Tk Command "bind" man page.