.config/awesome/lain/wiki/Utilities.md

   1 Quake\r
   2 -----\r
   3 \r
   4 A Quake-like dropdown container for your favourite application.\r
   5 \r
   6 **Usage**\r
   7 \r
   8 Define it globally to have a single instance for all screens:\r
   9 \r
  10 ```lua\r
  11 local quake = lain.util.quake()\r
  12 ```\r
  13 \r
  14 or define it in `connect_for_each_screen` to have one instance for each screen:\r
  15 \r
  16 ```lua\r
  17 awful.screen.connect_for_each_screen(function(s)\r
  18     -- Quake application\r
  19     s.quake = lain.util.quake()\r
  20     -- [...]\r
  21 ```\r
  22 \r
  23 **Keybinding example**\r
  24 \r
  25 If using a global instance:\r
  26 ```lua\r
  27 awful.key({ modkey, }, "z", function () quake:toggle() end),\r
  28 ```\r
  29 \r
  30 If using a per-screen instance:\r
  31 ```lua\r
  32 awful.key({ modkey, }, "z", function () awful.screen.focused().quake:toggle() end),\r
  33 ```\r
  34 \r
  35 **Input table**\r
  36 \r
  37 Variable | Meaning | Type | Default\r
  38 --- | --- | --- | ---\r
  39 `app` | client to spawn | string | "xterm"\r
  40 `name` | client name | string | "QuakeDD"\r
  41 `argname` | how to specify client name | string | "-name %s"\r
  42 `extra` | extra `app` arguments | string | empty string\r
  43 `border` | border width | integer | 1\r
  44 `visible` | initially visible | boolean | false\r
  45 `followtag` | always spawn on currently focused screen | boolean | false\r
  46 `overlap` | Overlap the wibox or not | boolean | false\r
  47 `settings` | Additional settings to make on the client | function | `nil`\r
  48 `screen` | screen where to spawn the client | integer | `awful.screen.focused()`\r
  49 `height` | dropdown client height | float in [0,1] or exact pixels number | 0.25\r
  50 `width` | dropdown client width | float in [0,1] or exact pixels number | 1\r
  51 `vert` | vertical position | string, possible values: "top", "bottom", "center" | "top"\r
  52 `horiz` | horizontal position | string, possible values: "left", "right", "center" | "left"\r
  53 \r
  54 `height` and `width` express a fraction of the workspace.\r
  55 \r
  56 `settings` is a function which takes the client as input, and can be used to customize its properties. For instance:\r
  57 \r
  58 ```lua\r
  59 -- set the client sticky\r
  60 s.quake = lain.util.quake { settings = function(c) c.sticky = true end }\r
  61 ```\r
  62 \r
  63 Read [here](https://awesomewm.org/doc/api/classes/client.html#Object_properties) for the complete list of properties.\r
  64 \r
  65 **Notes**\r
  66 \r
  67 * [Does not work](https://github.com/lcpz/lain/issues/358) with `gnome-terminal`, `konsole`, or any other terminal which is strictly designed for a Desktop Environment. Just pick a better terminal, [there's plenty](https://wiki.archlinux.org/index.php/List_of_applications#Terminal_emulators).\r
  68 * Set `followtag = true` if [experiencing issues with multiple screens](https://github.com/lcpz/lain/issues/346).\r
  69 * If you have a `awful.client.setslave` rule for your application, ensure you use an exception for `QuakeDD` (or your defined `name`). Otherwise, you may run into problems with focus.\r
  70 * If you are using a VTE-based terminal like `termite`, be sure to set [`argname = "--name %s"`](https://github.com/lcpz/lain/issues/211).\r
  71 \r
  72 Separators\r
  73 ----------\r
  74 \r
  75 Adds Cairo separators.\r
  76 \r
  77 ```lua\r
  78 local separators = lain.util.separators\r
  79 ```\r
  80 \r
  81 A separator function `separators.separator` takes two color arguments, defined as strings. `"alpha"` argument is allowed. Example:\r
  82 \r
  83 ```lua\r
  84 arrl_dl = separators.arrow_left(beautiful.bg_focus, "alpha")\r
  85 arrl_ld = separators.arrow_left("alpha", beautiful.bg_focus)\r
  86 ```\r
  87 \r
  88 You can customize height and width by setting `separators_height` and `separators_width` in your `theme.lua`. Default values are 0 and 9, respectively.\r
  89 \r
  90 List of functions:\r
  91 \r
  92      +-- separators\r
  93      |\r
  94      |`-- arrow_right()    Draw a right arrow.\r
  95       `-- arrow_left()     Draw a left arrow.\r
  96 \r
  97 markup\r
  98 ------\r
  99 \r
 100 Mades markup easier.\r
 101 \r
 102 ```lua\r
 103 local markup = lain.util.markup\r
 104 ```\r
 105 \r
 106 List of functions:\r
 107 \r
 108      +-- markup\r
 109      |\r
 110      |`-- bold()        Set bold.\r
 111      |`-- italic()      Set italicized text.\r
 112      |`-- strike()      Set strikethrough text.\r
 113      |`-- underline()   Set underlined text.\r
 114      |`-- monospace()   Set monospaced text.\r
 115      |`-- big()         Set bigger text.\r
 116      |`-- small()       Set smaller text.\r
 117      |`-- font()        Set the font of the text.\r
 118      |`-- font()        Set the font of the text.\r
 119      |`-- color()       Set background and foreground color.\r
 120      |`-- fontfg()      Set font and foreground color.\r
 121      |`-- fontbg()      Set font and background color.\r
 122       `-- fontcolor()   Set font, plus background and foreground colors.\r
 123      |\r
 124      |`--+ bg\r
 125      |   |\r
 126      |    `-- color()   Set background color.\r
 127      |\r
 128       `--+ fg\r
 129          |\r
 130           `-- color()   Set foreground color.\r
 131 \r
 132 they all take one argument, which is the text to markup, except the following:\r
 133 \r
 134 ```lua\r
 135 markup.font(font, text)\r
 136 markup.color(fg, bg, text)\r
 137 markup.fontfg(font, fg, text)\r
 138 markup.fontbg(font, bg, text)\r
 139 markup.fontcolor(font, fg, bg, text)\r
 140 markup.fg.color(color, text)\r
 141 markup.bg.color(color, text)\r
 142 ```\r
 143 \r
 144 Dynamic tagging\r
 145 ---------------\r
 146 \r
 147 That is:\r
 148 \r
 149 - add a new tag;\r
 150 - rename current tag;\r
 151 - move current tag;\r
 152 - delete current tag.\r
 153 \r
 154 If you delete a tag, any rule set on it shall be broken, so be careful.\r
 155 \r
 156 Use it with key bindings like these:\r
 157 \r
 158 ```lua\r
 159 awful.key({ modkey, "Shift" }, "n", function () lain.util.add_tag(mylayout) end),\r
 160 awful.key({ modkey, "Shift" }, "r", function () lain.util.rename_tag() end),\r
 161 awful.key({ modkey, "Shift" }, "Left", function () lain.util.move_tag(1) end),   -- move to next tag\r
 162 awful.key({ modkey, "Shift" }, "Right", function () lain.util.move_tag(-1) end), -- move to previous tag\r
 163 awful.key({ modkey, "Shift" }, "d", function () lain.util.delete_tag() end),\r
 164 ```\r
 165 \r
 166 The argument in `lain.util.add_tag` represents the tag layout, and is optional: if not present, it will be defaulted to `awful.layout.suit.tile`.\r
 167 \r
 168 Useless gaps resize\r
 169 ---------------------\r
 170 \r
 171 Changes `beautiful.useless_gaps` on the fly.\r
 172 \r
 173 ```lua\r
 174 lain.util.useless_gap_resize(thatmuch, s, t)\r
 175 ```\r
 176 \r
 177 The argument `thatmuch` is the number of pixel to add to/substract from gaps (integer).\r
 178 \r
 179 The arguments `s` and `t` are the `awful.screen` and `awful.tag` in which you want to change the gap. They are optional.\r
 180 \r
 181 Following are example keybindings for changing client gaps on current screen and tag.\r
 182 \r
 183 Example 1:\r
 184 \r
 185 ```lua\r
 186 -- On the fly useless gaps change\r
 187 awful.key({ altkey, "Control" }, "+", function () lain.util.useless_gaps_resize(1) end),\r
 188 awful.key({ altkey, "Control" }, "-", function () lain.util.useless_gaps_resize(-1) end),\r
 189 ```\r
 190 \r
 191 where `altkey = Mod1`. Example 2:\r
 192 \r
 193 ```lua\r
 194 mywidget:buttons(awful.util.table.join (\r
 195         awful.button({}, 4, function() lain.util.useless_gaps_resize(-1) end),\r
 196         awful.button({}, 5, function() lain.util.useless_gaps_resize(1) end)\r
 197     end)\r
 198 ))\r
 199 ```\r
 200 \r
 201 so when hovering the mouse over `mywidget`, you can adjust useless gaps size by scrolling with the mouse wheel.\r
 202 \r
 203 tag\_view\_nonempty\r
 204 -------------------\r
 205 \r
 206 This function lets you jump to the next/previous non-empty tag.\r
 207 It takes two arguments:\r
 208 \r
 209 * `direction`: `1` for next non-empty tag, `-1` for previous.\r
 210 * `sc`: Screen which the taglist is in. Default is `mouse.screen` or `1`. This\r
 211   argument is optional.\r
 212 \r
 213 You can use it with key bindings like these:\r
 214 \r
 215 ```lua\r
 216 -- Non-empty tag browsing\r
 217 awful.key({ altkey }, "Left", function () lain.util.tag_view_nonempty(-1) end),\r
 218 awful.key({ altkey }, "Right", function () lain.util.tag_view_nonempty(1) end),\r
 219 ```\r
 220 \r
 221 where `altkey = "Mod1"`.\r
 222 \r
 223 magnify\_client\r
 224 ---------------\r
 225 \r
 226 Set a client to floating and resize it in the same way the "magnifier"\r
 227 layout does it. Place it on the "current" screen (derived from the mouse\r
 228 position). This allows you to magnify any client you wish, regardless of\r
 229 the currently used layout. Use it with a client keybinding like this:\r
 230 \r
 231 ```lua\r
 232 clientkeys = awful.util.table.join(\r
 233     -- [...]\r
 234     awful.key({ modkey, "Control" }, "m", lain.util.magnify_client),\r
 235     -- [...]\r
 236 )\r
 237 ```\r
 238 \r
 239 If you want to "de-magnify" it, just retype the keybinding.\r
 240 \r
 241 If you want magnified client to respond to `incmwfact`, read [here](https://github.com/lcpz/lain/issues/195).\r
 242 \r
 243 menu\_clients\_current\_tags\r
 244 ----------------------------\r
 245 \r
 246 Similar to `awful.menu.clients`, but this menu only shows the clients\r
 247 of currently visible tags. Use it with a key binding like this:\r
 248 \r
 249 ```lua\r
 250 awful.key({ "Mod1" }, "Tab", function()\r
 251     lain.util.menu_clients_current_tags({ width = 350 }, { keygrabber = true })\r
 252 end),\r
 253 ```\r
 254 \r
 255 menu\_iterator\r
 256 --------------\r
 257 \r
 258 A generic menu utility which enables iteration over lists of possible\r
 259 actions to execute. The perfect example is a menu for choosing what\r
 260 configuration to apply to X with `xrandr`, as suggested on the [Awesome wiki page](https://awesomewm.org/recipes/xrandr).\r
 261 \r
 262 <p align="center">\r
 263     <img src="https://user-images.githubusercontent.com/4147254/36317474-3027f8b6-130b-11e8-9b6b-9a2cf55ae841.gif"/>\r
 264     <br>An example Synergy menu, courtesy of <a href="https://github.com/sim590/dotfiles/blob/master/awesome/rc/xrandr.lua">sim590</a>\r
 265 </p>\r
 266 \r
 267 You can either manually create a menu by defining a table in this format:\r
 268 \r
 269 ```lua\r
 270 { { "choice description 1", callbackFuction1 }, { "choice description 2", callbackFunction2 }, ... }\r
 271 ```\r
 272 \r
 273 or use `lain.util.menu_iterator.menu`. Once you have your menu, use it with `lain.menu_iterator.iterate`.\r
 274 \r
 275 ### Input tables\r
 276 \r
 277 **lain.menu_iterator.iterate**\r
 278 \r
 279 | Argument  | Description | Type\r
 280 |---|---| ---\r
 281 | `menu`    | the menu to iterate on                                                           | table\r
 282 | `timeout` | time (in seconds) to wait on a choice before the choice is accepted              | integer (default: 4)\r
 283 | `icon`    | path to the icon to display in `naughty.notify` window                           | string\r
 284 \r
 285 **lain.menu_iterator.menu**\r
 286 \r
 287 | Argument  | Description | Type\r
 288 |---|---| ---\r
 289 `choices` | list of choices (e.g., `{ "choice1", "choice2", ... }`) | array of strings\r
 290 `name` | name of the program related to this menu | string\r
 291 `selected_cb` | callback to execute for each selected choice, it takes one choice (string) as argument; can be `nil` (no action to execute) | function\r
 292 `rejected_cb` | callback to execute for all rejected choices (the remaining choices, once one is selected), it takes one choice (string) as argument; can be `nil` (no action to execute) | function\r
 293 `extra_choices` | more choices to be added to the menu; unlike `choices`, these ones won't trigger `rejected_cb` | array of `{ choice, callback }` pairs, where `choice` is a string and `callback` is a function\r
 294 `combination` | how choices have to be combined in the menu; possible values are: "single" (default), the set of possible choices will simply be the input set ; "powerset", the set of possible choices will be the [power set](https://en.wikipedia.org/wiki/Power_set) of the input set | string\r
 295 \r
 296 ### Examples\r
 297 \r
 298 A simple example is:\r
 299 \r
 300 ```lua\r
 301 local mymenu_iterable = lain.util.menu_iterator.menu {\r
 302     choices     = {"My first choice", "My second choice"},\r
 303     name        = "My awesome program",\r
 304     selected_cb = function(choice)\r
 305         -- do something with selected choice\r
 306     end,\r
 307     rejected_cb = function(choice)\r
 308         -- do something with every rejected choice\r
 309     end\r
 310 }\r
 311 ```\r
 312 \r
 313 The variable `mymenu_iterable` is a menu compatible with the function `lain.util.menu_iterator.iterate`, which will iterate over it and displays notification with `naughty.notify` every time it is called. You can use it like this:\r
 314 \r
 315 ```lua\r
 316 local confirm_timeout = 5 -- time to wait before confirming the menu selection\r
 317 local my_notify_icon = "/path/to/icon" -- the icon to display in the notification\r
 318 lain.util.menu_iterator.iterate(mymenu_iterable, confirm_timeout, my_notify_icon)\r
 319 ```\r
 320 \r
 321 Once `confirm_timeout` has passed without anymore calls to `iterate`, the choice is made and the associated callbacks (both for selected and rejected choices) are spawned.\r
 322 \r
 323 A useful practice is to add a `Cancel` option as an extra choice for canceling a menu selection. Extending the above example:\r
 324 \r
 325 ```lua\r
 326 local mymenu_iterable = lain.util.menu_iterator.menu {\r
 327     choices     = {"My first choice", "My second choice"},\r
 328     name        = "My awesome program",\r
 329     selected_cb = function(choice)\r
 330         -- do something with selected choice\r
 331     end,\r
 332     rejected_cb = function(choice)\r
 333         -- do something with every rejected choice\r
 334     end\r
 335     -- nil means no action to do\r
 336     extra_choices = { {"Cancel"}, nil }\r
 337 }\r
 338 ```\r