| 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 guaranteed 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. <<z-in>>, and |
| 32 |
corresponding methods, e.g. z_in_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 config-extensions.def) |
| 56 |
|
| 57 |
Here is a partial example from zzdummy.py: |
| 58 |
|
| 59 |
class 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 |
|
| 74 |
The final piece of the puzzle is the file "config-extensions.def", which is |
| 75 |
used 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. |