diff options
| -rw-r--r-- | docs/astro.config.mjs | 33 | ||||
| -rw-r--r-- | docs/src/content/docs/ags/cli-app.md | 2 | ||||
| -rw-r--r-- | docs/src/content/docs/ags/libraries.md | 8 | ||||
| -rw-r--r-- | docs/src/content/docs/ags/theming.md | 2 | ||||
| -rw-r--r-- | docs/src/content/docs/ags/variable.md | 2 | ||||
| -rw-r--r-- | docs/src/content/docs/ags/widget.md | 52 | ||||
| -rw-r--r-- | docs/src/content/docs/getting-started/installation.mdx | 63 | ||||
| -rw-r--r-- | docs/src/content/docs/getting-started/introduction.md | 4 | ||||
| -rw-r--r-- | docs/src/content/docs/index.mdx | 2 | ||||
| -rw-r--r-- | docs/src/content/docs/libraries/overview.md | 8 | ||||
| -rw-r--r-- | docs/src/content/docs/libraries/references.md | 49 |
11 files changed, 154 insertions, 71 deletions
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 080105b..cbbe24f 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -1,12 +1,6 @@ import { defineConfig } from "astro/config" import starlight from "@astrojs/starlight" -const directories = [ - ["Getting Started", "/getting-started"], - ["AGS", "/ags"], - ["Libraries", "/libraries"], -] - export default defineConfig({ site: "https://aylur.github.io", base: "astal", @@ -22,10 +16,29 @@ export default defineConfig({ }, customCss: ["./src/style.css"], favicon: "./favicon.ico", - sidebar: directories.map(([label, directory]) => ({ - label, - autogenerate: { directory }, - })), + sidebar: [ + { label: "Getting Started", autogenerate: { directory: "/getting-started" } }, + { label: "AGS", autogenerate: { directory: "/ags" } }, + { + label: "Libraries", + items: [ + "libraries/references", + { label: "Astal", link: "/reference" }, + { label: "Apps", link: "/reference/apps" }, + { label: "Auth", link: "/reference/auth" }, + { label: "Battery", link: "/reference/battery" }, + { label: "Bluetooth", link: "/reference/bluetooth" }, + { label: "Hyprland", link: "/reference/hyprland" }, + { label: "Mpris", link: "/reference/mpris" }, + { label: "Network", link: "/reference/network" }, + { label: "Notifd", link: "/reference/notifd" }, + { label: "PowerProfiles", link: "/reference/powerprofiles" }, + { label: "River", link: "/reference/river" }, + { label: "Tray", link: "/reference/tray" }, + { label: "WirePlumber", link: "/reference/wireplumber" }, + ], + } + ] }), ], }) diff --git a/docs/src/content/docs/ags/cli-app.md b/docs/src/content/docs/ags/cli-app.md index 6b9d4c3..3365505 100644 --- a/docs/src/content/docs/ags/cli-app.md +++ b/docs/src/content/docs/ags/cli-app.md @@ -5,7 +5,7 @@ sidebar: order: 3 --- -`App` is a singleton **instance** of [Astal.Application](/libastal/class.Application.html). +`App` is a singleton **instance** of [Astal.Application](/astal/reference/class.Application.html). ```tsx import { App } from "astal" diff --git a/docs/src/content/docs/ags/libraries.md b/docs/src/content/docs/ags/libraries.md deleted file mode 100644 index e594de8..0000000 --- a/docs/src/content/docs/ags/libraries.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Libraries -description: How to use Astal libraries -sidebar: - order: 7 ---- - -## TODO: diff --git a/docs/src/content/docs/ags/theming.md b/docs/src/content/docs/ags/theming.md index 5c930ea..ef2fe92 100644 --- a/docs/src/content/docs/ags/theming.md +++ b/docs/src/content/docs/ags/theming.md @@ -79,7 +79,7 @@ App.reset_css() // reset if need ``` :::caution -`App.apply_css` will apply over other stylesheets applied before. +`App.apply_css` will apply on top of other stylesheets applied before. You can reset stylesheets with `App.resetCss` ::: diff --git a/docs/src/content/docs/ags/variable.md b/docs/src/content/docs/ags/variable.md index 82ea856..d6023fe 100644 --- a/docs/src/content/docs/ags/variable.md +++ b/docs/src/content/docs/ags/variable.md @@ -37,7 +37,7 @@ Widget.Label({ :::caution Make sure to make the transform functions pure. The `.get()` function can be called -anytime by `astal` especially when `deriving`. +anytime by `astal` especially when `deriving`, so make sure there are no sideeffects. ::: ## Composing variables diff --git a/docs/src/content/docs/ags/widget.md b/docs/src/content/docs/ags/widget.md index 905c2a0..8e47490 100644 --- a/docs/src/content/docs/ags/widget.md +++ b/docs/src/content/docs/ags/widget.md @@ -16,7 +16,7 @@ These are properties that Astal.js additionally adds to Gtk.Widgets To have a full list of available properties, reference the documentation of the widget. -- [Astal widgets](/libastal/#classes) +- [Astal widgets](/astal/reference#classes) - [Gtk widgets](https://docs.gtk.org/gtk3/#classes) You can check the [source code](https://github.com/aylur/astal/blob/main/gjs/src/widgets.ts) to have a full list of builtin widgets. @@ -97,28 +97,54 @@ function MyWidget() { ## 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 { astalify, Gtk } from "astal" +import { Widget, Gtk } from "astal" // define its props, constructor and type -export type ColorButtonProps = Widget.ConstructProps<Gtk.ColorButton, Gtk.ColorButton.ConstructorProps> -export const ColorButton = Widget.astalify<typeof Gtk.ColorButton, ColorButtonProps, "ColorButton">(Gtk.ColorButton) +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) { - - } + function setup(button: ColorButton) {} return <ColorButton setup={setup} useAlpha - rgba={new Gdk.RGBA({ - red: 1, - green: 0, - blue: 0, - alpha: 0.5, - })} + rgba={ + new Gdk.RGBA({ + red: 1, + green: 0, + blue: 0, + alpha: 0.5, + }) + } + onColorSet={(self) => { + console.log(self.rgba) + }} /> } ``` + +:::note +Signal properties have to be annotated manually for TypeScript. +You can reference [Gtk3](https://gjs-docs.gnome.org/gtk30~3.0/) +and [Astal](/astal/reference#classes) for available signals. +::: diff --git a/docs/src/content/docs/getting-started/installation.mdx b/docs/src/content/docs/getting-started/installation.mdx index c1f4060..086ff5b 100644 --- a/docs/src/content/docs/getting-started/installation.mdx +++ b/docs/src/content/docs/getting-started/installation.mdx @@ -2,7 +2,7 @@ title: Installation description: How to install Astal sidebar: - order: 1 + order: 1 --- import { Tabs, TabItem } from "@astrojs/starlight/components" @@ -32,61 +32,72 @@ yay -S libastal-meta ``` </TabItem> - <TabItem label="AGS"> - -```bash -yay -S aylurs-gtk-shell-git -``` - - </TabItem> </Tabs> -## From Source +## Bulding core from source + +1. Clone the repo ```bash -git clone https://github.com/Aylur/Astal.git -cd Astal +git clone https://github.com/aylur/astal.git +cd astal/core ``` +2. Install the following dependencies + <Tabs> <TabItem label="Fedora"> ```bash -sudo dnf install meson - -meson setup --prefix /usr build -meson install -C build +sudo dnf install meson gcc valac gtk3-devel gtk-layer-shell-devel ``` </TabItem> <TabItem label="Arch"> ```bash -sudo pacman -Syu meson - -arch-meson build -meson install -C build +sudo pacman -Syu meson vala gtk3 gtk-layer-shell gobject-introspection ``` </TabItem> <TabItem label="Alpine"> ```bash -sudo apk add meson - -meson setup --prefix /usr build -meson install -C build +sudo apk add meson g++ vala gtk+3.0-dev gtk-layer-shell-dev gobject-introspection-dev ``` </TabItem> <TabItem label="Ubuntu"> ```bash -sudo apt install meson +sudo apt install meson valac libgtk3-dev libgtk-layer-shell-dev gobject-introspection +``` -meson setup --prefix /usr build -meson install -C build + </TabItem> + <TabItem label="openSUSE"> + +```bash +sudo zypper install gcc meson vala gtk3-devel gtk-layer-shell-devel gobject-introspection-devel ``` </TabItem> </Tabs> + +3. Build and install with `meson` + +```bash +meson setup build +meson install -C build +``` + +:::note +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, you set the `prefix` option: + +```bash +meson setup --prefix /usr build +meson install -C build +``` + +::: diff --git a/docs/src/content/docs/getting-started/introduction.md b/docs/src/content/docs/getting-started/introduction.md index cb46b29..f215707 100644 --- a/docs/src/content/docs/getting-started/introduction.md +++ b/docs/src/content/docs/getting-started/introduction.md @@ -8,8 +8,8 @@ sidebar: ## 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](/libastal) has some Gtk widgets that come packaged, -the most important one is the [Window](/libastal/class.Window.html) which is the main toplevel component using [gtk-layer-shell](https://github.com/wmww/gtk-layer-shell). +The core library [libastal](/astal/reference) has some Gtk widgets that come packaged, +the most important one is the [Window](/astal/reference/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. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 602662d..5c292de 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -14,7 +14,7 @@ hero: icon: right-arrow variant: primary - text: Reference - link: /astal/reference/references + link: /astal/libraries/references icon: open-book variant: secondary - text: View on GitHub diff --git a/docs/src/content/docs/libraries/overview.md b/docs/src/content/docs/libraries/overview.md deleted file mode 100644 index e39d746..0000000 --- a/docs/src/content/docs/libraries/overview.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Libraries -description: Overview of incuded Astal Libraries -sidebar: - order: 0 ---- - -## Libs diff --git a/docs/src/content/docs/libraries/references.md b/docs/src/content/docs/libraries/references.md new file mode 100644 index 0000000..f7b597d --- /dev/null +++ b/docs/src/content/docs/libraries/references.md @@ -0,0 +1,49 @@ +--- +title: References +description: References of libraries +sidebar: + order: 0 +--- + +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](/reference): libastal the core library, which has the widgets and utilites +- [Apps](/reference/apps): Library and cli tool for querying applications +- [Auth](/reference/auth): Authentication library using PAM +- [Battery](/reference/battery): DBus proxy library for upower daemon +- [Bluetooth](/reference/bluetooth): Library to control bluez over dbus +- [Hyprland](/reference/hyprland): Library and cli tool for Hyprland IPC socket +- [Mpris](/reference/mpris): Library and cli tool for controlling media players +- [Network](/reference/network): NetworkManager wrapper library +- [Notifd](/reference/notifd): A notification daemon library and cli tool +- [PowerProfiles](/reference/powerprofiles): Library and cli to control upowerd powerprofiles +- [River](/reference/river): Library and cli tool for getting status information of the river wayland compositor +- [Tray](/reference/tray): A systemtray library and cli tool +- [WirePlumber](/reference/wireplumber): A library for audio control using wireplumber |