Tagged current upstream version.

[ion3-doc.git] / conf-bindings.tex

diff --git a/conf-bindings.tex b/conf-bindings.tex
index 9afb2b88a3bafbf49cc1e78519c15da1751a3b46..efec6a4a393fb462401fb02f790a39ffc4f12b14 100644 (file)
--- a/conf-bindings.tex
+++ b/conf-bindings.tex
@@ -8,7 +8,7 @@ This, however, does not have to be so as long as the module has been
 loaded prior to defining any module-specific bindings.
 
 Bindings are defined by calling the function 
 loaded prior to defining any module-specific bindings.
 
 Bindings are defined by calling the function 

-\fnrefx{ioncore}{defbindings} with the ''context'' of the
+\fnrefx{ioncore}{defbindings} with the ``context'' of the

 bindings and the a table of new bindings to make. The context is simply
 string indicating one of the classes of regions (or modes such as
 \type{WMoveresMode}) introduced in section \ref{sec:objects}, and fully
 bindings and the a table of new bindings to make. The context is simply
 string indicating one of the classes of regions (or modes such as
 \type{WMoveresMode}) introduced in section \ref{sec:objects}, and fully


@@ -23,7 +23,7 @@ defbindings("WFrame", {
 \end{verbatim}
 
 There has been some confusion among users about the need to define the
 \end{verbatim}
 
 There has been some confusion among users about the need to define the

-''context'' for each binding, so let me try to explain this design
+``context'' for each binding, so let me try to explain this design

 decision here. The thing is that if there was a just a simple 'bind this 
 key to this action' method without knowledge of the context, some 
 limitations would have to be made on the available actions and writing 
 decision here. The thing is that if there was a just a simple 'bind this 
 key to this action' method without knowledge of the context, some 
 limitations would have to be made on the available actions and writing 


@@ -34,27 +34,27 @@ classes being based on \type{WMPlex}, and in the stock configuration the
 switch to $n$:th workspaces is bound to \key{Mod1+n} while the switch to 
 $n$:th tab is bound to the sequence \key{Mod1+k n}.
 
 switch to $n$:th workspaces is bound to \key{Mod1+n} while the switch to 
 $n$:th tab is bound to the sequence \key{Mod1+k n}.
 

-Currently known ''contexts'' include: 
-\code{WScreen},
-\code{WMPlex},
-\code{WMPlex.toplevel},
-\code{WFrame},
-\code{WFrame.toplevel},
-\code{WFrame.floating},
-\code{WFrame.tiled},
-\code{WFrame.transient},
-\code{WMoveresMode},
-\code{WGroup},
-\code{WGroupCW},
-\code{WGroupWS},
-\code{WClientWin},
-\code{WTiling}, and
-\code{WStatusBar}.
+Currently known contexts include: 
+\codestr{WScreen},
+\codestr{WMPlex},
+\codestr{WMPlex.toplevel},
+\codestr{WFrame},
+\codestr{WFrame.toplevel},
+\codestr{WFrame.floating},
+\codestr{WFrame.tiled},
+\codestr{WFrame.transient},
+\codestr{WMoveresMode},
+\codestr{WGroup},
+\codestr{WGroupCW},
+\codestr{WGroupWS},
+\codestr{WClientWin},
+\codestr{WTiling}, and
+\codestr{WStatusBar}.

 Most of these should be self-explanatory, corresponding to objects
 Most of these should be self-explanatory, corresponding to objects

-of class with the same name. The ones with \code{.toplevel} suffix
-refer to screens and ''toplevel''  frames, i.e. frames that are
-not used for transient windows. Likewise \code{.transient} refers
-to frames in transient mode, and \code{.tiled} and \code{.floating}
+of class with the same name. The ones with \codestr{.toplevel} suffix
+refer to screens and ``toplevel''  frames, i.e. frames that are
+not used for transient windows. Likewise \codestr{.transient} refers
+to frames in transient mode, and \codestr{.tiled} and \codestr{.floating}

 to frames in, respectively, tiled and floating modes. 
 
                                                         
 to frames in, respectively, tiled and floating modes. 
 
                                                         


@@ -75,9 +75,9 @@ gets to handle the action.
 \subsection{Binding handlers and special variables}
 
 Unlike in Ion2, in Ion3 binding handlers are not normally passed as
 \subsection{Binding handlers and special variables}
 
 Unlike in Ion2, in Ion3 binding handlers are not normally passed as

-''anonymous functions'', although this is still possible. The preferred
-method now is to pass the code of the handler as a string. Two special 
-variables are available in this code. These are
+``anonymous functions'', although this is still possible. The preferred
+method now is to pass the code of the handler as a string. Two following
+special variables are available in this code.

 
 \begin{tabularx}{\linewidth}{lX}
     \tabhead{Variable & Description}
 
 \begin{tabularx}{\linewidth}{lX}
     \tabhead{Variable & Description}


@@ -93,11 +93,12 @@ variables are available in this code. These are
       the binding. \\
     \code{_chld} &
       Object corresponding to the currently active child window of the
       the binding. \\
     \code{_chld} &
       Object corresponding to the currently active child window of the

-       object referred to by \code{_}.
+       object referred to by \code{_}. This should seldom be needed.

 \end{tabularx}
 
 \end{tabularx}
 

-For example, supposing '\code{_}' is a \type{WFrame}, the following
-handler should move the active window to the right, if possible:
+For example, supposing \code{_} (underscore) is a \type{WFrame}, the 
+following handler should move the active window to the right, if 
+possible:

 
 \begin{verbatim}
 "_:inc_index(_sub)"
 
 \begin{verbatim}
 "_:inc_index(_sub)"


@@ -106,14 +107,14 @@ handler should move the active window to the right, if possible:
 \subsection{Guards}
 
 To suppress error messages, each binding handler may also be accompanied
 \subsection{Guards}
 
 To suppress error messages, each binding handler may also be accompanied

-by a ''guard'' expression that blocks the handler from being called when
+by a ``guard'' expression that blocks the handler from being called when

 the guard condition is not met. Currently the following guard expressions
 are supported (for both \code{_sub} and \code{_chld}):
 
 \begin{tabularx}{\linewidth}{lX}
     \tabhead{Guard & Description}
 the guard condition is not met. Currently the following guard expressions
 are supported (for both \code{_sub} and \code{_chld}):
 
 \begin{tabularx}{\linewidth}{lX}
     \tabhead{Guard & Description}

-    \code{"_sub:non-nil"} & The \code{_sub} parameter must be set. \\
-    \code{"_sub:SomeClass"} & The \code{_sub} parameter must be member
+    \codestr{\_sub:non-nil} & The \code{_sub} parameter must be set. \\
+    \codestr{\_sub:SomeClass} & The \code{_sub} parameter must be member

       of class \type{SomeClass}. \\
 \end{tabularx}
 
       of class \type{SomeClass}. \\
 \end{tabularx}
 


@@ -127,27 +128,33 @@ functions.
 
 Key presses:
 \begin{itemize}
 
 Key presses:
 \begin{itemize}

-    \item \fnref{kpress}\code{(keyspec, handler [, guard])},
-    \item \fnref{kpress_wait}\code{(keyspec, handler [, guard])} and
-    \item \fnref{submap}\code{(keyspec, \{ ... more key bindings ... \})}.
+    \item \fnrefx{ioncore}{kpress}, and
+          \fnrefx{ioncore}{kpress_wait}\code{(keyspec, handler [, guard])}.
+    \item \fnrefx{ioncore}{submap}\code{(keyspec, \{ ... more key bindings ... \})}.
+    \item \fnrefx{ioncore}{submap_enter}, and
+          \fnrefx{ioncore}{submap_wait}\code{(handler [, guard])}.

 \end{itemize}
 Mouse actions:
 \begin{itemize}
 \end{itemize}
 Mouse actions:
 \begin{itemize}

-    \item \fnref{mclick}\code{(buttonspec, handler [, guard])},
-    \item \fnref{mdblclick}\code{(buttonspec, handler [, guard])}, 
-    \item \fnref{mpress}\code{(buttonspec, handler [, guard])} and
-    \item \fnref{mdrag}\code{(buttonspec, handler [, guard])}.
+    \item \fnrefx{ioncore}{mclick},
+          \fnrefx{ioncore}{mdblclick},
+          \fnrefx{ioncore}{mpress}, and
+          \fnrefx{ioncore}{mdrag}\code{(buttonspec, handler [, guard])}.

 \end{itemize}
 
 The actions that most of these functions correspond to should be clear
 \end{itemize}
 
 The actions that most of these functions correspond to should be clear

-and as explained in the reference, \fnref{kpress_wait} is simply
-\fnref{kpress} with a flag set instructing Ioncore wait for all
-modifiers to be released before processing any further actions.
+and as explained in the reference, \fnrefx{ioncore}{kpress_wait} is simply
+\fnrefx{ioncore}{kpress} with a flag set instructing Ioncore wait for
+all modifiers to be released before processing any further actions.

 This is to stop one from accidentally calling e.g.
 This is to stop one from accidentally calling e.g.

-\fnref{WRegion.rqclose} multiple times in a row. The \fnref{submap}
-function is used to define submaps or ''prefix maps''. The second
-argument to this function is table listing the key press actions
-(\fnref{kpress}) in the submap
+\fnref{WRegion.rqclose} multiple times in a row. The 
+\fnrefx{ioncore}{submap} function is used to define submaps or
+``prefix maps''. The second argument to this function is table listing
+the key press actions (\fnrefx{ioncore}{kpress}) in the submap. 
+The \fnrefx{ioncore}{submap_enter} handler is called when the submap
+is entered, in which this handler is defined. Likewise, the
+\fnrefx{ioncore}{submap_wait} handler is  called when all modifiers
+have been released while waiting for further key presses in the submap.

 
 The parameters \var{keyspec} and \var{buttonspec} are explained below
 in detail. The parameter \var{handler} is the handler for the binding,
 
 The parameters \var{keyspec} and \var{buttonspec} are explained below
 in detail. The parameter \var{handler} is the handler for the binding,


@@ -195,10 +202,10 @@ Most of the key names are quite intuitive while some are not. For example,
 the \key{Enter} key on the main part of the keyboard has the less common
 name \key{Return} while the one the numpad is called \key{KP\_Enter}.
 
 the \key{Enter} key on the main part of the keyboard has the less common
 name \key{Return} while the one the numpad is called \key{KP\_Enter}.
 

-The \var{keyspec} string may optionally have multiple ''modifier'' names
+The \var{keyspec} string may optionally have multiple ``modifier'' names

 followed by a plus sign (\code{+}) as a prefix. X defines the following
 modifiers:
 followed by a plus sign (\code{+}) as a prefix. X defines the following
 modifiers:

-\begin{quotation}
+

 \key{Shift}, \key{Control}, \key{Mod1} to \key{Mod5},
 \key{AnyModifier} and \key{Lock}.
 \index{Shift@\key{Shift}}
 \key{Shift}, \key{Control}, \key{Mod1} to \key{Mod5},
 \key{AnyModifier} and \key{Lock}.
 \index{Shift@\key{Shift}}


@@ -206,14 +213,13 @@ modifiers:
 \index{ModN@\key{ModN}}
 \index{AnyModifier@\key{AnyModifier}}
 \index{Lock@\key{Lock}}
 \index{ModN@\key{ModN}}
 \index{AnyModifier@\key{AnyModifier}}
 \index{Lock@\key{Lock}}

-\end{quotation}

 
 X allows binding all of these modifiers to almost any key and while this
 list of modifiers does not explicitly list keys such as 
 \key{Alt}\index{Alt@\key{Alt}} that are common on modern keyboards, such
 keys are bound to one of the \key{ModN}. On systems running XFree86
 \key{Alt} is usually \key{Mod1}. On Suns \key{Mod1} is the diamond key
 
 X allows binding all of these modifiers to almost any key and while this
 list of modifiers does not explicitly list keys such as 
 \key{Alt}\index{Alt@\key{Alt}} that are common on modern keyboards, such
 keys are bound to one of the \key{ModN}. On systems running XFree86
 \key{Alt} is usually \key{Mod1}. On Suns \key{Mod1} is the diamond key

-and \key{Alt} something else. One of the ''flying window'' keys on so
+and \key{Alt} something else. One of the ``flying window'' keys on so

 called Windows-keyboards is probably mapped to \key{Mod3} if you have
 such a key. Use the program \file{xmodmap}\index{xmodmap@\file{xmodmap}}
 to find out what exactly is bound where. 
 called Windows-keyboards is probably mapped to \key{Mod3} if you have
 such a key. Use the program \file{xmodmap}\index{xmodmap@\file{xmodmap}}
 to find out what exactly is bound where. 


@@ -241,8 +247,8 @@ and one of the button names \key{Button1} to
 specification may end with an optional area name following an @-sign.
 Only frames currently support areas, and the supported values in this
 case are
 specification may end with an optional area name following an @-sign.
 Only frames currently support areas, and the supported values in this
 case are

-\code{"border"}, \code{"tab"}, \code{"empty_tab"}, \code{"client"} and
-\code{nil} (for the whole frame).
+\codestr{border}, \codestr{tab}, \codestr{empty\_tab}, \codestr{client} 
+and \code{nil} (for the whole frame).

 
 For example, the following code binds dragging a tab with the first 
 button pressed to initiate tab drag\&drop handling:
 
 For example, the following code binds dragging a tab with the first 
 button pressed to initiate tab drag\&drop handling:


@@ -258,7 +264,7 @@ defbindings("WFrame", {
 
 The default binding configuration contains references to the variables
 \code{META} and \code{ALTMETA} instead of directly using the default
 
 The default binding configuration contains references to the variables
 \code{META} and \code{ALTMETA} instead of directly using the default

-values of \code{"Mod1+"} and \code{""} (nothing). As explained in
+values of \codestr{Mod1+} and \codestr{} (nothing). As explained in

 section \ref{sec:walkthrough}, the definitions of these variables
 appear in \file{cfg\_ion.lua}. This way you can easily change the the
 modifiers used by all bindings in the default configuration without 
 section \ref{sec:walkthrough}, the definitions of these variables
 appear in \file{cfg\_ion.lua}. This way you can easily change the the
 modifiers used by all bindings in the default configuration without