lua_docs.md (9514B)
1 # Lua API Documentation 2 3 kiwmi is configured completely in Lua. 4 All types kiwmi offers are actually reference types, pointing to the actual internal types. 5 This means Lua's garbage collection has no effect on the lifetime of the object. 6 7 kiwmi offers the following classes to work with: 8 9 ## Globals 10 11 ### `FROM_KIWMIC` 12 13 `true` when invoked from kiwmic, `false` otherwise. 14 15 ## kiwmi_server 16 17 This is the type of the global `kiwmi` singleton, representing the compositor. 18 This is the entry point to the API. 19 20 ### Methods 21 22 #### kiwmi:active_output() 23 24 Returns the active `kiwmi_output`. 25 26 See `request_active_output`. 27 28 #### kiwmi:bg_color(color) 29 30 Sets the background color (shown behind all views) to `color` (in the format #rrggbb). 31 32 #### kiwmi:cursor() 33 34 Returns a reference to the cursor object. 35 36 #### kiwmi:event_loop_add_fd(fd, mode, callback) 37 38 By registering with the event loop, arrange for `callback` to be called 39 whenever there is activity on the file descriptor `fd`. The `mode` parameter 40 is one of `O_RDWR`, `O_RDONLY`, `O_WRONLY` as defined in luaposix 41 `posix.fcntl` module. 42 43 If `callback` returns false or nil, the handler will be unregistered 44 from the event loop and not called again. 45 46 #### kiwmi:focused_view() 47 48 Returns the currently focused view. 49 50 #### kiwmi:output_at(lx, ly) 51 52 Returns the output at a specified position 53 54 #### kiwmi:on(event, callback) 55 56 Used to register event listeners. 57 58 #### kiwmi:quit() 59 60 Quit kiwmi. 61 62 #### kiwmi:schedule(delay, callback) 63 64 Call `callback` after `delay` ms. 65 Callback get passed itself, so that it can easily reregister itself. 66 67 #### kiwmi:set_verbosity(level) 68 69 Sets verbosity of kiwmi to the level specified with a number (see `kiwmi:verbosity()`). 70 71 #### kiwmi:spawn(command) 72 73 Spawn a new process. 74 `command` is passed to `/bin/sh`. 75 76 #### kiwmi:stop_interactive() 77 78 Stops an interactive move or resize. 79 80 #### kiwmi:unfocus() 81 82 Unfocus the currently focused view. 83 84 #### kiwmi:verbosity() 85 86 Returns the numerical verbosity level of kiwmi (value of one of `wlr_log_importance`, silent = 0, error = 1, info = 2, debug = 3). 87 88 #### kiwmi:view_at(lx, ly) 89 90 Get the view at a specified position. 91 92 ### Events 93 94 #### keyboard 95 96 A new keyboard got attached. 97 Callback receives a reference to the keyboard. 98 99 #### request_active_output 100 101 Called when the active output needs to be requested (for example because a layer-shell surface needs to be positioned). 102 Callback receives nothing and optionally returns a kiwmi_output. 103 104 If this isn't set or returns `nil`, the compositor defaults to the output the focused view is on, and if there is no view, the output the mouse is on. 105 106 #### output 107 108 A new output got attached. 109 Callback receives a reference to the output. 110 111 #### view 112 113 A new view got created (actually mapped). 114 Callback receives a reference to the view. 115 116 ## kiwmi_cursor 117 118 A reference to the cursor object. 119 120 ### Methods 121 122 #### cursor:output_at_pos() 123 124 Returns the output at the cursor position or `nil` if there is none. 125 126 #### cursor:on(event, callback) 127 128 Used to register event listeners. 129 130 #### cursor:pos() 131 132 Get the current position of the cursor. 133 Returns two parameters: `x` and `y`. 134 135 #### cursor:view_at_pos() 136 137 Returns the view at the cursor position, or `nil` if there is none. 138 139 ### Events 140 141 #### button_down 142 143 A mouse button got pressed. 144 Callback receives the ID of the button (i.e. LMB is 1, RMB is 2, ...). 145 146 The callback is supposed to return `true` if the event was handled. 147 The compositor will not forward it to the view under the cursor. 148 149 #### button_up 150 151 A mouse button got released. 152 Callback receives the ID of the button (i.e. LMB is 1, RMB is 2, ...). 153 154 The callback is supposed to return `true` if the event was handled. 155 The compositor will not forward it to the view under the cursor. 156 157 #### motion 158 159 The cursor got moved. 160 Callback receives a table containing `oldx`, `oldy`, `newx`, and `newy`. 161 162 #### scroll 163 164 Something was scrolled. 165 The callback receives a table containing `device` with the device name, `vertical` indicating whether it was a vertical or horizontal scroll, and `length` with the length of the vector (negative for left of up scrolls). 166 167 The callback is supposed to return `true` if the event was handled. 168 The compositor will not forward it to the view under the cursor. 169 170 ## kiwmi_keyboard 171 172 A handle to a keyboard. 173 174 ### Methods 175 176 #### keyboard:keymap(keymap) 177 178 The function takes a table as parameter. 179 The possible table indexes are "rules, model, layout, variant, options". 180 All the table parameters are optional and set to the system default if not set. 181 For the values to set have a look at the xkbcommon library. 182 <https://xkbcommon.org/doc/current/structxkb__rule__names.html> 183 184 #### keyboard:modifiers() 185 186 Returns a table with the state of all modifiers. 187 These are: `shift`, `caps`, `ctrl`, `alt`, `mod2`, `mod3`, `super`, and `mod5`. 188 189 #### keyboard:on(event, callback) 190 191 Used to register event listeners. 192 193 ### Events 194 195 #### destroy 196 197 The keyboard is getting destroyed. 198 Callback receives the keyboard. 199 200 #### key_down 201 202 A key got pressed. 203 204 Callback receives a table containing the `key`, `keycode`, `raw`, and the `keyboard`. 205 206 This event gets triggered twice, once with mods applied (i.e. `Shift+3` is `#`) and `raw` set to `false`, and then again with no mods applied and `raw` set to `true`. 207 208 The callback is supposed to return `true` if the event was handled. 209 The compositor will not forward it to the focused view in that case. 210 211 #### key_up 212 213 A key got released. 214 Callback receives a table containing the `key`, `keycode`, `raw`, and the `keyboard`. 215 216 This event gets triggered twice, once with mods applied (i.e. `Shift+3` is `#`) and `raw` set to `false`, and then again with no mods applied and `raw` set to `true`. 217 218 The callback is supposed to return `true` if the event was handled. 219 The compositor will not forward it to the focused view in that case. 220 221 ## kiwmi_lua_callback 222 223 A handle to a registered callback. 224 225 ## kiwmi_output 226 227 Represents an output (most often a display). 228 229 ### Methods 230 231 #### output:auto() 232 233 Tells the compositor to start automatically positioning the output (this is on per default). 234 235 #### output:move(lx, ly) 236 237 Moves the output to a specified position. 238 This is referring to the top-left corner. 239 240 #### output:name() 241 242 The name of the output. 243 244 #### output:on(event, callbacks) 245 246 Used to register event listeners. 247 248 #### output:pos() 249 250 Get the position of the output. 251 Returns two parameters: `x` and `y`. 252 253 #### output:redraw() 254 255 Force the output to redraw. Useful e.g. when you know the view `pre_render`/`post_render` callbacks are going to change. 256 257 #### output:size() 258 259 Get the size of the output. 260 Returns two parameters: `width` and `height`. 261 262 #### output:usable_area() 263 264 Returns a table containing the `x`, `y`, `width` and `height` of the output's usable area, relative to the output's top left corner. 265 266 ### Events 267 268 #### destroy 269 270 The output is getting destroyed. 271 Callback receives the output. 272 273 #### resize 274 275 The output is being resized. 276 Callback receives a table containing the `output`, the new `width`, and the new `height`. 277 278 #### usable_area_change 279 280 The usable area of this output has changed, e.g. because the output was resized or the bars around it changed. 281 Callback receives a table containing the `output` and the new `x`, `y`, `width` and `height`. 282 283 ## kiwmi_renderer 284 285 Represents a rendering context, to draw on the output. 286 287 ### Methods 288 289 #### renderer:draw_rect(color, x, y, w, h) 290 291 Draws a rect at the given position. 292 Color is a string in the form #rrggbb or #rrggbbaa. 293 294 ## kiwmi_view 295 296 Represents a view (a window in kiwmi terms). 297 298 ### Methods 299 300 #### view:app_id() 301 302 Returns the app id of the view. 303 This is comparable to the window class of X windows. 304 305 #### view:close() 306 307 Closes the view. 308 309 #### view:csd(client_draws) 310 311 Set whether the client is supposed to draw their own client decoration. 312 313 #### view:focus() 314 315 Focuses the view. 316 317 #### view:hidden() 318 319 Returns `true` if the view is hidden, `false` otherwise. 320 321 #### view:hide() 322 323 Hides the view. 324 325 #### view:id() 326 327 Returns an ID unique to the view. 328 329 #### view:imove() 330 331 Starts an interactive move. 332 333 #### view:iresize(edges) 334 335 Starts an interactive resize. 336 Takes a table containing the edges, that the resize is happening on. 337 338 #### view:move(lx, ly) 339 340 Moves the view to the specified position. 341 342 #### view:on(event, callback) 343 344 Used to register event listeners. 345 346 #### view:pid() 347 348 Returns the process ID of the client associated with the view. 349 350 #### view:pos() 351 352 Returns the position of the view (top-left corner). 353 354 #### view:resize(width, height) 355 356 Resizes the view. 357 358 #### view:show() 359 360 Unhides the view. 361 362 #### view:size() 363 364 Returns the size of the view. 365 366 **NOTE**: Used directly after `view:resize()`, this still returns the old size. 367 368 #### view:tiled(edges) 369 370 Takes a table containing all edges that are tiled, or a bool to indicate all 4 edges. 371 372 #### view:title() 373 374 Returns the title of the view. 375 376 ### Events 377 378 #### destroy 379 380 The view is being destroyed. 381 Callback receives the view. 382 383 #### post_render 384 385 The view finished being rendered. 386 Callback receives a table with the `view`, the `renderer` and the `output`. 387 388 This event occurs once per output the view might be drawn on. 389 390 #### pre_render 391 392 The view is about to be rendered. 393 Callback receives a table with the `view`, the `renderer` and the `output`. 394 395 This event occurs once per output the view might be drawn on. 396 397 #### request_move 398 399 The view wants to start an interactive move. 400 Callback receives the view. 401 402 #### request_resize 403 404 The view wants to start an interactive resize. 405 Callback receives a table containing the `view`, and `edges`, containing the edges.