Writing an IDLE extension

[0] Fix | Delete

=========================

[1] Fix | Delete

[2] Fix | Delete

An IDLE extension can define new key bindings and menu entries for IDLE

[3] Fix | Delete

edit windows. There is a simple mechanism to load extensions when IDLE

[4] Fix | Delete

starts up and to attach them to each edit window. (It is also possible

[5] Fix | Delete

to make other changes to IDLE, but this must be done by editing the IDLE

[6] Fix | Delete

source code.)

[7] Fix | Delete

[8] Fix | Delete

The list of extensions loaded at startup time is configured by editing

[9] Fix | Delete

the file config-extensions.def. See below for details.

[10] Fix | Delete

[11] Fix | Delete

An IDLE extension is defined by a class. Methods of the class define

[12] Fix | Delete

actions that are invoked by event bindings or menu entries. Class (or

[13] Fix | Delete

instance) variables define the bindings and menu additions; these are

[14] Fix | Delete

automatically applied by IDLE when the extension is linked to an edit

[15] Fix | Delete

window.

[16] Fix | Delete

[17] Fix | Delete

An IDLE extension class is instantiated with a single argument,

[18] Fix | Delete

`editwin', an EditorWindow instance. The extension cannot assume much

[19] Fix | Delete

about this argument, but it is guaranteed to have the following instance

[20] Fix | Delete

variables:

[21] Fix | Delete

[22] Fix | Delete

text a Text instance (a widget)

[23] Fix | Delete

io an IOBinding instance (more about this later)

[24] Fix | Delete

flist the FileList instance (shared by all edit windows)

[25] Fix | Delete

[26] Fix | Delete

(There are a few more, but they are rarely useful.)

[27] Fix | Delete

[28] Fix | Delete

The extension class must not directly bind Window Manager (e.g. X) events.

[29] Fix | Delete

Rather, it must define one or more virtual events, e.g. <<zoom-height>>, and

[30] Fix | Delete

corresponding methods, e.g. zoom_height_event(). The virtual events will be

[31] Fix | Delete

bound to the corresponding methods, and Window Manager events can then be bound

[32] Fix | Delete

to the virtual events. (This indirection is done so that the key bindings can

[33] Fix | Delete

easily be changed, and so that other sources of virtual events can exist, such

[34] Fix | Delete

as menu entries.)

[35] Fix | Delete

[36] Fix | Delete

An extension can define menu entries. This is done with a class or instance

[37] Fix | Delete

variable named menudefs; it should be a list of pairs, where each pair is a

[38] Fix | Delete

menu name (lowercase) and a list of menu entries. Each menu entry is either

[39] Fix | Delete

None (to insert a separator entry) or a pair of strings (menu_label,

[40] Fix | Delete

virtual_event). Here, menu_label is the label of the menu entry, and

[41] Fix | Delete

virtual_event is the virtual event to be generated when the entry is selected.

[42] Fix | Delete

An underscore in the menu label is removed; the character following the

[43] Fix | Delete

underscore is displayed underlined, to indicate the shortcut character (for

[44] Fix | Delete

Windows).

[45] Fix | Delete

[46] Fix | Delete

At the moment, extensions cannot define whole new menus; they must define

[47] Fix | Delete

entries in existing menus. Some menus are not present on some windows; such

[48] Fix | Delete

entry definitions are then ignored, but key bindings are still applied. (This

[49] Fix | Delete

should probably be refined in the future.)

[50] Fix | Delete

[51] Fix | Delete

Extensions are not required to define menu entries for all the events they

[52] Fix | Delete

implement. (They are also not required to create keybindings, but in that

[53] Fix | Delete

case there must be empty bindings in cofig-extensions.def)

[54] Fix | Delete

[55] Fix | Delete

Here is a complete example:

[56] Fix | Delete

[57] Fix | Delete

class ZoomHeight:

[58] Fix | Delete

[59] Fix | Delete

menudefs = [

[60] Fix | Delete

('edit', [

[61] Fix | Delete

None, # Separator

[62] Fix | Delete

('_Zoom Height', '<<zoom-height>>'),

[63] Fix | Delete

])

[64] Fix | Delete

]

[65] Fix | Delete

[66] Fix | Delete

def __init__(self, editwin):

[67] Fix | Delete

self.editwin = editwin

[68] Fix | Delete

[69] Fix | Delete

def zoom_height_event(self, event):

[70] Fix | Delete

"...Do what you want here..."

[71] Fix | Delete

[72] Fix | Delete

The final piece of the puzzle is the file "config-extensions.def", which is

[73] Fix | Delete

used to configure the loading of extensions and to establish key (or, more

[74] Fix | Delete

generally, event) bindings to the virtual events defined in the extensions.

[75] Fix | Delete

[76] Fix | Delete

See the comments at the top of config-extensions.def for information. It's

[77] Fix | Delete

currently necessary to manually modify that file to change IDLE's extension

[78] Fix | Delete

loading or extension key bindings.

[79] Fix | Delete

[80] Fix | Delete

For further information on binding refer to the Tkinter Resources web page at

[81] Fix | Delete

python.org and to the Tk Command "bind" man page.

[82] Fix | Delete

[83] Fix | Delete