Bindings in the Text Binding Tag

The "Text" binding tag has 92 bindings in X11, 103 in OS X, 90 in Windows (Table 1). In addition, several "real events" are mapped to "virtual events" that are bound in the "Text" binding tag (Table 2).

Table 1: List of Bindings

Column Headings

  • Event is the event "sequence" specified in the bind command
  • Type is either "keyboard" or "mouse" (either may include keyboard modifiers); other types of event are not bound in the Text binding tag
  • The next six columns describe the effects of the binding, in eight categories. The columns are:
    • Navigation - a change in the position of the insert mark ("cursor"), other than to accommodate insertion or removal of text at the cursor
    • Text - a change in the text content of the widget
    • Selection - effect on the selection
    • Focus - changes in keyboard focus
    • Undo Stack - the insertion of separators, and changes to the stack itself (other than the default, i.e. recording the modifications to the widget)
    • Other - other effects are
      • scrolling
      • changes to the clipboard contents
      • 'break' commands
      • changes to selection and scroll view when the mouse pointer leaves the widget while Button 1 is pressed
      • initialization for subsequent events
  • The next two columns give further information on the effects of the binding:
    • Conditions - if the conditions stated in this column are not satisfied, the binding has no effect. (Information in this column that is not a condition is given in italics and brackets.)
    • Description - may be provided in an attempt to clarify the effects of the binding
  • Windowing System Specific - availability on different windowing systems - Tk may not provide certain bindings on all windowing systems, and even if it does, the windowing system may intercept the event and not pass it on to the application

Abbreviations used in Table 1:

  • "DSE" = "delete selection if it exists"
  • "DSEC" = "delete selection if it exists and if the insert mark is inside the selection or at its boundaries"
  • "blocks" = "the existence of this binding prevents the event from being handled by the binding for"
  • "ignore sel[ection]" means that the selection is not automatically cancelled or overwritten, but its contents may be changed if the alteration to the text lies within the selection boundaries; this is the default (i.e. applies if the table cell is empty)
  • "Std Kbd Navigation" (standard keyboard navigation) means navigation, combined with changing the selection if the event includes the Shift modifier, or cancelling the selection and inserting a separator on the undo stack if the event does not include the Shift modifier
  • "(a)", "(b)" and "x2 (c)", in the Undo Stack column, refer to the placement of autoseparators (note that if a separator is already present at the top of the undo stack another will not be inserted):
    • "(a)" is a single autoseparator that is placed in order to split keyboard-entered text into lines
    • "(b)" is a single autoseparator that is placed in order to record movement of the insert mark: the purpose is to separate changes made to the text in different places
    • "x2 (c)" is two autoseparators that are placed before and after the change to the text, in order to make that change atomic
  • In the Focus column, "take" means "take keyboard focus for the widget"; "move" means "keyboard focus is moved to another widget"
  • "NSM" = "not strict Motif", meaning that the variable ::tk_strictMotif is set to boolean false. (For convenience, all consequences of "NSM" are listed in the Conditions column, but information that is not a condition is given in italics and brackets.)
  • "preceded by" - does not necessarily mean "immediately preceded by", for example a series of events might be <Button-1>, <Double-Button-1>, <Double-Button-1>.
  • "EOL" = "End Of Line", really means "End of Logical Line", not end of display line

File: lib/tk8.5/text.tcl

Event Type Navigation Text Selection Focus Undo Stack Other Description Conditions Windowing System Specific
<Key> Keyboard   Y DSEC   if DSEC x2 (c)   DSEC, then insert the keypress character widget is not disabled and key is one that inserts text  
<Key-BackSpace> Keyboard   Y DSE       DSE, else delete prev char    
<Key-Delete> Keyboard   Y DSE       DSE, else delete next char    
<Key-Return> Keyboard   Y DSEC   if DSEC x2 (c), else (a)   DSEC, then insert newline, add autoseparator widget is not disabled  
<Key-Tab> Keyboard   Y DSEC take@ if DSEC x2 (c) break to prevent the binding tag "all" from changing the focus DSEC and insert tab, then take focus, then break widget is not disabled  
<Shift-Key-Tab> Keyboard           break to prevent the binding tag "all" from changing the focus no action except break; blocks <Key-Tab>

