Widget

Gtk3

Additional widget properties

These are properties that Astal additionally adds to Gtk.Widgets

• className: 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.
• clickThrough: 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

function MyWidget() {
    const button = Widget.Button()
    // setup button
    return button
}

using setup

function MyWidget() {
    function setup(button: Widget.Button) {
        // setup button
    }

    return <buttons setup={setup} />
}

hook

Shorthand for connection and disconnecting to Subscribable and Connectable objects.

without hook

function MyWidget() {
    const id = gobject.connect("signal", callback)
    const unsub = variable.subscribe(callback)

    return <box
        onDestroy={() => {
            gobject.disconnect(id)
            unsub()
        }}
    />
}

with hook

function MyWidget() {
    return <box
        setup={(self) => {
            self.hook(gobject, "signal", callback)
            self.hook(variable, callback)
        }}
    />
}

toggleClassName

Toggle classNames based on a condition

function MyWidget() {
    return <box
        setup={(self) => {
            self.toggleClassName("classname", someCondition)
        }}
    />
}

How to use non builtin Gtk widgets

Using the Widget.astalify mixin you can subclass widgets to behave like builtin widgets. The astalify mixin 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
• sets up signal handlers that are passed as props prefixed with on

import GObject from "gi://GObject"
import { Gtk, Gdk, Widget, astalify, type ConstructProps } from "astal/gtk3"

// subclass, register, define constructor props
class ColorButton extends astalify(Gtk.ColorButton) {
    static { GObject.registerClass(this) }

    constructor(props: ConstructProps<
        ColorButton,
        Gtk.ColorButton.ConstructorProps,
        { onColorSet: [] } // signals of Gtk.ColorButton have to be manually typed
    >) {
        super(props as any)
    }
}

function MyWidget() {
    function setup(button: ColorButton) {

    }

    return <ColorButton
        setup={setup}
        useAlpha
        rgba={new Gdk.RGBA({
            red: 1,
            green: 0,
            blue: 0,
            alpha: 0.5,
        })}
        onColorSet={(self) => {
            console.log(self.rgba)
        }}
    />
}

INFO

Signal properties have to be annotated manually for TypeScript. You can reference Gtk3 and Astal for available signals.

TypeScript

Type of widgets are available through Widget. Here is an example Widget that takes in and handles a possibly Binding prop.

import { Binding, Variable } from "astal"
import { Widget } from "astal/gtk3"

export interface ToggleButtonProps extends Widget.ButtonProps {
    onToggled?: (self: Widget.Button, on: boolean) => void
    state?: Binding<boolean> | boolean
    child?: JSX.Element
}

export default function ToggleButton(btnprops: ToggleButtonProps) {
    const { state = false, onToggled, setup, child, ...props } = btnprops
    const innerState = Variable(state instanceof Binding ? state.get() : state)

    return <button
        {...props}
        setup={self => {
            setup?.(self)

            self.toggleClassName("active", innerState.get())
            self.hook(innerState, () => self.toggleClassName("active", innerState.get()))

            if (state instanceof Binding) {
                self.hook(state, () => innerState.set(state.get()))
            }
        }}
        onClicked={self => {
            onToggled?.(self, !innerState.get())
        }}
    >
        {child}
    </button>
}

Builtin Widgets

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

These widgets are available by default in JSX.

• 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 🚧