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