note that your "Shift Tab" key probably has a different name and is not covered by this binding but by <<PrevWindow>>: see Tables 5, 6 below.
   
<Control-Key-Tab> Keyboard       move     move focus to another widget   intercepted by KDE
<Control-Shift-Key-Tab> Keyboard       move     move focus to another widget   intercepted by KDE
<Control-Key> Keyboard             no action; blocks <Key>    
<Alt-Key> Keyboard             no action; blocks <Key>    
<Meta-Key> Keyboard             no action; blocks <Key>    
<Command-KeyPress> Keyboard             no action; blocks <Key>   Aqua only
<Key-Escape> Keyboard             no action; blocks <Key>    
<Key-KP_Enter> Keyboard             no action; blocks <Key>    
<Key-Insert> Keyboard   Y DSEC   if DSEC x2 (c)   DSEC, then insert selected text (use with <Control-1>) widget is not disabled and selection is not empty  
<Meta-Key-b> Keyboard Y   cancel sel   (b)   Std Kbd Navigation;
move to previous word-start
NSM  
<Meta-Key-d> Keyboard   Y ignore sel       delete to next word-start NSM  
<Meta-Key-f> Keyboard Y   cancel sel   (b)   Std Kbd Navigation;
move to next word-start
NSM  
<Meta-Key-less> Keyboard Y   cancel sel   (b)   Std Kbd Navigation;
move to top (1.0)
NSM  
<Meta-Key-greater> Keyboard Y   cancel sel   (b)   Std Kbd Navigation;
move to bottom (end-1c)
NSM  
<Meta-Key-BackSpace> Keyboard   Y ignore sel       delete to previous word-start NSM  
<Meta-Key-Delete> Keyboard   Y ignore sel       delete to previous word-start NSM  
<Control-Key-a> Keyboard Y   cancel sel   (b)   Std Kbd Navigation;
move to display line start
NSM  
<Control-Key-b> Keyboard Y   cancel sel   (b)   Std Kbd Navigation;
move -1 char
NSM  
<Control-Key-d> Keyboard   Y ignore sel       delete next char NSM  
<Control-Key-e> Keyboard Y   cancel sel   (b)   Std Kbd Navigation;
move to display line end
NSM  
<Control-Key-f> Keyboard Y   cancel sel   (b)   Std Kbd Navigation;
move +1 char
NSM  
<Control-Key-h> Keyboard   Y ignore sel       Backspace: delete previous char NSM, and insert mark not at 1.0  
<Control-Key-i> Keyboard   Y DSEC   if DSEC x2 (c)   DSEC, then insert tab char widget is not disabled  
<Control-Key-k> Keyboard   Y ignore sel       if at EOL, delete EOL; else delete to EOL NSM  
<Control-Key-n> Keyboard Y   cancel sel   (b)   Std Kbd Navigation;
move to next line
NSM  
<Control-Key-o> Keyboard   Y ignore sel       insert newline after insert mark NSM  
<Control-Key-p> Keyboard Y   cancel sel   (b)   Std Kbd Navigation;
move to previous line
NSM  
<Control-Key-t> Keyboard   Y ignore sel   x2 (c)   swap chars each side of insert cursor; move cursor +1 char NSM, and insert mark not at 1.0  
<Control-Key-backslash> Keyboard     cancel sel       Clear Selection    
<Control-Key-slash> Keyboard     change sel       Select All    
<Shift-Key-Select> Keyboard     change sel       select from anchor to insert    
<Control-Shift-Key-space> Keyboard     change sel       select from anchor to insert    
<Key-Select> Keyboard     ignore sel; set anchor       set selection anchor    
<Control-Key-space> Keyboard     ignore sel; set anchor       set selection anchor    
Navigation Events    
<Key-Left> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Key-Right> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Key-Up> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Key-Down> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Shift-Key-Left> Keyboard Y   change sel       Std Kbd Navigation    
<Shift-Key-Right> Keyboard Y   change sel       Std Kbd Navigation    
<Shift-Key-Up> Keyboard Y   change sel       Std Kbd Navigation    
<Shift-Key-Down> Keyboard Y   change sel       Std Kbd Navigation    
<Control-Key-Left> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Control-Key-Right> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Control-Key-Up> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Control-Key-Down> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Control-Shift-Key-Left> Keyboard Y   change sel       Std Kbd Navigation    
<Control-Shift-Key-Right> Keyboard Y   change sel       Std Kbd Navigation    
<Control-Shift-Key-Up> Keyboard Y   change sel       Std Kbd Navigation    
<Control-Shift-Key-Down> Keyboard Y   change sel       Std Kbd Navigation    
<Key-Home> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Key-End> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Control-Key-Home> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Control-Key-End> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Shift-Key-Home> Keyboard Y   change sel       Std Kbd Navigation    
<Shift-Key-End> Keyboard Y   change sel       Std Kbd Navigation    
<Control-Shift-Key-Home> Keyboard Y   change sel       Std Kbd Navigation    
<Control-Shift-Key-End> Keyboard Y   change sel       Std Kbd Navigation    
<Key-Next> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Key-Prior> Keyboard Y   cancel sel   (b)   Std Kbd Navigation    
<Shift-Key-Next> Keyboard Y   change sel       Std Kbd Navigation    
<Shift-Key-Prior> Keyboard Y   change sel       Std Kbd Navigation    
<Control-Key-Next> Keyboard           horizontal scrolling No navigation (insert cursor is unchanged)    
<Control-Key-Prior> Keyboard           horizontal scrolling No navigation (insert cursor is unchanged)    
<Option-Left> Keyboard Y   cancel sel   (b)   Std Kbd Navigation   Aqua Only (Option Key)
<Option-Right> Keyboard Y   cancel sel   (b)   Std Kbd Navigation   Aqua Only (Option Key)
<Option-Up> Keyboard Y   cancel sel   (b)   Std Kbd Navigation   Aqua Only (Option Key)
<Option-Down> Keyboard Y   cancel sel   (b)   Std Kbd Navigation   Aqua Only (Option Key)
<Shift-Option-Left> Keyboard Y   change sel       Std Kbd Navigation   Aqua Only (Option Key)
<Shift-Option-Right> Keyboard Y   change sel       Std Kbd Navigation   Aqua Only (Option Key)
<Shift-Option-Up> Keyboard Y   change sel       Std Kbd Navigation   Aqua Only (Option Key)
<Shift-Option-Down> Keyboard Y   change sel       Std Kbd Navigation   Aqua Only (Option Key)
<Control-v> Keyboard           vertical scrolling No navigation (insert cursor is unchanged)   Aqua Only
<<Undo>> Keyboard Y Y ignore sel   move item to redo stack   Undo changes back to previous separator undo activated for the widget  
<<Redo>> Keyboard Y Y ignore sel   move item from redo stack   Redo "undone" changes up to the next separator undo activated for the widget  
<<Cut>> Keyboard   Y cancel sel     change clipboard Move text from selection to clipboard selection not empty  
<<Copy>> Keyboard     ignore sel     change clipboard Copy text from selection to clipboard selection not empty  
<<Paste>> Keyboard   Y ignore sel (x11), DSE (other)   x2 (c)   Delete selection (except on x11), then copy text from clipboard to insert mark clipboard not empty  
<<Clear>> Keyboard   Y DSE       delete selected text   Aqua Only*
<<PasteSelection>> Mouse Y Y ignore sel take x2 (c)   Mapped to <ButtonRelease-2>.
If "strict Motif", or if the mouse pointer has not moved since <Button-2>, then navigate, paste selection, and if widget not disabled take focus.
If "not strict Motif" ("NSM"), and if the mouse has moved since <Button-2>, then nothing is done, and instead <B2-Motion> implements ScanDrag.
(N.B. precise action depends on NSM)  
<Button-1> Mouse Y   cancel sel take (b)   navigate; if widget not disabled or if platform is windows, take focus    
<ButtonRelease-1> Mouse           See "Description" See <B1-Leave>    
<B1-Motion> Mouse Y   change sel            
<Shift-Button-1> Mouse Y   change sel            
<Control-Button-1> Mouse Y   ignore sel            
<B1-Enter> Mouse           See "Description" See <B1-Leave>    
<B1-Leave> Mouse           See "Description" Start monitoring the mouse coordinates in order to update the selection range and scroll view of the widget. Do not stop until either <B1-Enter> or <ButtonRelease-1>.    
<Double-Button-1> Mouse Y   change sel       preceded by <Button-1>    
<Double-Shift-Button-1> Mouse     change sel       preceded by <Shift-Button-1>    
<Triple-Button-1> Mouse Y   change sel       preceded by <Button-1>, <Double-Button-1>    
<Triple-Shift-Button-1> Mouse     change sel       preceded by <Shift-Button-1>, <Double-Shift-Button-1>    
<Button-2> Mouse     ignore sel     See "Description" Initialization for <ButtonRelease-2> and possible <B2-Motion> events NSM  
<B2-Motion> Mouse     ignore sel     ScanDrag scrolling No navigation (insert cursor is unchanged) NSM  
<Button-4> Mouse           vertical scrolling   NSM X11 only - for Mouse Wheel
<Button-5> Mouse           vertical scrolling   NSM X11 only - for Mouse Wheel
<MouseWheel> Mouse           vertical scrolling     Not Aqua
<MouseWheel> Mouse           vertical scrolling     Aqua Only
<Option-MouseWheel> Mouse           vertical scrolling     Aqua Only (Option Key)
<Shift-MouseWheel> Mouse           horizontal scrolling     Aqua Only
<Shift-Option-MouseWheel> Mouse           horizontal scrolling     Aqua Only (Option Key)

