Widget

Gtk3

Additional widget properties

These are properties that Astal additionally adds to Gtk.Widgets

• class_name: string - List of class CSS selectors separated by white space.
• css: string - Inline CSS. e.g label { color: white; }. If no selector is specified * will be assumed. e.g color: white; will be inferred as * { color: white; }.
• cursor: string - Cursor style when hovering over widgets that have hover states, e.g it won't work on labels. list of valid values.
• click_through: boolean - Lets click events through.

To have a full list of available properties, reference the documentation of the widget.

• Astal3 widgets
• Gtk widgets

Additional widget methods

setup

setup is a convenience prop to remove the need to predefine widgets before returning them in cases where a reference is needed.

without setup

local function MyWidget()
    local button = Widget.Button()
    -- setup button
    return button
end

using setup

local function MyWidget()
    return Widget.Button({
        setup = function(self)
            -- setup button
        end,
    })
end

hook

Shorthand for connecting and disconnecting to Subscribable and Connectable objects.

without hook

local function MyWidget()
    local id = gobject.on_signal:connect(callback)
    local unsub = variable:subscribe(callback)

    return Widget.Box({
        on_destroy = function()
            GObject.signal_handler_disconnect(gobject, id)
            unsub()
        end,
    })
end

with hook

local function MyWidget()
    return Widget.Box({
        setup = function(self)
            self:hook(gobject, "signal", callback)
            self:hook(variable, callback)
        end,
    })
end

toggle_class_name

Toggle class names based on a condition.

local function MyWidget()
    return Widget.Box({
        setup = function(self)
            self:toggle_class_name("classname", some_condition)
        end,
    })
end

How to use non builtin Gtk widgets

Using the astalify function you can wrap widgets to behave like builtin widgets. It will apply the following:

• set visible to true by default (Gtk3 widgets are invisible by default)
• make gobject properties accept and consume Binding objects
• add properties and methods listed above

local astal = require("astal.gtk3")
local astalify = astal.astalify
local Gtk = astal.Gtk
local Gdk = astal.Gdk

local ColorButton = astalify(Gtk.ColorButton)

local function MyWidget()
    return ColorButton({
        setup = function(self)
            -- setup ColorButton instance
        end,
        use_alpha = true,
        rgba = Gdk.RGBA({
            red = 1,
            green = 0,
            blue = 0,
            alpha = 0.5,
        }),
        on_color_set = function(self)
            print(self.rgba:to_string())
        end
    })
end

Builtin Widgets

You can check the source code to have a full list of builtin widgets.

These widgets are available by default in Lua.

• Box: Astal.Box
• Button: Astal.Button
• CenterBox: Astal.CenterBox
• CircularProgress: Astal.CircularProgress
• DrawingArea: Gtk.DrawingArea
• Entry: Gtk.Entry
• Eventbox: Astal.EventBox
• Icon: Astal.Icon
• Label: Astal.Label
• Levelbar: Astal.LevelBar
• Overlay: Astal.Overlay
• Revealer: Gtk.Revealer
• Scrollable: Astal.Scrollable
• Slider: Astal.Slider
• Stack: Astal.Stack
• Switch: Gtk.Switch
• Window: Astal.Window

Gtk4

🚧 Work in Progress 🚧