X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=doc%2Fconf-bindings.tex;fp=doc%2Fconf-bindings.tex;h=0000000000000000000000000000000000000000;hb=a6561c9679cd701b0d50c3cfd44e4664f7df2b2f;hp=efec6a4a393fb462401fb02f790a39ffc4f12b14;hpb=cd09055902de482a1be019bf4b4efdae64c98d35;p=ion3.git diff --git a/doc/conf-bindings.tex b/doc/conf-bindings.tex deleted file mode 100644 index efec6a4..0000000 --- a/doc/conf-bindings.tex +++ /dev/null @@ -1,275 +0,0 @@ -\section{Keys and rodents} -\label{sec:bindings} - -In the stock configuration file setup, most key and mouse bindings are set -from the file \file{cfg\_ioncore.lua} while module-specific bindings -are set from the modules' main configuration files (\file{cfg\_modname.lua}). -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 -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 -listed in appendix \ref{app:fullhierarchy}, although not all define -a binding map. For example, the following skeleton would be used to -define new bindings for all frames: - -\begin{verbatim} -defbindings("WFrame", { - -- List of bindings to make goes here. -}) -\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 -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 -custom handlers would be more complicated. In addition one may want to -bind the same function to different key for different types of objects. -Indeed, the workspace and frame tab switching functions are the same both -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: -\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 \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. - - - -The following subsections describe how to construct elements of the -binding table. Note that \fnrefx{ioncore}{defbindings} adds -the the newly defined bindings to the previous bindings of the context, -overriding duplicates. To unbind an event, set the handler parameter -to \code{nil} for each of the functions to be described in the following -subsections. - -Also note that when multiple objects want to handle a binding, the -innermost (when the root window is considered the outermost) active object -in the parent--child hierarchy (see Figure \ref{fig:parentship}) of objects -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 following -special variables are available in this code. - -\begin{tabularx}{\linewidth}{lX} - \tabhead{Variable & Description} - \code{_} (underscore) & - Reference to the object on which the - binding was triggered. The object is of the same class as the the - context of the \fnrefx{ioncore}{defbindings} call - defining the binding. \\ - \code{_sub} & - Usually, the currently active \emph{managed object} of the - object referred to by \code{_}, but sometimes (e.g. mouse actions - on tabs of frames) something else relevant to the action triggering - the binding. \\ - \code{_chld} & - Object corresponding to the currently active child window of the - object referred to by \code{_}. This should seldom be needed. -\end{tabularx} - -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)" -\end{verbatim} - -\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 -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} - \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} - - -\subsection{Defining the bindings} -\label{sec:binddef} - -The descriptions of the individual bindings in the binding table argument -to \fnrefx{ioncore}{defbindings} should be constructed with the following -functions. - -Key presses: -\begin{itemize} - \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 \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, \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 -\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, -and the optional parameter \var{guard} its guard. These should normally -be strings as explained above. - -\subsection{Examples} - -For example, to just bind the key \key{Mod1+1} to switch to the first -workspace and \key{Mod1+Right} to the next workspace, you would make the -following call -\begin{verbatim} -defbindings("WScreen", { - kpress("Mod1+Right", "_:switch_next()"), - kpress("Mod1+1", "_:switch_nth(1)"), -}) -\end{verbatim} - -Note that \code{_:switch_nth(1)} is the same as calling -\fnref{WMPlex.switch_next}\code{(_, 1)} as \type{WScreen} inherits -\type{WMPlex} and this is where the function is actually defined. - -Similarly to the above example, to bind the key sequence \key{Mod1+k n} -switch to the next managed object within a frame, and \key{Mod1+k 1} to the -first, you would issue the following call: -\begin{verbatim} -defbindings("WFrame", { - submap("Mod1+K", { - kpress("Right", "_:switch_next()"), - kpress("1", "_:switch_nth(1)"), - }), -}) -\end{verbatim} - - -\subsection{Key specifications} - -As seen above, the functions that create key binding specifications require -a \var{keyspec} argument. This argument should be a string containing the -name of a key as listed in the X header file \file{keysymdef.h}% -\footnote{This file can usually be found in the directory -\file{/usr/X11R6/include/X11/}.} without the \code{XK_} prefix. -\index{keysymdef.h@\file{keysymdef.h}} -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 -followed by a plus sign (\code{+}) as a prefix. X defines the following -modifiers: - -\key{Shift}, \key{Control}, \key{Mod1} to \key{Mod5}, -\key{AnyModifier} and \key{Lock}. -\index{Shift@\key{Shift}} -\index{Control@\key{Control}} -\index{ModN@\key{ModN}} -\index{AnyModifier@\key{AnyModifier}} -\index{Lock@\key{Lock}} - -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 -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. - -Ion defaults to \key{AnyModifier} in submaps. This can sometimes lead to -unwanted effects when the same key is used with and without explicitly -specified modifiers in nested regions. For this reason, Ion recognises -\key{NoModifier} as a special modifier that can be used to reset this -default. - -Ion ignores the \key{Lock} modifier and any \key{ModN} ($N=1{\ldots} 5$) -bound to \key{NumLock}\index{NumLock@\key{NumLock}} or -\key{ScrollLock}\index{ScrollLock@\key{ScrollLock}} -by default because such\footnote{Completely useless keys that should be -gotten rid of in the author's opinion.} locking keys may otherwise -cause confusion. - - -\subsection{Button specifications} - -Button specifications are similar to key definitions but now -instead of specifying modifiers and a key, you specify modifiers -and one of the button names \key{Button1} to -\key{Button5}\index{Button-n@\key{Button-n}}. Additionally the -specification may end with an optional area name following an @-sign. -Only frames currently support areas, and the supported values in this -case are -\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: - -\begin{verbatim} -defbindings("WFrame", { - mdrag("Button1@tab", "_:p_tabdrag()"), -}) -\end{verbatim} - - -\subsection{A further note on the default binding configuration} - -The default binding configuration contains references to the variables -\code{META} and \code{ALTMETA} instead of directly using the default -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 -changing the whole binding configuration. Quite a few people prefer -to use the Windows keys as modifiers because many applications already -use \key{Alt}. Nevertheless, \key{Mod1} is the default as a key bound -to it is available virtually everywhere. -