* The virtual event <<Clear>> is provided on all windowing systems, but is used only on Aqua, where it is mapped to the <Clear> key.
@ Why does <Key-Tab> take focus? The widget must already have focus to receive the event, so why take it? ??Possibly some platforms respond to <Tab> by moving the focus before passing the event to the application/window that received it - if so, reclaiming the focus would be necessary here.

The widget prevents text insertion or deletion if its state is "disabled". However, the widget's bindings still fire, and so the bindings test the widget state, to provide control over operations other than text manipulation - usually changes to focus, and placement of autoseparators.

Table 2: Real and Virtual Events

Specifically, the Table shows mappings of <Real Events> to <<Virtual Events>> that are bound in the 'Text' binding tag.

The windowing system, [tk windowingsystem], governs the aspects of system-dependence discussed in Tables 1 and 2. System-dependence is also expressed by the values of the array variable ::tcl_platform, which is used by Text in other ways (to be discussed).

  • Windowing Systems - abbreviations used in Table 2:
    • "X" = x11 (Linux, UNIX, BSD)
    • "W" = win32 (Windows)
    • "M" = aqua (Mac OS X)
    • "-" = mapping is not included on this platform
  • Conditions - the event mapping is created iff the conditions stated in this column are satisfied
    • "NSM" = "not strict Motif", meaning that the variable $::tk_strictMotif is set to boolean false.

