diff options
Diffstat (limited to 'Lib/idlelib/extend.txt')
| -rw-r--r-- | Lib/idlelib/extend.txt | 111 |
1 files changed, 37 insertions, 74 deletions
diff --git a/Lib/idlelib/extend.txt b/Lib/idlelib/extend.txt index a1756f0..efb0fc7 100644 --- a/Lib/idlelib/extend.txt +++ b/Lib/idlelib/extend.txt @@ -1,4 +1,5 @@ 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 @@ -7,10 +8,10 @@ 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. +the file config-extensions.def. 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 +actions that are invoked by event 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. @@ -26,41 +27,32 @@ variables: (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.) +The extension class must not directly bind Window Manager (e.g. X) events. +Rather, it must define one or more virtual events, e.g. <<zoom-height>>, and +corresponding methods, e.g. zoom_height_event(). The virtual events will be +bound to the corresponding methods, and Window Manager events can then be bound +to the virtual events. (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.) + +An extension can define menu entries. This is done with a class or instance +variable named menudefs; it should be a list of pairs, 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 key bindings are still applied. (This +should probably be refined in the future.) + +Extensions are not required to define menu entries for all the events they +implement. (XXX KBK 15Jul03: But it appears they must have keybindings for each +virtual event?) Here is a complete example example: @@ -73,48 +65,19 @@ class ZoomHeight: ]) ] - 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). +The final piece of the puzzle is the file "config-extensions.def", which is +used to to configure the loading of extensions and to establish key (or, more +generally, event) bindings to the virtual events defined in the extensions. -Extensions are not required to define menu entries for all events they -implement. +See the comments at the top of config-extensions.def for information. It's +currently necessary to manually modify that file to change IDLE's extension +loading or extension key bindings. -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. +For further information on binding refer to the Tkinter Resources web page at +python.org and to the Tk Command "bind" man page. |