diff options
Diffstat (limited to 'docs/guide/ags')
| -rw-r--r-- | docs/guide/ags/cli-app.md | 131 | ||||
| -rw-r--r-- | docs/guide/ags/faq.md | 290 | ||||
| -rw-r--r-- | docs/guide/ags/first-widgets.md | 400 | ||||
| -rw-r--r-- | docs/guide/ags/installation.md | 65 | ||||
| -rw-r--r-- | docs/guide/ags/theming.md | 169 | ||||
| -rw-r--r-- | docs/guide/ags/utilities.md | 174 | ||||
| -rw-r--r-- | docs/guide/ags/variable.md | 141 | ||||
| -rw-r--r-- | docs/guide/ags/widget.md | 227 |
8 files changed, 1597 insertions, 0 deletions
diff --git a/docs/guide/ags/cli-app.md b/docs/guide/ags/cli-app.md new file mode 100644 index 0000000..ceed56a --- /dev/null +++ b/docs/guide/ags/cli-app.md @@ -0,0 +1,131 @@ +# 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 +``` + +## 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<string>) { + print(...args) + }, + + // every subsequent calls + client(message: (msg: string) => string, ...args: Array<string>) { + 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 new file mode 100644 index 0000000..6edc250 --- /dev/null +++ b/docs/guide/ags/faq.md @@ -0,0 +1,290 @@ +# Frequently asked question, common issues, tips and tricks + +## Monitor id does not match compositor + +The monitor 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 which you can get from compositor libraries. + +Example with Hyprland + +```tsx +import Hyprland from "gi://AstalHyprland" + +function Bar(gdkmonitor) { + return <window gdkmonitor={gdkmonitor} /> +} + +function main() { + for (const m of Hyprland.get_default().get_monitors()) { + Bar(m.gdk_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 `<icon-name>-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") +``` + +## Binding custom structures + +The `bind` function can take two types of objects. + +```ts +interface Subscribable<T = unknown> { + subscribe(callback: (value: T) => void): () => void + get(): T +} + +interface Connectable { + connect(signal: string, callback: (...args: any[]) => unknown): number + disconnect(id: number): void +} +``` + +`Connectable` is for mostly gobjects, while `Subscribable` is for `Variables` +and custom objects. + +For example you can compose `Variables` in using a class. + +```ts +type MyVariableValue = { + number: number + string: string +} + +class MyVariable { + number = Variable(0) + string = Variable("") + + get(): MyVariableValue { + return { + number: this.number.get(), + string: this.string.get(), + } + } + + subscribe(callback: (v: MyVariableValue) => void) { + const unsub1 = this.number.subscribe((value) => { + callback({ string: value, number: this.number.get() }) + }) + + const unsub2 = this.string.subscribe((value) => { + callback({ number: value, string: this.string.get() }) + }) + + return () => { + unsub1() + unsub2() + } + } +} +``` + +Then it can be used with `bind`. + +```tsx +function MyWidget() { + const myvar = new MyVariable() + const label = bind(myvar).as(({ string, number }) => { + return `${string} ${number}` + }) + + return <label label={label} /> +} +``` + +## 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 <window> + <box halign={START} /> + </window> +} +``` + +::: + +:::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 <window gdkmonitor={gdkmonitor} /> +} +``` + +::: + +:::code-group + +```ts [app.ts] +import { Gdk, Gtk } from "astal" +import Bar from "./Bar" + +function main() { + const bars = new Map<Gdk.Monitor, Gtk.Widget>() + + // 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 <RegularWindow + onDeleteEvent={(self) => { + self.hide() + return true + }} +> + {child} +</RegularWindow> +``` diff --git a/docs/guide/ags/first-widgets.md b/docs/guide/ags/first-widgets.md new file mode 100644 index 0000000..2c64732 --- /dev/null +++ b/docs/guide/ags/first-widgets.md @@ -0,0 +1,400 @@ +# 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 <window className="Bar" monitor={monitor}> + <box>Content of the widget</box> + </window> +} +``` + +::: + +::: 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 <button onClicked="echo hello"> + Clicke Me! + </button> +} +``` + +```ts [MyButton.ts] +import { Widget } from "astal" + +function MyButton(): Widget.Button { + return Widget.Button({ + onClicked: "echo hello", + 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 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 <window> + <box> + Click The button + <MyButton /> + </box> + </window> +} +``` + +Notice that widgets you defined start with a capital letter `<MyButton />`. +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 <button>{label}</button> +} +``` + +You can also pass JavaScript to markup attributes + +```tsx +function MyWidget() { + const label = "hello" + + return <button label={label} /> +} +``` + +## Conditional Rendering + +You can use the same techniques as you use when writing regular JavaScript code. +For example, you can use an if statement to conditionally include JSX: + +```tsx +function MyWidget() { + let content + + if (condition) { + content = <True /> + } else { + content = <False /> + } + + return <box>{content}</box> +} +``` + +You can also inline a [conditional `?`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_operator) (ternary) expression. + +```tsx +function MyWidget() { + return <box>{condition ? <True /> : <False />}</box> +} +``` + +When you don’t need the `else` branch, you can also use a shorter [logical && syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_AND#short-circuit_evaluation): + +```tsx +function MyWidget() { + return <box>{condition && <True />}</box> +} +``` + +:::info +As you can guess from the above snippet, [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) values are not rendered. +::: + +## Rendering lists + +You can use [`for` loops](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for) or [array `map()` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map). + +```tsx +function MyWidget() { + const labels = [ + "label1" + "label2" + "label3" + ] + + return <box> + {labels.map(label => ( + <label label={label} /> + ))} + </box> +} +``` + +## Widget signal handlers + +You can respond to events by declaring event handler functions inside your widget: + +```tsx +function MyButton() { + function onClicked(self: Widget.Button, ...args) { + console.log(self, "was clicked") + } + + return <button onClicked={onClicked} /> +} +``` + +The handler can also be a string, which will get executed in a subprocess asynchronously. + +```tsx +function MyButton() { + return <button onClicked="echo hello" /> +} +``` + +:::info +Attributes prefixed with `on` will connect to a `signal` of the widget. +Their types are not generated, but written by hand, which means not all of them are typed. +Refer to the Gtk and Astal docs to have a full list of them. +::: + +## How properties are passed + +Using JSX, a custom widget will always have a single object as its parameter. + +```ts +type Props = { + myprop: string + child?: JSX.Element // when only one child is passed + children?: Array<JSX.Element> // when multiple children are passed +} + +function MyWidget({ myprop, child, children }: Props) { + // +} +``` + +```tsx +// child prop of MyWidget is the box +return <MyWidget myprop="hello"> + <box /> +</MyWidget> +``` + +```tsx +// children prop of MyWidget is [box, box, box] +return <MyWidget myprop="hello"> + <box /> + <box /> + <box /> +</MyWidget> +``` + +## State management + +The state of widgets are handled with Bindings. A `Binding` lets you +connect the state of one [GObject](https://docs.gtk.org/gobject/class.Object.html) to another, in our case it is used to +rerender part of a widget based on the state of a `GObject`. +A `GObject` can be a [Variable](./variable) or it can be from a [Library](../libraries/references). + +We use the `bind` function to create a `Binding` object from a `Variable` or +a regular GObject and one of its properties. + +Here is an example of a Counter widget that uses a `Variable` as its state: + +```tsx +import { Variable, bind } from "astal" + +function Counter() { + const count = Variable(0) + + function increment() { + count.set(count.get() + 1) + } + + return <box> + <label label={bind(count).as(num => num.toString())} /> + <button onClicked={increment}> + Click to increment + <button> + </box> +} +``` + +:::info +Bindings have an `.as()` method which lets you transform the assigned value. +In the case of a Label, its label property expects a string, so it needs to be +turned to a string first. +::: + +:::tip +`Variables` have a shorthand for `bind(variable).as(transform)` + +```tsx +const v = Variable(0) +const transform = (v) => v.toString() + +return <box> + {/* these two are equivalent */} + <label label={bind(v).as(transform)} /> + <label label={v(transform)} /> +</box> +``` + +::: + +Here is an example of a battery percent label that binds the `percentage` +property of the Battery object from the [Battery Library](/guide/libraries/battery): + +```tsx +import Battery from "gi://AstalBattery" +import { bind } from "astal" + +function BatteryPercentage() { + const bat = Battery.get_default() + + return <label label={bind(bat, "percentage").as((p) => p * 100 + " %")} /> +} +``` + +## Dynamic children + +You can also use a `Binding` for `child` and `children` properties. + +```tsx +const child = Variable(<box />) + +return <box>{child}</box> +``` + +```tsx +const num = Variable(3) +const range = (n) => [...Array(n).keys()] + +return <box> + {num(n => range(n).map(i => ( + <button> + {i.toString()} + <button/> + )))} +<box> +``` + +:::warning +Only bind children of the `box` or the `stack` widget. Gtk does not cleanup widgets by default, +they have to be explicitly destroyed. The box widget is a special container that +will implicitly call `.destroy()` on its removed child widgets. +You can disable this behavior by setting the `noImplicityDestroy` property. +::: + +:::info +The above example destroys and recreates every widget in the list everytime +the value of the `Variable` changes. There might be cases where you would +want to handle child creation yourself, because you don't want to lose the +inner state of widgets that does not need to be recreated. +::: + +When there is at least one `Binding` passed as a child, the `children` +parameter will always be a flattened `Binding<Array<JSX.Element>>` + +```tsx +function MyContainer({ children }) { + // children is a Binding over an Array of widgets +} + +return <MyContainer> + <box /> + {num(n => range(n).map(i => ( + <button> + {i.toString()} + <button/> + )))} + [ + [ + <button /> + ] + <button /> + ] +</MyContainer> +``` + +:::info +You can pass the followings as children: + +- widgets +- deeply nested arrays of widgets +- bindings of widgets, +- bindings of deeply nested arrays of widgets + +[falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) values are not rendered and anything not from this list +will be coerced into a string and rendered as a label +::: diff --git a/docs/guide/ags/installation.md b/docs/guide/ags/installation.md new file mode 100644 index 0000000..0adcf68 --- /dev/null +++ b/docs/guide/ags/installation.md @@ -0,0 +1,65 @@ +# Installation + +## Nix + +maintainer: [@Aylur](https://github.com/Aylur) + +Read more about it on the [nix page](../getting-started/nix#ags) + +You can try without installing. + +<!--TODO: remove v2 after merge--> +```sh +nix run github:aylur/ags/v2 -- --help +``` + +## Bulding AGS from source + +1. [Install Astal](../getting-started/installation.md) if you have not already + +2. Install the following dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu go npm gjs +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install golang npm gjs +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install golang-go npm gjs +``` + +::: + +3. Clone the repo and Install + +<!--TODO: remove v2 after merge--> +```sh +git clone https://github.com/aylur/ags.git +cd ags/src +git checkout v2 # https://github.com/Aylur/ags/pull/504 +go install +``` + +:::info +If you have installed Astal **not** in `/usr` make sure to set its path. + +```sh +go install -ldflags "-X main.astalGjs=$(pkg-config --variable prefix astal-0.1)/share/astal/gjs" +``` + +::: + +:::tip +`go install` installs the `ags` binary to `$GOPATH/bin` so make sure its in your `$PATH`. +You can move it to another directory if you like. For example + +```sh +mv $GOPATH/bin/ags ~/.local/bin/ags +``` + +::: diff --git a/docs/guide/ags/theming.md b/docs/guide/ags/theming.md new file mode 100644 index 0000000..ea83e35 --- /dev/null +++ b/docs/guide/ags/theming.md @@ -0,0 +1,169 @@ +# Theming + +Since the widget toolkit is **GTK3** theming is done with **CSS**. + +- [CSS tutorial](https://www.w3schools.com/css/) +- [GTK CSS Overview wiki](https://docs.gtk.org/gtk3/css-overview.html) +- [GTK CSS Properties Overview wiki](https://docs.gtk.org/gtk3/css-properties.html) + +:::warning GTK is not the web +While most features are implemented in GTK, +you can't assume anything that works on the web will work with GTK. +Refer to the [GTK docs](https://docs.gtk.org/gtk3/css-overview.html) +to see what is available. +::: + +So far every widget you made used your default GTK3 theme. +To make them more custom, you can apply stylesheets to them. + +## From file at startup + +You can pass a path to a file or css as a string in `App.start` + +:::code-group + +```ts [app.ts] +const inlineCss = ` +window { + background-color: transparent; +} +` + +App.start({ + css: "./style.css", + css: `${SRC}/style.css'`, + css: inlineCss, +}) +``` + +::: + +:::info +The global `SRC` will point to the directory `app.ts` is in. +AGS will set the current working directory to `--config`, so `./style.css` also works. +::: + +## Css Property on Widgets + +```ts +Widget.Label({ + css: "color: blue; padding: 1em;", + label: "hello", +}) +``` + +:::info +The `css` property of a widget will not cascade to its children. +::: + +## Apply Stylesheets at Runtime + +You can apply additional styles at runtime. + +```ts +App.apply_css("/path/to/file.css") +``` + +```ts +App.apply_css(` +window { + background-color: transparent; +} +`) +``` + +```ts +App.reset_css() // reset if need +``` + +:::warning +`App.apply_css` will apply on top of other stylesheets applied before. +You can reset stylesheets with `App.resetCss` +::: + +## Inspector + +If you are not sure about the widget hierarchy or any CSS selector, +you can use the [GTK inspector](https://wiki.gnome.org/Projects/GTK/Inspector) + +```sh +# to bring up the inspector run +ags --inspector +``` + +## Using SCSS + +Gtk's CSS only supports a subset of what the web offers. +Most notably nested selectors are unsupported by Gtk, but this can be +workaround by using preprocessors like [SCSS](https://sass-lang.com/). + +:::code-group + +```sh [Arch] +sudo pacman -Syu dart-sass +``` + +```sh [Fedora] +npm install -g sass # not packaged on Fedora +``` + +```sh [Alpine] +sudo apk add dart-sass +``` + +```sh [Ubuntu] +npm install -g sass # not packaged on Ubuntu +``` + +```sh [openSUSE] +sudo zypper install dart-sass +``` + +::: + +Importing `scss` files will simply return transpiled css. + +:::code-group + +```ts [app.ts] +import style from "./style.scss" + +App.start({ + css: style, + main() {}, +}) +``` + +::: + +:::tip +If you for example want to set scss varibles from JS, +You can inline import, compose, and transpile yourself. + +```ts [app.ts] +import style1 from "inline:./style1.scss" +import style2 from "inline:./style2.scss" + +const tmpscss = "/tmp/style.scss" +const target = "/tmp/style.css" + +writeFile(tmpscss, ` + $var1: red; + $var1: blue; + ${style1} + ${style1} +`) + +exec(`sass ${tmpscss} ${target}`) + +App.start({ + css: target, +}) + +``` + +::: + +:::info +If you want other preprocessors support builtin open an Issue. +::: diff --git a/docs/guide/ags/utilities.md b/docs/guide/ags/utilities.md new file mode 100644 index 0000000..42589d3 --- /dev/null +++ b/docs/guide/ags/utilities.md @@ -0,0 +1,174 @@ +# Utilities + +## File functions + +Import them from `astal` or `astal/file` + +```ts +import { + readFile, + readFileAsync, + writeFile, + writeFileAsync, + monitorFile, +} from "astal" +``` + +### Reading files + +```ts +function readFile(path: string): string +function readFileAsync(path: string): Promise<string> +``` + +### Writing files + +```ts +function writeFile(path: string, content: string): void +function writeFileAsync(path: string, content: string): Promise<void> +``` + +### Monitoring files + +```ts +function monitorFile( + path: string, + callback: (file: string, event: Gio.FileMonitorEvent) => void, +): Gio.FileMonitor +``` + +## Timeouts and Intervals + +Import them from `astal` or `astal/time` + +```ts +import { interval, timeout, idle } from "astal" +``` + +You can use javascript native `setTimeout` or `setInterval` +they return a [GLib.Source](https://docs.gtk.org/glib/struct.Source.html) instance. +Alternatively you can use these functions provided by Astal, +which return an [Astal.Time](https://aylur.github.io/libastal/class.Time.html) instance. + +`Astal.Time` has a `now` signal and a `cancelled` signal. + +### Interval + +Will immediately execute the function and every `interval` millisecond. + +```ts +function interval(interval: number, callback?: () => void): Astal.Time +``` + +### Timeout + +Will execute the `callback` after `timeout` millisecond. + +```ts +function timeout(timeout: number, callback?: () => void): Astal.Time +``` + +### Idle + +Executes `callback` whenever there are no higher priority events pending. + +```ts +function idle(callback?: () => void): Astal.Time +``` + +Example: + +```ts +const timer = interval(1000, () => { + console.log("optional callback") +}) + +timer.connect("now", () => { + console.log("tick") +}) + +timer.connect("cancelled", () => { + console.log("cancelled") +}) + +timer.cancel() +``` + +## Process functions + +Import them from `astal` or `astal/proc` + +```ts +import { subprocess, exec, execAsync } from "astal" +``` + +### Subprocess + +You can start a subprocess and run callback functions whenever it outputs to +stdout or stderr. [Astal.Process](https://aylur.github.io/libastal/class.Process.html) has a `stdout` and `stderr` signal. + +```ts +function subprocess(args: { + cmd: string | string[] + out?: (stdout: string) => void + err?: (stderr: string) => void +}): Astal.Process + +function subprocess( + cmd: string | string[], + onOut?: (stdout: string) => void, + onErr?: (stderr: string) => void, +): Astal.Process +``` + +Example: + +```ts +const proc = subprocess( + "some-command", + (out) => console.log(out), // optional + (err) => console.error(out), // optional +) + +// or with signals +const proc = subprocess("some-command") +proc.connect("stdout", (out) => console.log(out)) +proc.connect("stderr", (err) => console.error(err)) +``` + +### Executing external commands and scripts + +```ts +function exec(cmd: string | string[]): string +function execAsync(cmd: string | string[]): Promise<string> +``` + +Example: + +```ts +try { + const out = exec("/path/to/script") + console.log(out) +} catch (err) { + console.error(err) +} + +execAsync(["bash", "-c", "/path/to/script.sh"]) + .then((out) => console.log(out)) + .catch((err) => console.error(err)) +``` + +:::warning +`subprocess`, `exec`, and `execAsync` executes the passed executable as is. +They are **not** executed in a shell environment, +they do **not** expand env variables like `$HOME`, +and they do **not** handle logical operators like `&&` and `||`. + +If you want bash, run them with bash. + +```ts +exec(["bash", "-c", "command $VAR && command"]) +exec("bash -c 'command $VAR' && command") +``` + +::: diff --git a/docs/guide/ags/variable.md b/docs/guide/ags/variable.md new file mode 100644 index 0000000..96e8d38 --- /dev/null +++ b/docs/guide/ags/variable.md @@ -0,0 +1,141 @@ +# Variable + +```js +import { Variable } from "astal" +``` + +Variable is just a simple `GObject` that holds a value. +And has shortcuts for hooking up subprocesses. + +:::info +The `Variable` object imported from the `"astal"` package is **not** [Astal.Variable](https://aylur.github.io/libastal/class.Variable.html). +::: + +## Variable as state + +```typescript +const myvar = Variable<string>("initial-value") + +// whenever its value changes, callback will be executed +myvar.subscribe((value: string) => { + console.log(value) +}) + +// settings its value +myvar.set("new value") + +// getting its value +const value = myvar.get() + +// binding them to widgets +Widget.Label({ + label: bind(myvar).as((value) => `transformed ${value}`), + label: myvar((value) => `transformed ${value}`), // shorthand for the above +}) +``` + +:::warning +Make sure to make the transform functions pure. The `.get()` function can be called +anytime by `astal` especially when `deriving`, so make sure there are no sideeffects. +::: + +## Composing variables + +Using `Variable.derive` we can compose both Variables and Bindings. + +```typescript +const v1: Variable<number> = Variable(2) +const v2: Variable<number> = Variable(3) + +// first argument is a list of dependencies +// second argument is a transform function, +// where the parameters are the values of the dependencies in the order they were passed +const v3: Variable<number> = Variable.derive([v1, v2], (v1, v2) => { + return v1 * v2 +}) + +const b1: Binding<string> = bind(obj, "prop") +const b2: Binding<string> = bind(obj, "prop") + +const b3: Variable<string> = Variable.derive([b1, b2], (b1, b2) => { + return `${b1}-${b2}` +}) +``` + +## Subprocess shorthands + +Using `.poll` and `.watch` we can start subprocess and capture their +output in `Variables`. They can poll and watch at the same time, but they +can only poll/watch one subprocess. + +:::warning +The command parameter is passed to [execAsync](/guide/ags/utilities#executing-external-commands-and-scripts) +which means they are **not** executed in a shell environment, +they do **not** expand env variables like `$HOME`, +and they do **not** handle logical operators like `&&` and `||`. + +If you want bash, run them with bash. + +```js +Variable("").poll(1000, ["bash", "-c", "command $VAR && command"]) +``` + +::: + +```typescript +const myVar = Variable<number>(0) + .poll(1000, "command", (out: string, prev: number) => parseInt(out)) + .poll(1000, ["bash", "-c", "command"], (out, prev) => parseInt(out)) + .poll(1000, (prev) => prev + 1) +``` + +```typescript +const myVar = Variable<number>(0) + .watch("command", (out: string, prev: number) => parseInt(out)) + .watch(["bash", "-c", "command"], (out, prev) => parseInt(out)) +``` + +You can temporarily stop them and restart them whenever. + +```js +myvar.stopWatch() // this kills the subprocess +myvar.stopPoll() + +myvar.startListen() // launches the subprocess again +myvar.startPoll() + +console.log(myvar.isListening()) +console.log(myvar.isPolling()) +``` + +## Gobject connection shorthands + +Using `.observe` you can connect gobject signals and capture their value. + +```typescript +const myvar = Variable("") + .observe(obj1, "signal", () => "") + .observe(obj2, "signal", () => "") +``` + +## Dispose if no longer needed + +This will stop the interval and force exit the subprocess and disconnect gobjects. + +```js +myVar.drop() +``` + +:::warning +Don't forget to drop them when they are defined inside widgets +with either `.poll`, `.watch` or `.observe` + +```tsx +function MyWidget() { + const myvar = Variable().poll() + + return <box onDestroy={() => myvar.drop()} /> +} +``` + +::: diff --git a/docs/guide/ags/widget.md b/docs/guide/ags/widget.md new file mode 100644 index 0000000..1fe755f --- /dev/null +++ b/docs/guide/ags/widget.md @@ -0,0 +1,227 @@ +# Widget + +## AGS widget properties + +These are properties that Astal.js 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](https://docs.gtk.org/gdk3/ctor.Cursor.new_from_name.html). +- clickThrough: `boolean` - Lets click events through. + +To have a full list of available properties, reference the documentation of the widget. + +- [Astal widgets](https://aylur.github.io/libastal/index.html#classes) +- [Gtk widgets](https://docs.gtk.org/gtk3/#classes) + +## AGS widget methods + +Additional methods that Astal.js adds to Gtk.Widget instances + +### setup + +`setup` is a convenience prop to not have predefine widgets before returning them + +without `setup` + +```tsx +function MyWidget() { + const button = Widget.Button() + // setup button + return button +} +``` + +using `setup` + +```tsx +function MyWidget() { + function setup(button: Widget.Button) { + // setup button + } + + return <buttons setup={setup} /> +} +``` + +### hook + +Shorthand for connection and disconnecting to gobjects. + +without `hook` + +```tsx +function MyWidget() { + const id = gobject.connect("signal", callback) + + return <box + onDestroy={() => { + gobject.disconnect(id) + }} + /> +} +``` + +with `hook` + +```tsx +function MyWidget() { + return <box + setup={(self) => { + self.hook(gobject, "signal", callback) + }} + /> +} +``` + +### toggleClassName + +Toggle classNames based on a condition + +```tsx +function MyWidget() { + return <box + setup={(self) => { + self.toggleClassName("classname", someCondition) + }} + /> +} +``` + +## How to use non builtin Gtk widgets + +Using `Widget.astalify` you can setup widget constructors to behave like builtin widgets. +The `astalify` function 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 +- proxify the constructor so the `new` keyword is not needed +- sets up signal handlers that are passed as props prefixed with `on` + +```tsx +import { Widget, Gtk } from "astal" + +// define its props, constructor and type +export type ColorButtonProps = Widget.ConstructProps< + Gtk.ColorButton, + Gtk.ColorButton.ConstructorProps, + { onColorSet: [] } +> +export const ColorButton = Widget.astalify< + typeof Gtk.ColorButton, + ColorButtonProps, + "ColorButton" +>(Gtk.ColorButton) +export type ColorButton = ReturnType<typeof ColorButton> + +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](https://gjs-docs.gnome.org/gtk30~3.0/) +and [Astal](https://aylur.github.io/libastal/index.html#classes) for available signals. +::: + +:::tip + +As stated before children are passed as either `child` or `children` property, +when passing a container widget with `Widget.astalify` these rules still apply. +While subclasses of `Gtk.Bin` *can* take a `child` property in gjs, you might notice +a warning that it is deprecated. You can workaround this with a simple wrapper function. + +```tsx +const GtkFrame = Widget.astalify< + typeof Gtk.Frame, + FrameProps, + "Frame" +>(Gtk.Frame) + +export function Frame({ child, ...props }: FrameProps) { + const frame = GtkFrame(props) + frame.add(child) // use the widget's child adding function + return frame +} +``` + +::: + +## TypeScript + +Type of widgets are available through `Widget`. +Here is an example Widget that takes in and handles a possibly `Binding` prop. + +```tsx +import { Binding, Variable, Widget } from "astal" + +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](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) |