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