diff options
Diffstat (limited to 'Tools/idle/extend.txt')
-rw-r--r-- | Tools/idle/extend.txt | 120 |
1 files changed, 0 insertions, 120 deletions
diff --git a/Tools/idle/extend.txt b/Tools/idle/extend.txt deleted file mode 100644 index a1756f0..0000000 --- a/Tools/idle/extend.txt +++ /dev/null @@ -1,120 +0,0 @@ -Writing an IDLE extension - -An IDLE extension can define new key bindings and menu entries for IDLE -edit windows. There is a simple mechanism to load extensions when IDLE -starts up and to attach them to each edit window. (It is also possible -to make other changes to IDLE, but this must be done by editing the IDLE -source code.) - -The list of extensions loaded at startup time is configured by editing -the file config.txt; see below for details. - -An IDLE extension is defined by a class. Methods of the class define -actions that are invoked by those bindings or menu entries. Class (or -instance) variables define the bindings and menu additions; these are -automatically applied by IDLE when the extension is linked to an edit -window. - -An IDLE extension class is instantiated with a single argument, -`editwin', an EditorWindow instance. The extension cannot assume much -about this argument, but it is guarateed to have the following instance -variables: - - text a Text instance (a widget) - io an IOBinding instance (more about this later) - flist the FileList instance (shared by all edit windows) - -(There are a few more, but they are rarely useful.) - -The extension class must not bind key events. Rather, it must define -one or more virtual events, e.g. <<zoom-height>>, and corresponding -methods, e.g. zoom_height_event(), and have one or more class (or instance) -variables that define mappings between virtual events and key sequences, -e.g. <Alt-F2>. When the extension is loaded, these key sequences will -be bound to the corresponding virtual events, and the virtual events -will be bound to the corresponding methods. (This indirection is done -so that the key bindings can easily be changed, and so that other -sources of virtual events can exist, such as menu entries.) - -The following class or instance variables are used to define key -bindings for virtual events: - - keydefs for all platforms - mac_keydefs for Macintosh - windows_keydefs for Windows - unix_keydefs for Unix (and other platforms) - -Each of these variables, if it exists, must be a dictionary whose -keys are virtual events, and whose values are lists of key sequences. - -An extension can define menu entries in a similar fashion. This is done -with a class or instance variable named menudefs; it should be a list of -pair, where each pair is a menu name (lowercase) and a list of menu -entries. Each menu entry is either None (to insert a separator entry) or -a pair of strings (menu_label, virtual_event). Here, menu_label is the -label of the menu entry, and virtual_event is the virtual event to be -generated when the entry is selected. An underscore in the menu label -is removed; the character following the underscore is displayed -underlined, to indicate the shortcut character (for Windows). - -At the moment, extensions cannot define whole new menus; they must -define entries in existing menus. Some menus are not present on some -windows; such entry definitions are then ignored, but the key bindings -are still applied. (This should probably be refined in the future.) - -Here is a complete example example: - -class ZoomHeight: - - menudefs = [ - ('edit', [ - None, # Separator - ('_Zoom Height', '<<zoom-height>>'), - ]) - ] - - windows_keydefs = { - '<<zoom-height>>': ['<Alt-F2>'], - } - unix_keydefs = { - '<<zoom-height>>': ['<Control-z><Control-z>'], - } - - def __init__(self, editwin): - self.editwin = editwin - - def zoom_height_event(self, event): - "...Do what you want here..." - -The final piece of the puzzle is the file "config.txt", which is used -to to configure the loading of extensions. For each extension, -you must include a section in config.txt (or in any of the other -configuration files that are consulted at startup: config-unix.txt, -config-win.txt, or ~/.idle). A section is headed by the module name -in square brackets, e.g. - - [ZoomHeight] - -The section may be empty, or it may define configuration options for -the extension. (See ParenMatch.py for an example.) A special option -is 'enable': including - - enable = 0 - -in a section disables that extension. More than one configuration -file may specify options for the same extension, so a user may disable -an extension that is loaded by default, or enable an extension that is -disabled by default. - -Extensions can define key bindings and menu entries that reference -events they don't implement (including standard events); however this is -not recommended (and may be forbidden in the future). - -Extensions are not required to define menu entries for all events they -implement. - -Note: in order to change key bindings, you must currently edit the file -keydefs. It contains two dictionaries named and formatted like the -keydefs dictionaries described above, one for the Unix bindings and one -for the Windows bindings. In the future, a better mechanism will be -provided. |