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{stylemenu} &
  52     List of available \file{look\_*.lua} style files. Activating an entry
  53     loads that style and ask to save the selection. \\
  54     \code{ctxmenu} &
  55     Context menu for given object. \\
  56 \end{tabularx}
  57
  58
  59 \subsection{Defining context menus}
  60
  61 The ''ctxmenu'' is a special menu that is assembled from a defined context
  62 menu for the object for which the menu was opened for, but also includes
  63 the context menus for the manager objects as submenus.
  64
  65 Context menus for a given region class are defined with the
  66 \fnrefx{mod_menu}{defctxmenu} function. This is other ways similar to
  67 \fnrefx{mod_menu}{defmenu}, but the first argument instead being the name
  68 of the menu, the name of the region class to define context menu for.
  69 For example, here's part of the stock \type{WFrame} context menu
  70 definition:
  71
  72 \begin{verbatim}
  73 defctxmenu("WFrame", {
  74     menuentry("Close", "WRegion.rqclose_propagate(_, _sub)"),
  75     menuentry("Kill",  "WClientWin.kill(_sub)", "_sub:WClientWin"),
  76 })
  77 \end{verbatim}
  78
  79 Some of the same ''modes'' as were available for some bindings
  80 may also be used: \code{WFrame.tiled}, \code{WFrame.floating},
  81 and \code{WFrame.transient}.
  82
  83
  84 \subsection{Displaying menus}
  85 \label{sec:menudisp}
  86
  87 The following functions may be used to display menus from binding
  88 handlers (and elsewhere):
  89
  90 \begin{tabularx}{\linewidth}{lX}
  91     \tabhead{Function & Description}
  92     \fnref{mod_menu.menu} &
  93       Keyboard (or mouse) operated menus that open in the bottom-left corner
  94       of a screen or frame. \\
  95     \fnref{mod_menu.bigmenu} &
  96       Same as previous, but uses another graphical style. \\
  97     \fnref{mod_menu.pmenu} &
  98       Mouse-operated drop-down menus. This function can only be called from a
  99       mouse press or drag handler. \\
 100     \fnref{mod_menu.grabmenu} &
 101       A special version of \fnref{mod_menu.menu} that grabs the keyboard
 102       and is scrolled with a given key until all modifiers have been released,
 103       after which the selected entry is activated. This function is meant to
 104       be used for implementing, for example, Win***s-style \key{Alt-Tab}
 105       handling.\footnote{See the \file{wcirculate.lua} script in the Ion
 106         scripts repository \url{http://iki.fi/tuomov/repos/ion-scripts-3/}.} \\
 107 \end{tabularx}
 108
 109 The \fnrefx{mod_menu}{grabmenu} function takes the extra key parameter, but
 110 aside from that each of these functions takes three arguments, which when
 111 called from a binding handler, should be the parameters to the handler, and
 112 the name of the menu. For example, the following snippet of of code binds
 113 the both ways to open a context menu for a frame:
 114
 115 \begin{verbatim}
 116 defbindings("WFrame", {
 117     kpress(MOD1.."M", "mod_menu.menu(_, _sub, 'ctxmenu')"),
 118     mpress("Button3", "mod_menu.pmenu(_, _sub, 'ctxmenu')"),
 119 })
 120 \end{verbatim}