Binding
As mentioned before binding an object's state to another - so in most cases a Variable
or a GObject.Object
property to a widget's property - is done through the bind
function which returns a Binding
object.
Binding
objects simply hold information about the source and how it should be transformed which Widget constructors can use to setup a connection between themselves and the source.
class Binding<Value> {
private transformFn: (v: any) => unknown
private emitter: Subscribable<Value> | Connectable
private prop?: string
as<T>(fn: (v: Value) => T): Binding<T>
get(): Value
subscribe(callback: (value: Value) => void): () => void
}
A Binding
can be constructed from an object implementing the Subscribable
interface (usually a Variable
) or an object implementing the Connectable
interface and one of its properties (usually a GObject.Object
instance).
function bind<T>(obj: Subscribable<T>): Binding<T>
function bind<
Obj extends Connectable,
Prop extends keyof Obj,
>(obj: Obj, prop: Prop): Binding<Obj[Prop]>
Subscribable and Connectable interface
Any object implementing one of these interfaces can be used with bind
.
interface Subscribable<T> {
subscribe(callback: (value: T) => void): () => void
get(): T
}
interface Connectable {
connect(signal: string, callback: (...args: any[]) => unknown): number
disconnect(id: number): void
}
Example Custom Subscribable
When binding the children of a box from an array, usually not all elements of the array changes each time, so it would make sense to not destroy the widget which represents the element.
import { type Subscribable } from "astal/binding"
import { Gtk } from "astal"
export class VarMap<K, T = Gtk.Widget> implements Subscribable {
#subs = new Set<(v: Array<[K, T]>) => void>()
#map: Map<K, T>
#notifiy() {
const value = this.get()
for (const sub of this.#subs) {
sub(value)
}
}
#delete(key: K) {
const v = this.#map.get(key)
if (v instanceof Gtk.Widget) {
v.destroy()
}
this.#map.delete(key)
}
constructor(initial?: Iterable<[K, T]>) {
this.#map = new Map(initial)
}
set(key: K, value: T) {
this.#delete(key)
this.#map.set(key, value)
this.#notifiy()
}
delete(key: K) {
this.#delete(key)
this.#notifiy()
}
get() {
return [...this.#map.entries()]
}
subscribe(callback: (v: Array<[K, T]>) => void) {
this.#subs.add(callback)
return () => this.#subs.delete(callback)
}
}
And this VarMap<key, Widget>
can be used as an alternative to Variable<Array<Widget>>
.
function MappedBox() {
const map = new VarMap([
[1, <MyWidget id={id} />]
[2, <MyWidget id={id} />]
])
const conns = [
gobject.connect("added", (_, id) => map.set(id, MyWidget({ id }))),
gobject.connect("removed", (_, id) => map.delete(id, MyWidget({ id }))),
]
return <box onDestroy={() => conns.map(id => gobject.disconnect(id))}>
{bind(map).as(arr => arr.sort(([a], [b]) => a - b).map(([,w]) => w))}
</box>
}
Example Custom Connectable
Astal provides decorator functions that make it easy to subclass gobjects, however you can read more about GObjects and subclassing on gjs.guide.
Objects coming from libraries usually have a singleton gobject you can access with .get_default()
.
Here is an example of a Brightness library by wrapping the brightnessctl
cli utility and by monitoring /sys/class/backlight
import GObject, { register, property } from "astal/gobject"
import { monitorFile, readFileAsync } from "astal/file"
import { exec, execAsync } from "astal/process"
const get = (args: string) => Number(exec(`brightnessctl ${args}`))
const screen = exec(`bash -c "ls -w1 /sys/class/backlight | head -1"`)
const kbd = exec(`bash -c "ls -w1 /sys/class/leds | head -1"`)
@register({ GTypeName: "Brightness" })
export default class Brightness extends GObject.Object {
static instance: Brightness
static get_default() {
if (!this.instance)
this.instance = new Brightness()
return this.instance
}
#kbdMax = get(`--device ${kbd} max`)
#kbd = get(`--device ${kbd} get`)
#screenMax = get("max")
#screen = get("get") / (get("max") || 1)
@property(Number)
get kbd() { return this.#kbd }
set kbd(value) {
if (value < 0 || value > this.#kbdMax)
return
execAsync(`brightnessctl -d ${kbd} s ${value} -q`).then(() => {
this.#kbd = value
this.notify("kbd")
})
}
@property(Number)
get screen() { return this.#screen }
set screen(percent) {
if (percent < 0)
percent = 0
if (percent > 1)
percent = 1
execAsync(`brightnessctl set ${Math.floor(percent * 100)}% -q`).then(() => {
this.#screen = percent
this.notify("screen")
})
}
constructor() {
super()
const screenPath = `/sys/class/backlight/${screen}/brightness`
const kbdPath = `/sys/class/leds/${kbd}/brightness`
monitorFile(screenPath, async f => {
const v = await readFileAsync(f)
this.#screen = Number(v) / this.#screenMax
this.notify("screen")
})
monitorFile(kbdPath, async f => {
const v = await readFileAsync(f)
this.#kbd = Number(v) / this.#kbdMax
this.notify("kbd")
})
}
}
And it can be used like any other library object.
function BrightnessSlider() {
const brightness = Brightness.get_default()
return <slider
value={bind(brightness, "screen")}
onDragged={({ value }) => brightness.screen = value}
/>
}