diff options
Diffstat (limited to 'docs/guide')
25 files changed, 3166 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) diff --git a/docs/guide/getting-started/installation.md b/docs/guide/getting-started/installation.md new file mode 100644 index 0000000..ef5c6e8 --- /dev/null +++ b/docs/guide/getting-started/installation.md @@ -0,0 +1,69 @@ +# Installation + +## Nix + +maintainer: [@Aylur](https://github.com/Aylur) + +Read more about it on the [nix page](./nix#astal) + +## Arch + +maintainer: [@kotontrion](https://github.com/kotontrion) + +:::code-group + +```sh [Core Library] +yay -S libastal-git +``` + +```sh [Every Library] +yay -S libastal-meta +``` + +::: + +## Bulding libastal from source + +1. Clone the repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/core +``` + +2. Install the following dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala gtk3 gtk-layer-shell gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc valac gtk3-devel gtk-layer-shell-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libgtk3-dev libgtk-layer-shell-dev gobject-introspection +``` + +::: + +3. Build and install with `meson` + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +meson install -C build +``` + +::: diff --git a/docs/guide/getting-started/introduction.md b/docs/guide/getting-started/introduction.md new file mode 100644 index 0000000..92d2ff1 --- /dev/null +++ b/docs/guide/getting-started/introduction.md @@ -0,0 +1,23 @@ +# Introduction + +## What is Astal? + +Astal (_meaning "desk"_) is a bundle of libraries built using [GLib](https://docs.gtk.org/glib/) in Vala and C. +The core library [libastal](https://aylur.github.io/libastal) has some Gtk widgets that come packaged, +the most important one is the [Window](https://aylur.github.io/libastal/class.Window.html) which is the main toplevel component using [gtk-layer-shell](https://github.com/wmww/gtk-layer-shell). +This is what allows us to use Gtk as shell components on Wayland. +libastal also comes with some utility functions such as running external processes, +reading, writing and monitoring files. + +## Why Astal? + +What makes Astal convenient to use is not the core library, as it could easily be replaced +by the standard library of any of your favorite language that has bindings to Gtk, it is the +accompanying libraries (_formerly known as "services" in AGS_) + +Have you ever wanted to write a custom bar, custom notification popups +or an applauncher, but gave up because writing a workspace widget, +implementing the notification daemon or handling a search filter was too much of a hassle? + +Astal libraries have you [covered](/guide/libraries/references), you don't have to worry about these, +you just define the layout, style it with CSS and that's it. diff --git a/docs/guide/getting-started/nix.md b/docs/guide/getting-started/nix.md new file mode 100644 index 0000000..2b04bdc --- /dev/null +++ b/docs/guide/getting-started/nix.md @@ -0,0 +1,154 @@ +# Nix + +## Astal + +Using Astal on Nix will require you to package your project. + +:::code-group + +```nix [<i class="devicon-lua-plain"></i> Lua] +{ + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; + astal = { + url = "github:aylur/astal"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + }; + + outputs = { self, nixpkgs, astal }: let + system = "x86_64-linux"; + pkgs = nixpkgs.legacyPackages.${system}; + in { + packages.${system}.default = astal.lib.mkLuaPacakge { + inherit pkgs; + src = ./path/to/project; # should contain init.lua + + # add extra glib packages or binaries + extraPackages = [ + astal.packages.${system}.battery + pkgs.dart-sass + ]; + }; + }; +} +``` + +```nix [<i class="devicon-python-plain"></i> Python] +# Not documented yet +``` + +```nix [<i class="devicon-vala-plain"></i> Vala] +# keep in mind that this is just the nix derivation +# and you still have to use some build tool like meson +{ + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; + astal.url = "github:aylur/astal"; + }; + + outputs = { self, nixpkgs, astal }: let + system = "x86_64-linux"; + pkgs = nixpkgs.legacyPackages.${system}; + in { + packages.${system} = { + default = pkgs.stdenv.mkDerivation { + name = "my-shell"; + src = ./.; + + nativeBuildInputs = with pkgs; [ + meson + ninja + pkg-config + vala + gobject-introspection + ]; + + # add extra packages + buildInputs = [ + astal.packages.${system}.astal + ]; + }; + }; + }; +} +``` + +::: + +## AGS + +The recommended way to use AGS on NixOS is through the home-manager module. + +Example content of a `flake.nix` file that contains your `homeConfigurations`. + +<!--TODO: remove v2 after merge--> + +:::code-group + +```nix [<i class="devicon-nixos-plain"></i> flake.nix] +{ + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; + home-manager = { + url = "github:nix-community/home-manager"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + + # add ags https://github.com/Aylur/ags/pull/504 + ags.url = "github:aylur/ags/v2"; + }; + + outputs = { home-manager, nixpkgs, ... }@inputs: + let + system = "x86_64-linux"; + in + { + homeConfigurations."${username}" = home-manager.lib.homeManagerConfiguration { + pkgs = import nixpkgs { inherit system; }; + + # pass inputs as specialArgs + extraSpecialArgs = { inherit inputs; }; + + # import your home.nix + modules = [ ./home-manager/home.nix ]; + }; + }; +} +``` + +::: + +Example content of `home.nix` file + +:::code-group + +```nix [<i class="devicon-nixos-plain"></i> home.nix] +{ inputs, pkgs, ... }: +{ + # add the home manager module + imports = [ inputs.ags.homeManagerModules.default ]; + + programs.ags = { + enable = true; + configDir = ../ags; + + # additional packages to add to gjs's runtime + extraPackages = with pkgs; [ + inputs.ags.packages.${pkgs.system}.battery + fzf + ]; + }; +} +``` + +::: + +AGS by default only includes the core `libastal` library. +If you want to include any other [library](../libraries/references) you have to add them to `extraPackages`. +You can also add binaries which will be added to `$PATH`. + +:::warning +The `configDir` option symlinks the given path to `~/.config/ags`. +If you already have your source code there leave it as `null`. +::: diff --git a/docs/guide/getting-started/supported-languages.md b/docs/guide/getting-started/supported-languages.md new file mode 100644 index 0000000..634bad0 --- /dev/null +++ b/docs/guide/getting-started/supported-languages.md @@ -0,0 +1,65 @@ +# Supported Languages + +## JavaScript + +The main intended usage of Astal is in TypeScript with [AGS](/guide/ags/first-widgets). +It supports JSX and has a state management solution similar to web frameworks. +Only a minimal knowledge of JavaScript's syntax is needed to get started. + +:::info +The runtime is [GJS](https://gitlab.gnome.org/GNOME/gjs) and **not** nodejs +::: + +Examples: + +- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/js/simple-bar) + + +## Lua + +Similar to how there is a [TypeScript](https://github.com/Aylur/astal/tree/main/core/gjs) lib for GJS, there is also an accompanying library for [Lua](https://github.com/Aylur/astal/tree/main/core/lua). +<!--TODO: open issue and link performance issue--> +Unfortunately, I have encountered very heavy [performance issues](https://github.com/aylur/astal) with [lgi](https://github.com/lgi-devs/lgi), +and so currently I don't recommend using Lua for full desktop shells, but only for static +components that don't render child nodes dynamically, bars and panels for example. + +Examples: + +- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/lua/simple-bar) + + +## Python + +There was a WIP [library for python](https://github.com/aylur/astal/tree/feat/python), to make it behave similar to the above two +but I don't plan on finishing it, because I'm not a fan of python. +If you are interested in picking it up, feel free to open a PR. +Nonetheless you can still use python the OOP way [pygobject](https://pygobject.gnome.org/tutorials/gobject/subclassing.html) intended it. + +Examples: + +- [Starter Bar](https://github.com/Aylur/astal/tree/main/examples/py/starter-bar) + +## Vala + +Vala is a language that simply put uses C# syntax and compiles to C. +It is the language most of Astal is written in. I would still recommend +using TypeScript or Lua over Vala as they don't need a build step. + +Examples: + +- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/vala/simple-bar) + + +## C + +I don't recommend using C as it requires quite a lot of boilerplate, both for +build step and code. + +Examples: + +- TODO + +## Other languages + +There a few more that supports gobject-introspection, most notably Haskell, Rust and C++. +If you are interested and feel like contributing, PRs are welcome for bindings, and examples. diff --git a/docs/guide/libraries/apps.md b/docs/guide/libraries/apps.md new file mode 100644 index 0000000..c53daf0 --- /dev/null +++ b/docs/guide/libraries/apps.md @@ -0,0 +1,113 @@ +# Apps + +Library and CLI tool for querying and launching +applications that have a corresponding `.desktop` file. + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libjson-glib-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/apps +``` + +3. install + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +``` + +::: + +## Usage + +You can browse the [Apps reference](https://aylur.github.io/libastal/apps). + +### CLI + +```sh +astal-apps --help +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import Apps from "gi://AstalApps" + +const apps = new Apps.Apps({ + includeEntry: true, + includeExecutable: true, +}) + +for (const app of apps.fuzzy_query("spotify")) { + print(app.name) +} +``` + +```py [<i class="devicon-python-plain"></i> Python] +from gi.repository import AstalApps as Apps + +apps = Apps.Apps( + include_entry=True, + include_executable=True, +) + +for app in apps.fuzzy_query("obsidian"): + print(app.get_name()) + +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +local Apps = require("lgi").require("AstalApps") + +local apps = Apps.Apps({ + include_entry = true, + include_executable = true, +}) + +for _, app in ipairs(apps:fuzzy_query("lutris")) do + print(app.name) +end +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented, contributions are appreciated +``` + +::: + +:::info +The fuzzy query uses [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance). I am not a mathematician, but if you know how to reimplement +the logic of [fzf](https://github.com/junegunn/fzf) to make it better feel free to open PRs. +::: diff --git a/docs/guide/libraries/auth.md b/docs/guide/libraries/auth.md new file mode 100644 index 0000000..1f07a17 --- /dev/null +++ b/docs/guide/libraries/auth.md @@ -0,0 +1,118 @@ +# Auth + +Library and CLI tool for authentication using [pam](https://github.com/linux-pam/linux-pam). + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson pam gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson pam-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +# Not yet documented +``` + +::: + +::: warning On NixOS you have to add `astal-auth` to `security.pam`. +::: code-group + +```nix [configuration.nix] +{ + security.pam.services.astal-auth = {} +} +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/auth +``` + +3. install + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +``` + +::: + +## Usage + +You can browse the [Auth reference](https://aylur.github.io/libastal/auth). + +### CLI + +```sh +astal-auth --password my-password +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import Auth from "gi://AstalAuth" + +Auth.Pam.authenticate("password", (_, task) => { + try { + AstalAuth.Pam.authenticate_finish(task) + print("authentication sucessful") + } catch (error) { + print(error) + } +}) +``` + +```py [<i class="devicon-python-plain"></i> Python] +from gi.repository import AstalAuth as Auth + +def callback(_, task) -> None: + try: + Auth.Pam.authenticate_finish(task) + print("success") + except Exception as e: + print(e) + +Auth.Pam.authenticate("password", callback) +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +local Auth = require("lgi").require("AstalAuth") + +Auth.Pam.authenticate("password", function(_, task) + local status, err = Auth.Pam.authenticate_finish(task) + if err ~= nil then + print(err) + else + print("success") + end +end) +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented +``` + +::: diff --git a/docs/guide/libraries/battery.md b/docs/guide/libraries/battery.md new file mode 100644 index 0000000..b42d747 --- /dev/null +++ b/docs/guide/libraries/battery.md @@ -0,0 +1,97 @@ +# Battery + +Library and CLI tool for monitoring [upowerd](https://upower.freedesktop.org/) devices. + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libjson-glib-dev gobject-introspection +``` + +::: + +::: info +Although UPower is not a direct build dependency, +it should be self-explanatory that the daemon is required to be available at runtime. +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/battery +``` + +3. install + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +``` + +::: + +## Usage + +You can browse the [Battery reference](https://aylur.github.io/libastal/battery). + +### CLI + +```sh +astal-battery --help +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import Battery from "gi://AstalBattery" + +const battery = Battery.get_default() + +print(battery.percentage) +``` + +```py [<i class="devicon-python-plain"></i> Python] +from gi.repository import AstalBattery as Battery + +battery = Battery.get_default() + +print(battery.get_percentage()) +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +local Battery = require("lgi").require("AstalBattery") + +local battery = Battery.get_default() + +print(battery.percentage) +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented +``` + +::: diff --git a/docs/guide/libraries/bluetooth.md b/docs/guide/libraries/bluetooth.md new file mode 100644 index 0000000..04d9db2 --- /dev/null +++ b/docs/guide/libraries/bluetooth.md @@ -0,0 +1,104 @@ +# Bluetooth + +Library for monitoring [bluez](https://www.bluez.org/) over dbus. + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc valac gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac gobject-introspection +``` + +::: + +::: info +Although bluez is not a direct build dependency, +it should be self-explanatory that the daemon is required to be available at runtime. +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/bluetooth +``` + +3. install + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +``` + +::: + +## Usage + +You can browse the [Bluetooth reference](https://aylur.github.io/libastal/bluetooth). + +### CLI + +There is no CLI for this library, use the one provided by bluez. + +```sh +bluetoothctl --help +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import Bluetooth from "gi://AstalBluetooth" + +const bluetooth = Bluetooth.get_default() + +for (const device of bluetooth.get_devices()) { + print(device.name) +} +``` + +```py [<i class="devicon-python-plain"></i> Python] +from gi.repository import AstalBluetooth as Bluetooth + +bluetooth = Bluetooth.get_default() + +for device in bluetooth.get_devices(): + print(device.get_name()) +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +local Bluetooth = require("lgi").require("AstalBluetooth") + +local bluetooth = Bluetooth.get_default() + +for _, d in ipairs(bluetooth.devices) do + print(d.name) +end +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented +``` + +::: diff --git a/docs/guide/libraries/hyprland.md b/docs/guide/libraries/hyprland.md new file mode 100644 index 0000000..faf9e50 --- /dev/null +++ b/docs/guide/libraries/hyprland.md @@ -0,0 +1,97 @@ +# Hyprland + +Library and CLI tool for monitoring the [Hyprland socket](https://wiki.hyprland.org/IPC/). + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libjson-glib-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/hyprland +``` + +3. install + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +``` + +::: + +## Usage + +You can browse the [Hyprland reference](https://aylur.github.io/libastal/hyprland). + +### CLI + +```sh +astal-hyprland # starts monitoring +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import Hyprland from "gi://AstalHyprland" + +const hyprland = Hyprland.get_default() + +for (const client of hyprland.get_clients()) { + print(client.title) +} +``` + +```py [<i class="devicon-python-plain"></i> Python] +from gi.repository import AstalHyprland as Hyprland + +hyprland = Hyprland.get_default() + +for client in hyprland.get_clients(): + print(client.get_title()) +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +local Hyprland = require("lgi").require("AstalHyprland") + +local hyprland = Hyprland.get_default() + +for _, c in ipairs(hyprland.clients) do + print(c.title) +end +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented +``` + +::: diff --git a/docs/guide/libraries/mpris.md b/docs/guide/libraries/mpris.md new file mode 100644 index 0000000..dfe7956 --- /dev/null +++ b/docs/guide/libraries/mpris.md @@ -0,0 +1,100 @@ +# Mpris + +Library and CLI tool for interacting and monitoring media players +exposing an mpris interface through dbus. + +An alternative for [playerctl](https://github.com/altdesktop/playerctl) that better integrates +with astal. + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libjson-glib-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/mpris +``` + +3. install + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +``` + +::: + +## Usage + +You can browse the [Mpris reference](https://aylur.github.io/libastal/mpris). + +### CLI + +```sh +astal-mpris --help +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import Mpris from "gi://AstalMpris" + +const spotify = Mpris.Player.new("spotify") + +if (spotify.available) + print(spotify.title) +``` + +```py [<i class="devicon-python-plain"></i> Python] +from gi.repository import AstalMpris as Mpris + +spotify = Mpris.Player.new("spotify") + +if spotify.get_available(): + print(spotify.get_title()) +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +local Mpris = require("lgi").require("AstalMpris") + +local spotify = Mpris.Player.new("spotify") + +if spotify.available then + print(spotify.title) +end +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented +``` + +::: diff --git a/docs/guide/libraries/network.md b/docs/guide/libraries/network.md new file mode 100644 index 0000000..afeb5d2 --- /dev/null +++ b/docs/guide/libraries/network.md @@ -0,0 +1,94 @@ +# Network + +Wrapper library over [networkmanager](https://networkmanager.dev/) to better integrate with Astal. + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala libnm gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc valac NetworkManager-libnm-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libnm-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/network +``` + +3. install + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +``` + +::: + +## Usage + +You can browse the [Network reference](https://aylur.github.io/libastal/network). + +### CLI + +There is no CLI for this library, use the one provided by networkmanager. + +```sh +nmcli --help +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import Network from "gi://AstalNetwork" + +const network = Network.get_default() + +print(network.wifi.ssid) +``` + +```py [<i class="devicon-python-plain"></i> Python] +from gi.repository import AstalNetwork as Network + +network = Network.get_default() + +print(network.get_wifi().get_ssid()) +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +local Network = require("lgi").require("AstalNetwork") + +local network = Network.get_default() + +print(network.wifi.ssid) +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented +``` + +::: diff --git a/docs/guide/libraries/notifd.md b/docs/guide/libraries/notifd.md new file mode 100644 index 0000000..7e02149 --- /dev/null +++ b/docs/guide/libraries/notifd.md @@ -0,0 +1,106 @@ +# Notifd + +A [notification daemon](https://specifications.freedesktop.org/notification-spec/latest/) implementation as a library and CLI tool. + +## How it works + +The first instantiation of the [Notifd](https://aylur.github.io/libastal/notifd/class.Notifd.html) class will become the daemon and every subsequent instantiation will queue up to act as the daemon and will act as a client in the meantime. This means this library can be used throughout multiple processes. + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala gdk-pixbuf2 json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc valac gdk-pixbuf2-devel json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libgdk-pixbuf-2.0-dev libjson-glib-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/notifd +``` + +3. install + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +``` + +::: + +## Usage + +You can browse the [Notifd reference](https://aylur.github.io/libastal/notifd). + +### CLI + +```sh +astal-notifd --help +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import Notifd from "gi://AstalNotifd" + +const notifd = Notifd.get_default() + +notifd.connect("notified", (_, id) => { + const n = notifd.get_notification(id) + print(n.summary, n.body) +}) +``` + +```py [<i class="devicon-python-plain"></i> Python] +from gi.repository import AstalNotifd as Notifd + +notifd = Notifd.get_default() + +def on_notified(_, id): + n = notifd.get_notification(id) + print(n.get_body(), n.get_body()) + +notifd.connect("notified", on_notified) +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +local Notifd = require("lgi").require("AstalNotifd") + +local notifd = Notifd.get_default() + +notifd.on_notified = function(_, id) + local n = notifd.get_notification(id) + print(n.body, n.summary) +end +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented +``` + +::: diff --git a/docs/guide/libraries/powerprofiles.md b/docs/guide/libraries/powerprofiles.md new file mode 100644 index 0000000..8571c29 --- /dev/null +++ b/docs/guide/libraries/powerprofiles.md @@ -0,0 +1,97 @@ +# Power Profiles + +Library and CLI tool for monitoring [upowerd](https://upower.freedesktop.org/) powerprofiles. + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libjson-glib-dev gobject-introspection +``` + +::: + +::: info +Although UPower is not a direct build dependency, +it should be self-explanatory that the daemon is required to be available at runtime. +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/powerprofiles +``` + +3. install + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +``` + +::: + +## Usage + +You can browse the [PowerProfiles reference](https://aylur.github.io/libastal/powerprofiles). + +### CLI + +```sh +astal-power-profiles --help +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import PowerProfiles from "gi://AstalPowerProfiles" + +const powerprofiles = PowerProfiles.get_default() + +print(powerprofiles.activeProfile) +``` + +```py [<i class="devicon-python-plain"></i> Python] +from gi.repository import AstalPowerProfiles as PowerProfiles + +powerprofiles = PowerProfiles.get_default() + +print(powerprofiles.get_active_profile()) +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +local PowerProfiles = require("lgi").require("AstalPowerProfiles") + +local powerprofiles = PowerProfiles.get_default() + +print(powerprofiles.active_profile) +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented +``` + +::: diff --git a/docs/guide/libraries/references.md b/docs/guide/libraries/references.md new file mode 100644 index 0000000..8f2bd02 --- /dev/null +++ b/docs/guide/libraries/references.md @@ -0,0 +1,44 @@ +# References + +The references of the libraries are annotated for the C language. +Reading their documentation will vary depending on the language they are used in. + +<!--TODO: list some examples on how to read docs,--> +<!--for example the difference between C enums and gjs enums--> + +## Additional references + +### GJS + +- [gjs-docs.gnome.org](https://gjs-docs.gnome.org/): Library references annotated for GJS +- [gjs.guide](https://gjs.guide/): GJS and GObject guide + +### Python + +- [pgi-docs](https://lazka.github.io/pgi-docs/): Library references annotated for Python +- [pygobject.gnome.org](https://pygobject.gnome.org/): PyGObject reference and guide + +### Lua + +- [lua-lgi docs](https://github.com/lgi-devs/lgi/tree/master/docs): GObject bindings guide for Lua + +### Vala + +- [vala.dev](https://vala.dev/): Guide for the Vala language +- [valadoc.org](https://valadoc.org/): Library references annotated for Vala + +## Astal Libraries + +- [Astal](https://aylur.github.io/libastal): libastal the core library, which has the widgets and utilites +- [Apps](https://aylur.github.io/libastal/apps): Library and cli tool for querying applications +- [Auth](https://aylur.github.io/libastal/auth): Authentication library using PAM +- [Battery](https://aylur.github.io/libastal/battery): DBus proxy library for upower daemon +- [Bluetooth](https://aylur.github.io/libastal/bluetooth): Library to control bluez over dbus +- [Hyprland](https://aylur.github.io/libastal/hyprland): Library and cli tool for Hyprland IPC socket +- [Mpris](https://aylur.github.io/libastal/mpris): Library and cli tool for controlling media players +- [Network](https://aylur.github.io/libastal/network): NetworkManager wrapper library +- [Notifd](https://aylur.github.io/libastal/notifd): A notification daemon library and cli tool +- [PowerProfiles](https://aylur.github.io/libastal/powerprofiles): Library and cli to control upowerd powerprofiles +- [River](https://aylur.github.io/libastal/river): Library and cli tool for getting status information of the river wayland compositor +- [Tray](https://aylur.github.io/libastal/tray): A systemtray library and cli tool +- [WirePlumber](https://aylur.github.io/libastal/wireplumber): A library for audio control using wireplumber diff --git a/docs/guide/libraries/river.md b/docs/guide/libraries/river.md new file mode 100644 index 0000000..4818d0b --- /dev/null +++ b/docs/guide/libraries/river.md @@ -0,0 +1,97 @@ +# River + +Library and CLI tool for monitoring the [River Wayland Compositor](https://isaacfreund.com/software/river/). + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson libjson-glib-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/river +``` + +3. install + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +``` + +::: + +## Usage + +You can browse the [River reference](https://aylur.github.io/libastal/river). + +### CLI + +```sh +astal-river --help +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import River from "gi://AstalRiver" + +const river = River.get_default() + +for (const output of river.get_outputs()) { + print(output.name) +} +``` + +```py [<i class="devicon-python-plain"></i> Python] +from gi.repository import AstalRiver as River + +river = River.get_default() + +for output in river.get_outputs(): + print(output.get_name()) +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +local River = require("lgi").require("AstalRiver") + +local river = River.River.get_default() + +for _, o in ipairs(river.outputs) do + print(o.name) +end +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented +``` + +::: diff --git a/docs/guide/libraries/tray.md b/docs/guide/libraries/tray.md new file mode 100644 index 0000000..c8d093b --- /dev/null +++ b/docs/guide/libraries/tray.md @@ -0,0 +1,97 @@ +# Tray + +Library for managing the systemtray by implementing the [StatusNotifierItem](https://www.freedesktop.org/wiki/Specifications/StatusNotifierItem/) protocol. + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson gtk3 gobject-introspection libdbusmenu-gtk3 +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc gtk3-devel libdbusmenu-gtk3 gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson libgtk-3-dev libdbusmenu-gtk3-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/tray +``` + +3. install + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +``` + +::: + +## Usage + +You can browse the [Tray reference](https://aylur.github.io/libastal/tray). + +### CLI + +```sh +astal-tray --help +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import Tray from "gi://AstalTray" + +const tray = Tray.get_default() + +for (const item of tray.get_items()) { + print(item.title) +} +``` + +```py [<i class="devicon-python-plain"></i> Python] +from gi.repository import AstalTray as Tray + +tray = Tray.get_default() + +for item in tray.get_items(): + print(item.title) +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +local Tray = require("lgi").require("AstalTray") + +local tray = Tray.get_default() + +for _, i in ipairs(tray.items) do + print(i.title) +end +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented +``` + +::: diff --git a/docs/guide/libraries/wireplumber.md b/docs/guide/libraries/wireplumber.md new file mode 100644 index 0000000..5f1daab --- /dev/null +++ b/docs/guide/libraries/wireplumber.md @@ -0,0 +1,94 @@ +# Wire Plumber + +Wrapper library over [wireplumber](https://pipewire.pages.freedesktop.org/wireplumber/) to better integrate with Astal. + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala wireplumber gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc valac wireplumber-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +# Not yet documented +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/wireplumber +``` + +3. install + +```sh +meson setup build +meson install -C build +``` + +:::tip +Most distros recommend manual installs in `/usr/local`, +which is what `meson` defaults to. If you want to install to `/usr` +instead which most package managers do, set the `prefix` option: + +```sh +meson setup --prefix /usr build +``` + +::: + +## Usage + +You can browse the [Wireplumber reference](https://aylur.github.io/libastal/wireplumber). + +### CLI + +There is no CLI for this library, use the one provided by wireplumber. + +```sh +wpctl --help +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import Wp from "gi://AstalWp" + +const audio = Wp.get_default().audio + +print(audio.default_speaker.volume) +``` + +```py [<i class="devicon-python-plain"></i> Python] +from gi.repository import AstalWp as Wp + +audio = Wp.get_default().get_audio() + +print(audio.get_default_speaker().get_volume()) +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +local Wp = require("lgi").require("AstalWp") + +local audio = Wp.get_default().audio + +print(audio.default_speaker.volume) +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented +``` + +::: |