Laylua

Lua interface for creating layer-shell windows

Laylua is a script interpreter enabling easy creation of layer-shell surfaces for wayland compositors supporting the zwlr-layer-shell protocol (e.g., those based on wlroots or qt-compositor).

This allows for the scripting backgrounds, menus, launchers, status bars, on-screen-display notifications, conky-like system monitors, etc. Examples for several of these uses can be found in the examples folder of this repository.

---

---

Usage

Laylua is intended to be used as a script interpreter. You may run laylua passing the name of a script file as the first argument, but more often you'd use the full path to laylua as a shebang for laylua-scripts such as those in the example directory.

Laylua sets up the wayland connection and provides the global laylua namespace with a few laylua-specific functions for initializing a layer window along with a wide range of cairo and pango functions for drawing. Other libraries can be added via luajit's FFI as needed.

The first laylua function to use is laylua.create which takes a table as its single argument. This table is cast to a c struct with the following defintion and associated enums:

struct laylua_win_config {
	int layer;
	int width, height;
	int anchor;
	int exclusive;
	int margin[4];
	int kbfocus;
};

enum { AnchorTop = 1, AnchorBottom = 2, AnchorLeft = 4, AnchorRight = 8 };
enum { LayerBackground = 0, LayerBottom = 1, LayerTop = 2, LayerOverlay = 3 };

You may leave any unneeded values unset, though it is your responsibility to satisfy the requirements of the layer-shell protocol definition: for example, width or height may be left out if and only if anchor is set appropriately. All unspecified values default to zero.

The create function retuns a window table / object on which you should (re)define a draw function and may also define button and key (if kbfocus is true / non-zero). Laylua provides the close and redraw functions on a window object / table which should not be redefined.

Laylua also provides a small number of utility functions as outlined below:

-- set a listener for events from fd
-- "handler" is a function that is passed the single user_data argument
-- "handler" should return 0 until the through with the event source
-- then return -1 to remove this event source from the main loop
laylua.event_add_fd(fd, handler, user_data)
-- as above, but the event is a timer expiring every "seconds" seconds
-- return -1 from handler to stop repeating timer events
laylua.event_add_timer(seconds, handler, user_data)
-- returns width, height for the layout as currently configured / filled
laylua.layout_get_size(layout)
-- returns width, height for the provided markup typeset with font_description
-- this is useful for determining the necessary size of a window prior to
-- it's creation predetermined text / markup
laylua.markup_get_size(font_description, markup)
-- forks and execs a shell running "command"
laylua.launch(command)

---

---

Examples

The following are examples included in the source respository. Some of these may be installed with laylua. While these examples are functional just as they are, most of them are intended to be copied to a user-modifiable location within PATH (e.g., ~/.local/bin/) and modified to customize settings.

launcher

A menu / launcher that replicates the behavior of the silo program and can emulate the behavior of dmenu and related launchers. The first code block at the start of the file includes settings intended to be customized.

msgbox

A simple on-screen-display message pop-up that expires after 5 seconds. All non-option arguments are strung together as text to be displayed. One optional argument can be provided as the first parameter starting with a "-" which defines a style for the popup. Default styles include -default -warn -err -err2 and -query.

tilua-bar

This is work-in-progress demonstration of a status bar to be used with a tiling window compositor: tilua (a soon to be released descendent of Tabby).

wonky

Wonky is intended to be a conky alternative for wayland with a variety of customizable "widgets" or system monitor displays that can be selected from. The current code is a trivial proof-of-concept showing just a "spedometer"-style RAM usage display.

User contributions would be gladly welcomed for expanding wonky's available monitor styles and data sources.

---

---

Planned Features / Changes

• post to AUR
• example: tilua_bar
  • button handling
  • test w/ tilua
• example: wonky
  • expand w/ other system monitors
• man page
• tag: 0.3

---

---