X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=doc%2Fconf-bindings.tex;h=efec6a4a393fb462401fb02f790a39ffc4f12b14;hb=ae4260bb64817c11f9a7140324cd3e3ba113e297;hp=9afb2b88a3bafbf49cc1e78519c15da1751a3b46;hpb=8366314611bf30a0f31d25bf5f5023186fa87692;p=ion3.git diff --git a/doc/conf-bindings.tex b/doc/conf-bindings.tex index 9afb2b8..efec6a4 100644 --- a/doc/conf-bindings.tex +++ b/doc/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 -\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 @@ -23,7 +23,7 @@ defbindings("WFrame", { \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 @@ -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}. -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 -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. @@ -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 -''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} @@ -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 - object referred to by \code{_}. + object referred to by \code{_}. This should seldom be needed. \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)" @@ -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 -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} - \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} @@ -127,27 +128,33 @@ functions. 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} - \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 -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. -\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, @@ -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 \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: -\begin{quotation} + \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}} -\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 -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. @@ -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 -\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: @@ -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 -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