From ede8890a08b3fbbb1f6df3b8c277ab6424d1befd Mon Sep 17 00:00:00 2001 From: Aylur Date: Tue, 15 Oct 2024 01:22:24 +0000 Subject: docs: better explain ags --- docs/guide/ags/binding.md | 234 ----------------------- docs/guide/ags/cli-app.md | 167 ----------------- docs/guide/ags/faq.md | 266 -------------------------- docs/guide/ags/first-widgets.md | 402 ---------------------------------------- docs/guide/ags/gobject.md | 166 ----------------- docs/guide/ags/installation.md | 65 ------- docs/guide/ags/theming.md | 161 ---------------- docs/guide/ags/utilities.md | 174 ----------------- docs/guide/ags/variable.md | 153 --------------- docs/guide/ags/widget.md | 208 --------------------- 10 files changed, 1996 deletions(-) delete mode 100644 docs/guide/ags/binding.md delete mode 100644 docs/guide/ags/cli-app.md delete mode 100644 docs/guide/ags/faq.md delete mode 100644 docs/guide/ags/first-widgets.md delete mode 100644 docs/guide/ags/gobject.md delete mode 100644 docs/guide/ags/installation.md delete mode 100644 docs/guide/ags/theming.md delete mode 100644 docs/guide/ags/utilities.md delete mode 100644 docs/guide/ags/variable.md delete mode 100644 docs/guide/ags/widget.md (limited to 'docs/guide/ags') diff --git a/docs/guide/ags/binding.md b/docs/guide/ags/binding.md deleted file mode 100644 index f1592a0..0000000 --- a/docs/guide/ags/binding.md +++ /dev/null @@ -1,234 +0,0 @@ -# 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. - -```ts -class Binding { - private transformFn: (v: any) => unknown - private emitter: Subscribable | Connectable - private prop?: string - - as(fn: (v: Value) => T): Binding - 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). - -```ts -function bind(obj: Subscribable): Binding - -function bind< - Obj extends Connectable, - Prop extends keyof Obj, ->(obj: Obj, prop: Prop): Binding -``` - -## Subscribable and Connectable interface - -Any object implementing one of these interfaces can be used with `bind`. - -```ts -interface Subscribable { - 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. - -::: code-group - -```ts :line-numbers [varmap.ts] -import { type Subscribable } from "astal/binding" -import { Gtk } from "astal" - -export class VarMap implements Subscribable { - #subs = new Set<(v: Array<[K, T]>) => void>() - #map: Map - - #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` can be used as an alternative to `Variable>`. - -```tsx -function MappedBox() { - const map = new VarMap([ - [1, ] - [2, ] - ]) - - const conns = [ - gobject.connect("added", (_, id) => map.set(id, MyWidget({ id }))), - gobject.connect("removed", (_, id) => map.delete(id, MyWidget({ id }))), - ] - - return conns.map(id => gobject.disconnect(id))}> - {bind(map).as(arr => arr.sort(([a], [b]) => a - b).map(([,w]) => w))} - -} -``` - -## Example Custom Connectable - -This was formerly known as a "Service" in AGS. -Astal provides [decorator functions](./gobject#example-usage) that make it easy to subclass gobjects, however -you can read more about GObjects and subclassing on [gjs.guide](https://gjs.guide/guides/gobject/subclassing.html#gobject-subclassing). - -Objects coming from [libraries](../libraries/references#astal-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` - -::: code-group - -```ts :line-numbers [brightness.ts] -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. - -```tsx -function BrightnessSlider() { - const brightness = Brightness.get_default() - - return brightness.screen = value} - /> -} -``` diff --git a/docs/guide/ags/cli-app.md b/docs/guide/ags/cli-app.md deleted file mode 100644 index ec6d174..0000000 --- a/docs/guide/ags/cli-app.md +++ /dev/null @@ -1,167 +0,0 @@ -# CLI and App - -`App` is a singleton **instance** of [Astal.Application](https://aylur.github.io/libastal/class.Application.html). - -```ts -import { App } from "astal" -``` - -## Entry point - -:::code-group - -```ts [app.ts] -App.start({ - main() { - // setup anything - // instantiate widgets - }, -}) -``` - -::: - -:::warning -You can not instantiate widgets outside of the main function. -::: - -## Instance identifier - -You can run multiple instance by defining a unique instance name. - -```ts -App.start({ - instanceName: "my-instance", // defaults to "astal" - main() {}, -}) -``` - -## Messaging from CLI - -If you want to interact with an instance from the cli, you can do so by sending a message. - -```ts -App.start({ - main() {}, - requestHandler(request: string, res: (response: any) => void) { - if (request == "say hi") { - res("hi cli") - } - res("unknown command") - }, -}) -``` - -:::code-group - -```sh [ags] -ags -m "say hi" -# hi cli -``` - -```sh [astal] -astal say hi -# hi cli -``` - -::: - -If you want to run arbitrary JavaScript from cli, you can use `App.eval`. -It will evaluate the passed string as the body of an `async` function. - -```ts -App.start({ - main() {}, - requestHandler(js: string, res) { - App.eval(js).then(res).catch(res) - }, -}) -``` - -If the string does not contain a semicolon, a single expression is assumed and returned implicity. - -```sh -ags -m "'hello'" -# hello -``` - -If the string contains a semicolon, you have to return explicitly - -```sh -ags -m "'hello';" -# undefined - -ags -m "return 'hello';" -# hello -``` - -## Toggling Windows by their name - -In order for AGS to know about your windows, you have to register them. -You can do this by specifying a **unique** `name` and calling `App.add_window` - -```tsx {4} -import { App } from "astal" - -function Bar() { - return App.add_window(self)}> - - -} -``` - -You can also invoke `App.add_window` by simply passing the `App` to the `application` prop. - -```tsx {4} -import { App } from "astal" - -function Bar() { - return - - -} -``` - -:::warning -When assigning the `application` prop make sure `name` comes before. -Props are set sequentially and if name is applied after application it won't work. -::: - -```sh -ags -t Bar -``` - -## App without AGS - -As mentioned before AGS is only a scaffolding tool. You can setup -a dev environment and a bundler yourself. In which case you won't be using -the ags cli to run the bundled scripts. The produced script can run as the main instance -and a "client" instance. - -The first time you run your bundled script the `main` function gets executed. -While that instance is running any subsequent execution of the script will call -the `client` function. - -:::code-group - -```ts [main.ts] -App.start({ - // main instance - main(...args: Array) { - print(...args) - }, - - // every subsequent calls - client(message: (msg: string) => string, ...args: Array) { - const res = message("you can message the main instance") - console.log(res) - }, - - // this runs in the main instance - requestHandler(request: string, res: (response: any) => void) { - res("response from main") - }, -}) -``` - -::: diff --git a/docs/guide/ags/faq.md b/docs/guide/ags/faq.md deleted file mode 100644 index 76d8e72..0000000 --- a/docs/guide/ags/faq.md +++ /dev/null @@ -1,266 +0,0 @@ -# Frequently asked question, common issues, tips and tricks - -## Monitor id does not match compositor - -The monitor id property that windows expect is mapped by Gdk, which is not always -the same as the compositor. Instead use the `gdkmonitor` property which expects -a `Gdk.Monitor` object. - -```tsx -import { App } from "astal" - -function Bar(gdkmonitor) { - return -} - -function main() { - for (const monitor of App.get_monitors()) { - if (monitor.model == "your-desired-model") { - Bar(monitor) - } - } -} - -App.start({ main }) -``` - -## Environment variables - -JavaScript is **not** an bash. - -```ts -const HOME = exec("echo $HOME") // does not work -``` - -`exec` and `execAsync` runs the passed program as is, its **not** run in a -shell environment, so the above example just passes `$HOME` as a string literal -to the `echo` program. - -:::danger Please don't do this -You could pass it to bash, but that is a horrible approach. - -```ts -const HOME = exec("bash -c 'echo $HOME'") -``` - -::: - -You can read environment variables with [GLib.getenv](https://gjs-docs.gnome.org/glib20~2.0/glib.getenv). - -```ts -import GLib from "gi://GLib" - -const HOME = GLib.getenv("HOME") -``` - -## Custom SVG symbolic icons - -Put the svgs in a directory, named `-symbolic.svg` -and use `App.add_icons` or `icons` parameter in `App.start` - -:::code-group - -```ts [app.ts] -App.start({ - icons: `${SRC}/icons`, - main() { - Widget.Icon({ - icon: "custom-symbolic", // custom-symbolic.svg - css: "color: green;", // can be colored, like other named icons - }) - }, -}) -``` - -::: - -:::info -If there is a name clash with an icon from your current icon pack -the icon pack will take precedence -::: - -## Logging - -The `console` API in gjs uses glib logging functions. -If you just want to print some text as is to stdout -use the globally available `print` function or `printerr` for stderr. - -```ts -print("print this line to stdout") -printerr("print this line to stderr") -``` - -## Populate the global scope with frequently accessed variables - -It might be annoying to always import Gtk only for `Gtk.Align` enums. - -:::code-group - -```ts [globals.ts] -import Gtk from "gi://Gtk" - -declare global { - const START: number - const CENTER: number - const END: number - const FILL: number -} - -Object.assign(globalThis, { - START: Gtk.Align.START, - CENTER: Gtk.Align.CENTER, - END: Gtk.Align.END, - FILL: Gtk.Align.FILL, -}) -``` - -::: - -:::code-group - -```tsx [Bar.tsx] -export default function Bar() { - return - - -} -``` - -::: - -:::code-group - -```ts [app.ts] -import "./globals" -import Bar from "./Bar" - -App.start({ - main: Bar -}) -``` - -::: - -:::info -It is considered bad practice to populate the global scope, but its your code, not a public library. -::: - -## Auto create Window for each Monitor - -To have Window widgets appear on a monitor when its plugged in, listen to `App.monitor_added`. - -:::code-group - -```tsx [Bar.tsx] -export default function Bar(gdkmonitor: Gdk.Monitor) { - return -} -``` - -::: - -:::code-group - -```ts [app.ts] -import { Gdk, Gtk } from "astal" -import Bar from "./Bar" - -function main() { - const bars = new Map() - - // initialize - for (const gdkmonitor of App.get_monitors()) { - bars.set(gdkmonitor, Bar(gdkmonitor)) - } - - App.connect("monitor-added", (_, gdkmonitor) => { - bars.set(gdkmonitor, Bar(gdkmonitor)) - }) - - App.connect("monitor-removed", (_, gdkmonitor) => { - bars.get(gdkmonitor)?.destroy() - bars.delete(gdkmonitor) - }) -} - -App.start({ main }) -``` - -::: - -## Error: Can't convert non-null pointer to JS value - -These happen when accessing list type properties. Gjs fails to correctly bind -`List` and other array like types of Vala as a property. - -```ts -import Notifd from "gi://AstalNotifd" -const notifd = Notifd.get_default() - -notifd.notifications // ❌ // [!code error] - -notifd.get_notifications() // ✅ -``` - -## How to create regular floating windows - -Use `Gtk.Window` with [Widget.astalify](/guide/ags/widget#how-to-use-non-builtin-gtk-widgets). - -By default `Gtk.Window` is destroyed on close. To prevent this add a handler for `delete-event`. - -```tsx {4-7} -const RegularWindow = Widget.astalify(Gtk.Window) - -return { - self.hide() - return true - }} -> - {child} - -``` - -## Is there a way to limit the width/height of a widget? - -Unfortunately not. You can set a minimum size with `min-width` and `min-heigth` css attributes, -but you can not set max size. - -## Custom widgets with bindable properties - -In function components you can wrap any primitive to handle both -binding and value cases as one. - -```tsx -function MyWidget(props: { prop: string | Binding }) { - const prop = props.prop instanceof Binding - ? props.prop - : bind({ get: () => props.prop, subscribe: () => () => {} }) - - function setup(self: Widget.Box) { - self.hook(prop, () => { - const value = prop.get() - // handler - }) - } - - return - -} -``` - -You can pass the prop the super constructor in subclasses - -```tsx -@register() -class MyWidget extends Widget.Box { - @property(String) - set prop(v: string) { - // handler - } - - constructor(props: { prop: string | Binding }) { - super(props) - } -} -``` diff --git a/docs/guide/ags/first-widgets.md b/docs/guide/ags/first-widgets.md deleted file mode 100644 index 6dba7b3..0000000 --- a/docs/guide/ags/first-widgets.md +++ /dev/null @@ -1,402 +0,0 @@ -# First Widgets - -AGS is the predecessor of Astal, which was written purely in TypeScript and so only supported -JavaScript/TypeScript. Now it serves as a scaffolding tool for Astal projects in TypeScript. -While what made AGS what it is, is now part of the Astal project, for simplicity we will -refer to the Astal TypeScript lib as AGS. - -:::tip -If you are not familiar with the JavaScript syntax [MDN](https://developer.mozilla.org/en-US/) -and [javascript.info](https://javascript.info/) have great references. -::: - -## Getting Started - -Start by initializing a project - -```sh -ags --init -``` - -then run `ags` in the terminal - -```sh -ags -``` - -Done! You have now a custom written bar using Gtk. - -:::tip -AGS will transpile every `.ts`, `.jsx` and `.tsx` files into regular javascript then -it will bundle everything into a single javascript file which then GJS can execute. -The bundler used is [esbuild](https://esbuild.github.io/). -::: - -## Root of every shell component: Window - -Astal apps are composed of widgets. A widget is a piece of UI that has its own logic and style. -A widget can be as small as a button or an entire bar. -The top level widget is always a [Window](https://aylur.github.io/libastal/class.Window.html) which will hold all widgets. - -::: code-group - -```tsx [widget/Bar.tsx] -function Bar(monitor = 0) { - return - Content of the widget - -} -``` - -::: - -::: code-group - -```ts [app.ts] -import Bar from "./widget/Bar" - -App.start({ - main() { - Bar(0) - Bar(1) // instantiate for each monitor - }, -}) -``` - -::: - -## Creating and nesting widgets - -Widgets are JavaScript functions which return Gtk widgets, -either by using JSX or using a widget constructor. - -:::code-group - -```tsx [MyButton.tsx] -function MyButton(): JSX.Element { - return -} -``` - -```ts [MyButton.ts] -import { Widget } from "astal" - -function MyButton(): Widget.Button { - return new Widget.Button( - { onClicked: "echo hello" }, - new Widget.Label({ label: "Click me!" }), - ) -} -``` - -::: - -:::info -The only difference between the two is the return type. -Using markup the return type is always `Gtk.Widget` (globally available as `JSX.Element`), -while using constructors the return type is the actual type of the widget. -It is rare to need the actual return type, so most if not all of the time, you can use markup. -::: - -Now that you have declared `MyButton`, you can nest it into another component. - -```tsx -function MyBar() { - return - - Click The button - - - -} -``` - -Notice that widgets you defined start with a capital letter ``. -Lowercase tags are builtin widgets, while capital letter is for custom widgets. - -## Displaying Data - -JSX lets you put markup into JavaScript. -Curly braces let you “escape back” into JavaScript so that you can embed some variable -from your code and display it. - -```tsx -function MyWidget() { - const label = "hello" - - return -} -``` - -You can also pass JavaScript to markup attributes - -```tsx -function MyWidget() { - const label = "hello" - - return -} -``` - -## Builtin Widgets - -You can check the [source code](https://github.com/aylur/astal/blob/main/core/gjs/src/widgets.ts) to have a full list of builtin widgets. - -These widgets are available by default in JSX. - -- box: [Astal.Box](https://aylur.github.io/libastal/class.Box.html) -- button: [Astal.Button](https://aylur.github.io/libastal/class.Button.html) -- centerbox: [Astal.CenterBox](https://aylur.github.io/libastal/class.CenterBox.html) -- circularprogress: [Astal.CircularProgress](https://aylur.github.io/libastal/class.CircularProgress.html) -- drawingarea: [Gtk.DrawingArea](https://docs.gtk.org/gtk3/class.DrawingArea.html) -- entry: [Gtk.Entry](https://docs.gtk.org/gtk3/class.Entry.html) -- eventbox: [Astal.EventBox](https://aylur.github.io/libastal/class.EventBox.html) -- icon: [Astal.Icon](https://aylur.github.io/libastal/class.Icon.html) -- label: [Astal.Label](https://aylur.github.io/libastal/class.Label.html) -- levelbar: [Astal.LevelBar](https://aylur.github.io/libastal/class.LevelBar.html) -- overlay: [Astal.Overlay](https://aylur.github.io/libastal/class.Overlay.html) -- revealer: [Gtk.Revealer](https://docs.gtk.org/gtk3/class.Revealer.html) -- scrollable: [Astal.Scrollable](https://aylur.github.io/libastal/class.Scrollable.html) -- slider: [Astal.Slider](https://aylur.github.io/libastal/class.Slider.html) -- stack: [Astal.Stack](https://aylur.github.io/libastal/class.Stack.html) -- switch: [Gtk.Switch](https://docs.gtk.org/gtk3/class.Switch.html) -- window: [Astal.Window](https://aylur.github.io/libastal/class.Window.html) -- cgit v1.2.3