File: lib/tk8.5/tk.tcl

Real Event Type Virtual Event Windowing Systems Conditions
<ButtonRelease-2> Mouse <<PasteSelection>> XWM  
<Shift-Key-Delete> Keyboard <<Cut>> -W-  
<Shift-Key-Insert> Keyboard <<Paste>> -W-  
<Control-Key-Insert> Keyboard <<Copy>> -W-  
<Control-Key-c> Keyboard <<Copy>> XW-  
<Control-Key-v> Keyboard <<Paste>> XW-  
<Control-Key-w> Keyboard <<Cut>> X-- NSM
<Control-Key-x> Keyboard <<Cut>> XW-  
<Control-Key-y> Keyboard <<Redo>> -W-  
<Control-Key-y> Keyboard <<Paste>> X-- NSM
<Control-Key-z> Keyboard <<Undo>> XW-  
<Control-Key-Z> Keyboard <<Redo>> X--  
<Control-Key-underscore> Keyboard <<Undo>> X-- NSM
<Meta-Key-w> Keyboard <<Copy>> X-- NSM
<Command-Key-c> Keyboard <<Copy>> --M  
<Command-Key-v> Keyboard <<Paste>> --M  
<Command-Key-x> Keyboard <<Cut>> --M  
<Command-Key-y> Keyboard <<Redo>> --M  
<Command-Key-z> Keyboard <<Undo>> --M  
<Clear> Keyboard <<Clear>> --M  
<Key-F2> Keyboard <<Cut>> --M  
<Key-F3> Keyboard <<Copy>> --M  
<Key-F4> Keyboard <<Paste>> --M  
<Key-F16> Keyboard <<Copy>> X--  
<Key-F18> Keyboard <<Paste>> X--  
<Key-F20> Keyboard <<Cut>> X--  

