From 65654282a98cb0590d498e4ed9c924f97646f1dc Mon Sep 17 00:00:00 2001 From: Aylur Date: Wed, 25 Sep 2024 23:22:01 +0000 Subject: docs: restructure --- docs/guide/libraries/apps.md | 113 ++++++++++++++++++++++++++++++++ docs/guide/libraries/auth.md | 118 ++++++++++++++++++++++++++++++++++ docs/guide/libraries/battery.md | 97 ++++++++++++++++++++++++++++ docs/guide/libraries/bluetooth.md | 104 ++++++++++++++++++++++++++++++ docs/guide/libraries/hyprland.md | 97 ++++++++++++++++++++++++++++ docs/guide/libraries/mpris.md | 100 ++++++++++++++++++++++++++++ docs/guide/libraries/network.md | 94 +++++++++++++++++++++++++++ docs/guide/libraries/notifd.md | 106 ++++++++++++++++++++++++++++++ docs/guide/libraries/powerprofiles.md | 97 ++++++++++++++++++++++++++++ docs/guide/libraries/references.md | 44 +++++++++++++ docs/guide/libraries/river.md | 97 ++++++++++++++++++++++++++++ docs/guide/libraries/tray.md | 97 ++++++++++++++++++++++++++++ docs/guide/libraries/wireplumber.md | 94 +++++++++++++++++++++++++++ 13 files changed, 1258 insertions(+) create mode 100644 docs/guide/libraries/apps.md create mode 100644 docs/guide/libraries/auth.md create mode 100644 docs/guide/libraries/battery.md create mode 100644 docs/guide/libraries/bluetooth.md create mode 100644 docs/guide/libraries/hyprland.md create mode 100644 docs/guide/libraries/mpris.md create mode 100644 docs/guide/libraries/network.md create mode 100644 docs/guide/libraries/notifd.md create mode 100644 docs/guide/libraries/powerprofiles.md create mode 100644 docs/guide/libraries/references.md create mode 100644 docs/guide/libraries/river.md create mode 100644 docs/guide/libraries/tray.md create mode 100644 docs/guide/libraries/wireplumber.md (limited to 'docs/guide/libraries') 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 [ Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [ Fedora] +sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel +``` + +```sh [ 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 [ 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 [ 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 [ 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 [ 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 [ Arch] +sudo pacman -Syu meson pam gobject-introspection +``` + +```sh [ Fedora] +sudo dnf install meson pam-devel gobject-introspection-devel +``` + +```sh [ 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 [ 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 [ 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 [ 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 [ 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 [ Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [ Fedora] +sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel +``` + +```sh [ 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 [ JavaScript] +import Battery from "gi://AstalBattery" + +const battery = Battery.get_default() + +print(battery.percentage) +``` + +```py [ Python] +from gi.repository import AstalBattery as Battery + +battery = Battery.get_default() + +print(battery.get_percentage()) +``` + +```lua [ Lua] +local Battery = require("lgi").require("AstalBattery") + +local battery = Battery.get_default() + +print(battery.percentage) +``` + +```vala [ 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 [ Arch] +sudo pacman -Syu meson vala gobject-introspection +``` + +```sh [ Fedora] +sudo dnf install meson gcc valac gobject-introspection-devel +``` + +```sh [ 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 [ JavaScript] +import Bluetooth from "gi://AstalBluetooth" + +const bluetooth = Bluetooth.get_default() + +for (const device of bluetooth.get_devices()) { + print(device.name) +} +``` + +```py [ Python] +from gi.repository import AstalBluetooth as Bluetooth + +bluetooth = Bluetooth.get_default() + +for device in bluetooth.get_devices(): + print(device.get_name()) +``` + +```lua [ Lua] +local Bluetooth = require("lgi").require("AstalBluetooth") + +local bluetooth = Bluetooth.get_default() + +for _, d in ipairs(bluetooth.devices) do + print(d.name) +end +``` + +```vala [ 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 [ Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [ Fedora] +sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel +``` + +```sh [ 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 [ JavaScript] +import Hyprland from "gi://AstalHyprland" + +const hyprland = Hyprland.get_default() + +for (const client of hyprland.get_clients()) { + print(client.title) +} +``` + +```py [ Python] +from gi.repository import AstalHyprland as Hyprland + +hyprland = Hyprland.get_default() + +for client in hyprland.get_clients(): + print(client.get_title()) +``` + +```lua [ Lua] +local Hyprland = require("lgi").require("AstalHyprland") + +local hyprland = Hyprland.get_default() + +for _, c in ipairs(hyprland.clients) do + print(c.title) +end +``` + +```vala [ 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 [ Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [ Fedora] +sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel +``` + +```sh [ 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 [ JavaScript] +import Mpris from "gi://AstalMpris" + +const spotify = Mpris.Player.new("spotify") + +if (spotify.available) + print(spotify.title) +``` + +```py [ Python] +from gi.repository import AstalMpris as Mpris + +spotify = Mpris.Player.new("spotify") + +if spotify.get_available(): + print(spotify.get_title()) +``` + +```lua [ Lua] +local Mpris = require("lgi").require("AstalMpris") + +local spotify = Mpris.Player.new("spotify") + +if spotify.available then + print(spotify.title) +end +``` + +```vala [ 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 [ Arch] +sudo pacman -Syu meson vala libnm gobject-introspection +``` + +```sh [ Fedora] +sudo dnf install meson gcc valac NetworkManager-libnm-devel gobject-introspection-devel +``` + +```sh [ 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 [ JavaScript] +import Network from "gi://AstalNetwork" + +const network = Network.get_default() + +print(network.wifi.ssid) +``` + +```py [ Python] +from gi.repository import AstalNetwork as Network + +network = Network.get_default() + +print(network.get_wifi().get_ssid()) +``` + +```lua [ Lua] +local Network = require("lgi").require("AstalNetwork") + +local network = Network.get_default() + +print(network.wifi.ssid) +``` + +```vala [ 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 [ Arch] +sudo pacman -Syu meson vala gdk-pixbuf2 json-glib gobject-introspection +``` + +```sh [ Fedora] +sudo dnf install meson gcc valac gdk-pixbuf2-devel json-glib-devel gobject-introspection-devel +``` + +```sh [ 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 [ 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 [ 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 [ 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 [ 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 [ Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [ Fedora] +sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel +``` + +```sh [ 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 [ JavaScript] +import PowerProfiles from "gi://AstalPowerProfiles" + +const powerprofiles = PowerProfiles.get_default() + +print(powerprofiles.activeProfile) +``` + +```py [ Python] +from gi.repository import AstalPowerProfiles as PowerProfiles + +powerprofiles = PowerProfiles.get_default() + +print(powerprofiles.get_active_profile()) +``` + +```lua [ Lua] +local PowerProfiles = require("lgi").require("AstalPowerProfiles") + +local powerprofiles = PowerProfiles.get_default() + +print(powerprofiles.active_profile) +``` + +```vala [ 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. + + + + +## 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 [ Arch] +sudo pacman -Syu meson json-glib gobject-introspection +``` + +```sh [ Fedora] +sudo dnf install meson gcc json-glib-devel gobject-introspection-devel +``` + +```sh [ 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 [ JavaScript] +import River from "gi://AstalRiver" + +const river = River.get_default() + +for (const output of river.get_outputs()) { + print(output.name) +} +``` + +```py [ Python] +from gi.repository import AstalRiver as River + +river = River.get_default() + +for output in river.get_outputs(): + print(output.get_name()) +``` + +```lua [ 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 [ 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 [ Arch] +sudo pacman -Syu meson gtk3 gobject-introspection libdbusmenu-gtk3 +``` + +```sh [ Fedora] +sudo dnf install meson gcc gtk3-devel libdbusmenu-gtk3 gobject-introspection-devel +``` + +```sh [ 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 [ JavaScript] +import Tray from "gi://AstalTray" + +const tray = Tray.get_default() + +for (const item of tray.get_items()) { + print(item.title) +} +``` + +```py [ Python] +from gi.repository import AstalTray as Tray + +tray = Tray.get_default() + +for item in tray.get_items(): + print(item.title) +``` + +```lua [ Lua] +local Tray = require("lgi").require("AstalTray") + +local tray = Tray.get_default() + +for _, i in ipairs(tray.items) do + print(i.title) +end +``` + +```vala [ 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 [ Arch] +sudo pacman -Syu meson vala wireplumber gobject-introspection +``` + +```sh [ Fedora] +sudo dnf install meson gcc valac wireplumber-devel gobject-introspection-devel +``` + +```sh [ 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 [ JavaScript] +import Wp from "gi://AstalWp" + +const audio = Wp.get_default().audio + +print(audio.default_speaker.volume) +``` + +```py [ Python] +from gi.repository import AstalWp as Wp + +audio = Wp.get_default().get_audio() + +print(audio.get_default_speaker().get_volume()) +``` + +```lua [ Lua] +local Wp = require("lgi").require("AstalWp") + +local audio = Wp.get_default().audio + +print(audio.default_speaker.volume) +``` + +```vala [ Vala] +// Not yet documented +``` + +::: -- cgit v1.2.3