astrum is a widgeting system that depends on libcosmic it can run on any wayland compositor that supports the layer-shell protocol.

astrum is made in rust and is configured in lua i reccomend using the lua language server as that is what i will depend on for types and i reccomend getting familiar with the annotation syntax as that is what i will show in documentation

since this project is still a work in progress, you have to build it from source.

if you use nix you can add this as a nix flake input

inputs = {
    astrum.url = "github:vnuxa/astrum"
}

and somewhere in your package list add the following

    astrum.defaultPackage.${pkgs.system}

I also recommend having the lua language server installed in your text editor, since it contains astrum types and descriptions

Start by making ~/.config/astrum/config.lua

Astrum = require("astrum")
App = Astrum:application()
-- you can make windows with App:window()

return App

You will see nothing happening if you run astrum, mainly because its an empty config
You have to make a window in order for astrum to display something

Making windows

Windows are toplevel containers that hold widgets and signals (More on signals later).

App:window("window_name", {
 -- window model goes here
})

Windows have a mandatory view field, which defines what widgets to display
The view field gets ran after signals get processed.

App:window("window_name", {
    view = function()
         return Astrum.widgets:text("hello world!")
    end
})

This will display a window that has a text widget containing "hello world!"

Signals and states

Windows also have an optional signals field, which is a dictionary of signal names and logic that will be processed when the signal is fired

App:window("window_name", {
    view = function()
         return Astrum.widgets:button({
             child = Astrum.widgets:text("press me!")
             on_press = "button_pressed" -- the name of the signal
         })
    end,
    -- the syntax for signals is this
    -- signal_name = function(signal_data) end
    signals = {
        button_pressed = function() -- signal data is unnecessary since we do not send any yet
            print("hello world!")
        end
    }
})

This example will make a window, that has a button which when pressed will print hello world!

Signals are also the main way you change the state within astrum
And view logic is where you define widgets based on state

local state = {
    widget_text = "false"
}

App:window("window_name", {
    view = function()
         return Astrum.widgets:button({
             child = Astrum.widgets:text(state.widget_text)
             on_press = "button_pressed"
         })
    end,

    signals = {
        button_pressed = function()
            if state.widget_text == "false" then
                state.widget_text = "true"
            else
                state.widget_text = "false"
            end
        end
    }
})

This will make a window that has a button with text that toggles between false and true

Since astrum depends on libcosmic, styling is done within lua and not in another language (css for example)

Stylesheets

Although the styling is done within lua, there still are stylesheets

Astrum.style:add_style("style_name", {
-- style body goes here
})

Each widget has its own styling model, though if a widget has multiple styling states (for example buttons on_pressed and on_hovered) there is a default state as well, which overrides the base defaults, if not already specified

You can use stylesheets within widgets via the get_style function

Astrum.widgets:text({
    content = "hello world!",
    style = Astrum.style:get_style("style_name")
})

Subscriptions are the only way to update your state and view logic after an external event occurs.
Subscriptions will trigger every window's view and signal logic (might change in the future, depending on libcosmic)

To use a subscription, you must subscribe to a specific service.
Here is a hyprland workspace changed subscription example:

local state = {
    -- most services have types
    ---@type HyprlandWorkspaces
    workspaces = {}
}

App:window("workspace_example", {
    view = function()
        local row = Widgets:row({})

        for _, workspace in pairs(state.workspaces) do
            row:push(Widgets:text(tostring(workspace.id)))
        end

        return row
    end,
    -- Tells the application to subscribe to the `Hyprland` service
    subscriptions = {
        hyprland = {
            ---Specifies that whenever there is a workspace change, send the following signal that goes by the name of `on_workspace`
            workspaces = "on_workspace"
        }
    }
    signals = {
        on_workspace = function(signal_data)
            -- Signal data is of type `HyprlandWorkspaces`
            state.workspaces = signal_data
        end
    }
})

Advanced subscriptions

These subscriptions do not follow the common subscription syntax or are not autocompleted automatically by the LSP which is why they will be further explained here.

Calls

Calls is a powerful subscription that allows external proccesses to interact with astrum by sending a call signal.
Each key in the calls subscription table will be the call_signal and each value will be the name of the signal that will fire when it recieved the call signal

local called_times = 0

app:window("notification-thing", {
	view = function()
        return widgets:text("recieved call `mycall` ".. called_times.. " times")
	end,
	subscriptions = {
        calls = {
            mycall = "on_call"
        }
	},
	signals = {
        on_call = function(signal_data)
            called_times = called_times + 1
        end
	},
})

This will display a widget that shows the amount of times that it has recieved the mycall call signal
to send this call signal, add --call to the options of astrum (i.e. astrum --call mycall)

You can also send data through the call by adding a : after the call signal name, though note that it has to be in valid lua table

local data = ""

app:window("notification-thing", {
	view = function()
        return widgets:text("call `mycall` has sent data: ".. data)
	end,
	subscriptions = {
        calls = {
            mycall = "on_call"
        }
	},
	signals = {
        on_call = function(signal_data)
            data = signal_data.data
        end
	},
})

and executing the resulting command

astrum --call 'mycall:{data="test"}'

will result in the window text displaying the following

    call `mycall` has send data: test

Keybinds

Custom keybinds in astrum are defined through subscriptions
The index of the keybind susbcription table will be the signal name that it will send to when the specified keys have been pressed.

The first parameter of the value table are the modifiers that need to be pressed, seperated by commas.
The second parameter is a single character or a lowercase name for the keybind (you can see the full list of named keys in the source of the keybind susbcription)

An example implementation:

app:window("notification-thing", {
    keymode = "on_demand",
	subscriptions = {
        keybinds = {
            on_key = { "ctrl,shift", "space"},
            on_key2 = { "ctrl", "d"}
        }
	},
	signals = {
        on_key = function()
            print("ctrl shift and space have been pressed!")
        end,
        on_key2 = function()
            print("ctrl and d have been pressed!")
        end
	},
})

Note: keybinds will not work if the keymode is none

astrum wiki