Table 3: Keyboard Modifiers (PC)

A standard PC keyboard does not have Select or Clear keys; nor does it have Meta, Option or Command modifier keys. Its modifier keys are:

File: these names are not defined by a Tcl script file

Key Notes
Shift_L  
Shift_R  
Control_L  
Control_R  
Super_L (The left "Windows" key)
Super_R (The right "Windows" key)
Alt_L  
ISO_Level3_Shift (The "Right Alt" key)

The "Windows Menu" key <Menu> is not a modifier key.

Table 4: Actions that modify the text contents of the widget

File: lib/tk8.5/text.tcl - data extracted from Table 1.

Binding Mapped To
<Key>  
<Key-BackSpace>  
<Key-Delete>  
<Key-Return>  
<Key-Tab>  
<Key-Insert>  
<Meta-Key-d>  
<Meta-Key-BackSpace>  
<Meta-Key-Delete>  
<Control-Key-d>  
<Control-Key-h>  
<Control-Key-i>  
<Control-Key-k>  
<Control-Key-o>  
<Control-Key-t>  
<<Undo>> windowing-system-dependent: e.g. in X11 <Control-Key-z> (and others)
<<Redo>> windowing-system-dependent: e.g. in X11 <Control-Key-Z>
<<Cut>> windowing-system-dependent: e.g. in X11 <Control-Key-x> (and others)
<<Paste>> windowing-system-dependent: e.g. in X11 <Control-Key-v> (and others)
<<Clear>> windowing-system-dependent: Aqua only, <Clear> key
<<PasteSelection>> <ButtonRelease-2>

Bindings in the "all" Binding Tag

Table 5: List of Bindings

The "all" Binding Tag has 5 bindings (Table 5). Further real events are mapped to a "virtual event" that is bound in the "all" binding tag (Table 6).

Files: lib/tk8.5/focus.tcl, lib/tk8.5/menu.tcl, lib/tk8.5/tk.tcl

Event Type Description File
<<PrevWindow>> keyboard switching focus between widgets lib/tk8.5/tk.tcl
<Key-Tab> keyboard switching focus between widgets lib/tk8.5/tk.tcl
<Key-F10> keyboard keyboard navigation of menus lib/tk8.5/menu.tcl
<Alt-Key> keyboard keyboard navigation of menus lib/tk8.5/menu.tcl
<Enter> mouse focus follows mouse (optional, not the default) lib/tk8.5/focus.tcl

Table 6: Real and Virtual Events

Specifically, the Table shows mappings of <Real Events> to <<Virtual Events>> that are bound in the "all" binding tag.

File: lib/tk8.5/tk.tcl

Real Event Type Virtual Event Systems
<Key-ISO_Left_Tab> Keyboard <<PrevWindow>> X11 (XFree86 or X.org) on PC
<Key-hpBackTab> Keyboard <<PrevWindow>> some HP systems
<Shift-Key-Tab> Keyboard <<PrevWindow>> all

Some systems define a goofy (as in, not <Shift-Tab>) keysym that is returned when the user presses <Shift-Tab>. These keysyms are added to the <<PrevWindow>> event. For the first two, catch is used in case the keysym isn't recognized.