conf-menus.tex

   1 \section{Menus}
   2 \label{sec:menus}
   3
   4 \subsection{Defining menus}
   5
   6 \index{menus}
   7 \index{defmenu@\code{defmenu}}
   8 \index{menuentry@\code{menuentry}}
   9 \index{submenu@\code{submenu}}
  10 In the stock configuration file setup, menus are defined in the file
  11 \file{cfg\_menus.lua} as previously mentioned. The \file{mod\_menu} module
  12 must be loaded for one to be able to define menus, and this is done with
  13 the function \fnrefx{mod_menu}{defmenu} provided by it.
  14
  15 Here's an example of the definition of a rather simple menu with a submenu:
  16
  17 \begin{verbatim}
  18 defmenu("exitmenu", {
  19     menuentry("Restart", "ioncore.restart()"),
  20     menuentry("Exit", "ioncore.shutdown()"),
  21 })
  22
  23 defmenu("mainmenu", {
  24     menuentry("Lock screen", "ioncore.exec('xlock')"),
  25     menuentry("Help", "mod_query.query_man(_)"),
  26     submenu("Exit", "exitmenu"),
  27 })
  28 \end{verbatim}
  29
  30
  31 The \fnrefx{mod_menu}{menuentry} function is used to create an entry in the
  32 menu with a title and an entry handler to be called when the menu entry
  33 is activated. The parameters to the handler are similar to those of binding
  34 handlers, and usually the same as those of the binding that opened the menu.
  35
  36 The \fnrefx{mod_menu}{submenu} function is used to insert a submenu at that
  37 point in the menu. (One could as well just pass a table with the menu
  38 entries, but it is not encouraged.)
  39
  40 \subsection{Special menus}
  41
  42 The menu module predefines the following special menus. These can be used
  43 just like the menus defined as above.
  44
  45 \begin{tabularx}{\linewidth}{lX}
  46     \tabhead{Menu name & Description}
  47     \code{windowlist} &
  48     List of all client windows. Activating an entry jumps to that window. \\
  49     \code{workspacelist} &
  50     List of all workspaces. Activating an entry jumps to that workspaces. \\
  51     \code{focuslist} &
  52     List of client windows with recent activity in them, followed by
  53     previously focused client windows. \\
  54     \code{focuslist_} &
  55     List of previously focused client windows. \\
  56     \code{stylemenu} &
  57     List of available \file{look\_*.lua} style files. Activating an entry
  58     loads that style and ask to save the selection. \\
  59     \code{ctxmenu} &
  60     Context menu for given object. \\
  61 \end{tabularx}
  62
  63
  64 \subsection{Defining context menus}
  65
  66 The ''ctxmenu'' is a special menu that is assembled from a defined context
  67 menu for the object for which the menu was opened for, but also includes
  68 the context menus for the manager objects as submenus.
  69
  70 Context menus for a given region class are defined with the
  71 \fnrefx{mod_menu}{defctxmenu} function. This is other ways similar to
  72 \fnrefx{mod_menu}{defmenu}, but the first argument instead being the name
  73 of the menu, the name of the region class to define context menu for.
  74 For example, here's part of the stock \type{WFrame} context menu
  75 definition:
  76
  77 \begin{verbatim}
  78 defctxmenu("WFrame", {
  79     menuentry("Close", "WRegion.rqclose_propagate(_, _sub)"),
  80     menuentry("Kill",  "WClientWin.kill(_sub)", "_sub:WClientWin"),
  81 })
  82 \end{verbatim}
  83
  84 Some of the same ''modes'' as were available for some bindings
  85 may also be used: \code{WFrame.tiled}, \code{WFrame.floating},
  86 and \code{WFrame.transient}.
  87
  88
  89 \subsection{Displaying menus}
  90 \label{sec:menudisp}
  91
  92 The following functions may be used to display menus from binding
  93 handlers (and elsewhere):
  94
  95 \begin{tabularx}{\linewidth}{lX}
  96     \tabhead{Function & Description}
  97     \fnref{mod_menu.menu} &
  98       Keyboard (or mouse) operated menus that open in the bottom-left corner
  99       of a screen or frame. \\
 100     \fnref{mod_menu.bigmenu} &
 101       Same as previous, but uses another graphical style. \\
 102     \fnref{mod_menu.pmenu} &
 103       Mouse-operated drop-down menus. This function can only be called from a
 104       mouse press or drag handler. \\
 105     \fnref{mod_menu.grabmenu} &
 106       A special version of \fnref{mod_menu.menu} that grabs the keyboard
 107       and is scrolled with a given key until all modifiers have been released,
 108       after which the selected entry is activated. This function is meant to
 109       be used for implementing, for example, Win***s-style \key{Alt-Tab}
 110       handling.\footnote{See the \file{wcirculate.lua} script in the Ion
 111         scripts repository \url{http://iki.fi/tuomov/repos/ion-scripts-3/}.} \\
 112 \end{tabularx}
 113
 114 The \fnrefx{mod_menu}{grabmenu} function takes the extra key parameter, but
 115 aside from that each of these functions takes three arguments, which when
 116 called from a binding handler, should be the parameters to the handler, and
 117 the name of the menu. For example, the following snippet of of code binds
 118 the both ways to open a context menu for a frame:
 119
 120 \begin{verbatim}
 121 defbindings("WFrame", {
 122     kpress(MOD1.."M", "mod_menu.menu(_, _sub, 'ctxmenu')"),
 123     mpress("Button3", "mod_menu.pmenu(_, _sub, 'ctxmenu')"),
 124 })
 125 \end{verbatim}