Bindings, and Customizeability

Back to Dred Help Index

Dred's built-in components and extensions are configured from "bindings" files that take a standard form. The most important function of configuration (for most users) is the association of keystrokes with editing actions.

Initial Bindings

When the program starts, then if no bindings file is specified on its command line with the switch

        --bindings=bindings-url

it attempts to read a bindings file from the first of the following url-specified files that exists:

        url                                     (if the environment variable DREDBINDINGS is set to url)
        url                                     (if the Java virtual machine has its DREDBINDINGS property set to url)
        file:$(HOME)/DRED/dred.bindings         ($(HOME) stands for the user's desktop in Windows)
        file:$(HOME)/.dred/dred.bindings        ($(HOME) stands for the user's desktop in Windows)

If it cannot do so, then it issues a warning on the console and uses its inbuilt "fallback" bindings. Many people will find that these bindings do not suit them.

The Fallback Bindings

editor minitext action doComplete    TAB                  # complete the filename in the Argument minitext
editor action   doAbout              #keystroke#          # Show version details of the currently-running Dred
editor action   doCWD                #keystroke#          # Change the directory of this session to the directory named in the ... field
editor action   doChooseCWD          #keystroke#          # Browse for a directory then change directory to it
editor action   doClearArgument      ctrl  INSERT         # Clear the .... field and send focus there
editor action   doClearFind          ctrl alt  INSERT     # Clear the find field and send focus there
editor action   doClearRepl          shift ctrl alt  INSERT # Clear the repl field and send focus there
editor action   doCommands           #keystroke#          # Insert (and select) the skeleton of a bindings file (showing current bindings) into the current document.
editor action   doComplete           TAB                  # Try to complete the filename in the .... field
editor action   doCurrentBindings    #keystroke#          # Show the current bindings and abbreviations in a window
editor action   doEdit               ctrl  E              # Edit the file named in the ... field
editor action   doEditChoose         #keystroke#          # Browse for a file and start editing it
editor action   doFindDown           ctrl  F              # Find the next instance of the pattern in the Find field
editor action   doFindSelDown        ctrl alt  F          # Set the find field to the selection, then find its next instance
editor action   doFindSelUp          shift ctrl alt  F    # Set the find field to the selection, then find its previous instance
editor action   doFindUp             shift ctrl  F        # Find the previous instance of the pattern in the Find field
editor action   doGoToXY             ctrl  G              # Go to the row.col specified by the .... field
editor action   doGrow               #keystroke#          # window height*=3/2
editor action   doHelp               #keystroke#          # Browse Dred help using Dred's built-in browser
editor action   doIndent             ctrl  RIGHT          # Add a leading space to each line of the selection
editor action   doKillProcess        ctrl  K              # Kill any currently-running background process
editor action   doLogger             #keystroke#          # Start the HTTP logging interface at the port number specified in ....
editor action   doLowercase          #keystroke#          # Swap the current selection with its lowercased translation
editor action   doMatchDown          ctrl  OPEN_BRACKET   # Find next (balanced) bracket that matches the opening bracket at the cursor
editor action   doMatchUp            ctrl  CLOSE_BRACKET  # Find previous (balanced) bracket that matches the opening bracket at the cursor
editor action   doMax                #keystroke#          # maximize window height
editor action   doMozilla            #keystroke#          # Browse the help text (from Dred's built-in server) using mozilla.
editor action   doNewView            #keystroke#          # Open another view on the document being edited
editor action   doPrefix             ctrl alt  RIGHT      # Add the text in .... to the start of each line of the selection
editor action   doQuit               ctrl  Q              # Quit the current file-editing window. Offers a dialogue if the document being edited has channged since it was last saved.
editor action   doReplaceAll         #keystroke#          # Replace all instances of the Find pattern within the selection with the Repl text.
editor action   doReplaceDown        ctrl  R              # Replace the current instance of the find pattern with the replacement text
editor action   doReplaceUp          shift ctrl  R        # Replace the current instance of the find pattern with the replacement text
editor action   doSave               ctrl  S              # Save the document being edited if it has changed since it was last saved
editor action   doSaveAs             #keystroke#          # Save the document being edited in the file named by the .... field
editor action   doSaveAsChoose       #keystroke#          # Browse for a filename in which to save the document being edited
editor action   doSavePrefs          #keystroke#          # Save the current state of all preferences now
editor action   doShell              #keystroke#          # Pipe the current selection through the shell command given in the .... field
editor action   doShrink             #keystroke#          # window height*=2/3
editor action   doUnPrefix           ctrl alt  LEFT       # Remove the text in .... from the start of each line of the selection
editor action   doUndent             ctrl  LEFT           # Remove a leading space from each line of the selection
editor action   doUnicode            alt  U               # Insert Unicode character whose (hex) code is in ....
editor action   doUppercase          #keystroke#          # Swap the current selection with its uppercased translation
text action     doAbbrev             ESCAPE               # Find the longest abbreviation that matches text at the left of the cursor and insert the corresponding insertion text. This is undone by doSwapSel.
text action     doCopy               ctrl  C              # Set the system clipboard from the document selection
text action     doCut                ctrl  X              # Set the system clipboard from the document selection, and remove the document selection
text action     doDeleteLineLeft     ctrl  U              # Delete the line to the left of the cursor
text action     doDownMove           DOWN                 # Move cursor down (in the same column if possible)
text action     doEndMove            END                  # Move cursor to the start of the last line of the document
text action     doHomeMove           HOME                 # Move cursor to the start of the document
text action     doIndentNewline      ENTER                # Insert a newline and copy current indentation
text action     doInsertNewline      ctrl  ENTER          # Insert a newline without copying current indentation
text action     doInsertTab          TAB                  # Simulate the insertion of a tab character
                                                          # (Tabs never appear in Dred documents)
text action     doLeftDelete         BACK_SPACE           # Delete the character to the left of the cursor
text action     doLeftDelete         DELETE               # Delete the character to the left of the cursor
text action     doLeftMove           LEFT                 # Move cursor to the previous location in the document
text action     doPaste              ctrl  V              # Insert the system clipboard into the document at the cursor, and select it
text action     doRightMove          RIGHT                # Move cursor to the next location in the document
text action     doSelectLine         ctrl  L              # Select the line under the cursor (also triple-click)
text action     doSelectParagraph    ctrl  P              # Select the paragraph(s) that contain the selection or cursor
text action     doSelectWord         ctrl  W              # Select the word under the cursor (also double-click)
text action     doSwap2              alt  BACK_SPACE      # Swap the two characters preceding the cursor
text action     doSwap2              alt  DELETE          # Swap the two characters preceding the cursor
text action     doSwapCursorAndMark  ctrl  S              # Swap the cursor and the mark
text action     doSwapSel            shift ctrl  C        # Swap the system clipboard with the document selection
text action     doUpMove             UP                   # Move cursor up (in the same column if possible)
minitext action doBig                ctrl  ENTER          # to make a multiline-view minitext of this one-line-view minitext
minitext action doClear              ctrl  U              # Clear this text field
minitext action doTellBig            ENTER                # Tell the user how to make a new big window onto this text field

Specifying Bindings

Bindings are specified by bindings files, which are UTF8-encoded and contain a sequence of Binding descriptions together with some comments.

A comment is a line whose first non-blank character is #

A binding description is a sequence of binding fields separated by spaces and followed by an optional comment that starts with # and extends to the end of the line.

A binding field is a sequence of non-space characters. Within a binding field: \# stands for #, \s stands for space, \t stands for a tab character, \n stands for a newline character, and a sequence of the form \uXXXX (where XXXX are hexadecimal characters) stands for the character at unicode XXXX.

In general the first field of a binding indicates the name of the extension (or component) that is expected to interpret it, the second field of a binding indicates the type of interpretation, and subsequent fields are there to be interpreted.

The principal built-in component types are

Examples of Editor and Text Bindings

The fallback bindings shown above are in the form they might appear in a Bindings file. Here are a few other examples:

   text   abbrev forall           \u2200        meta shift A    # ∀   
   text   abbrev exists           \u2203        meta shift E    # ∃    
     
   text   key                     \u03B3        meta G          # (gamma) γ       
   text   key                     \u0393        meta shift G    # (Gamma) Γ        

   editor          action doFindDown            F9
   editor          action doFindUp              shift F9

Other Bindings

Include Bindings
The binding forms
        include  url
        include? url
call for the inclusion of the file denoted by the url. If there's no protocol part in the url, then the protocol is taken to be file:. The include? form fails quietly if the url is not accessible.
Style Sheet Bindings
The Tools/Styles menu entry brings up a style book composed of sheets that are specified by bindings that start style. Substantive entries specify actions that apply "styles" to the current selection -- mostly by embedding it in "brackets'' of some kind.

Here is a (commented and slightly sanitised) extract from the style sheet bindings I used myself.

style sheet XML                                             # start a new sheet, called XML
style transform untag (?s)^<[^>]+>(.*)</[^>]+>$ $1          # button "untag" extracts the body of an xml tag
style -                                                     # add a separator to the style sheet
style xml  block p                                          # button "p" embeds the selection in "p" tags -- block style
style xml  line  i                                          # button "i" embeds the selection in "i" tags -- line style
style line img   <image\salt="[IMG]"\ssrc="%SEL%">          # button "img" makes an image tag (line style) from the selection
style line link  <a\shref="[XXXX]">%SEL%</a>                # button "link" embed the selection in anchor tags
style form block ? <%ARG%>%SEL%</%ARG%>                     # add a style form named "?" to the sheet. Pressing ? generates a block-style tag 
style sheet Latex
style form  block \\begin \begin{%ARG%}%SEL%\end{%ARG%}     # add a block style form named "\begin"
style latex macro textbf                                    # button "textbf" embeds the selection in \textbf{...}
style latex env   verbatim                                  # button "verbatim" embeds the selection in \begin{verbatim}...\end{verbatim} -- block style
style form  array \begin{array}{%ARG%}%SEL%\end{array}      # add a line style form named "array"
style block foil  \documentclass{foil}\n\\usepackage{RCS}\n\RCS\s$I\u0064: $\n\\title{}\n\author{}\n\date{}\n%\n\begin{document}\n\maketitle%SEL%\end{document}
"Line style" means that the selection is embedded without further ado. "Block style" means that a heuristic is used to try to make the resulting material look pretty by inserting newlines and indenting in appropriate places. Experiment to see if you like it. A form has both a button and a minitext on it. You "fill in" the minitext with an argument, and then press the button. The transformed material can mention the content of the minitext (%ARG%) and the selection (%SEL%).
Extension Bindings
The binding
        extension path url
adds the given url to the search path for extensions, and the binding
        extension load classname
searches the extension search path for the given class, and loads it.

Examples are:

        extension path jar:file://home/sufrin/.dred/extensions.jar   # adds the given jar file to the path
        extension path file://home/sufrin/.dred/extensions.jar       # ditto
        extension path /home/sufrin/.dred/extensions.jar             # ditto
        extension path /home/sufrin/.dred/extensions/                # adds the given folder to the path

Further documentation of Bindings

Clicking on the Help/Show Bindings menu item provides documentation for the built-in actions. Clicking on the Help/Insert Bindings menu item inserts the prototype of a bindings file into the document currently being edited. This is intended to make it easy to construct an alternative bindings file. The prototype shows the existing bindings, and can be edited into the right form and saved in the right place.

Keystroke Specifications

Keystroke specifications take the form of zero or more optional modifiers followed by a key specification:
                 [ctrl][alt][meta][shift][altGraph] key specification

A key specification takes one of the forms given in the documentation for java.awt.event.KeyEvent, but without the VK_ prefix. If you don't want to bother looking these up, then check the Tools/Keystroke Tool checkbox. This puts up a keystroke tool -- if you type anything when the mouse cursor is over this tool, then a specification of the key you typed will be placed in the current document.

To specify a modified variant of a character that appears in the shift position on a keytop, you have to specify the shift with the character that appears in the unshifted position on the keytop. For example: alt LEFT_PARENTHESIS is an invalid keystroke specification, and the keystroke you get by pressing alt with ( has to be expressed as alt shift 9.

Beware that on some keyboards the alt and meta keys are indistinguishable, and that some X window managers pre-empt some keystroke combinations for their own purposes.

Bernard Sufrin
$Revision: 187 $
$Date: 2006-09-14 22:39:58 +0100 (Thu, 14 Sep 2006) $