zoriya/astal
1
0
Fork 0
mirror of https://github.com/zoriya/astal.git synced 2026-05-28 08:23:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: reference links

Browse Source
This commit is contained in:
Aylur
2024-09-02 16:29:44 +00:00
parent bf639c4e0b
commit 8071a20035
11 changed files with 154 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/astro.config.mjs
+23 -10
View File
@@ -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" },
],
}
]
}),
],
})
docs/src/content/docs/ags/cli-app.md
+1 -1
View File
@@ -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"
docs/src/content/docs/ags/libraries.md
-8
View File
@@ -1,8 +0,0 @@
---
title: Libraries
description: How to use Astal libraries
sidebar:
order: 7
---
## TODO:
docs/src/content/docs/ags/theming.md
+1 -1
View File
@@ -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`
:::
docs/src/content/docs/ags/variable.md
+1 -1
View File
@@ -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
docs/src/content/docs/ags/widget.md
+39 -13
View File
@@ -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.
:::
docs/src/content/docs/getting-started/installation.mdx
+37 -26
View File
@@ -2,7 +2,7 @@
title: Installation
description: How to install Astal
sidebar:
order: 1
order: 1
---
import { Tabs, TabItem } from "@astrojs/starlight/components"
@@ -29,64 +29,75 @@ yay -S libastal-git
```bash
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
```
:::
docs/src/content/docs/getting-started/introduction.md
+2 -2
View File
@@ -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.
docs/src/content/docs/index.mdx
+1 -1
View File
@@ -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
docs/src/content/docs/libraries/overview.md
-8
View File
@@ -1,8 +0,0 @@
---
title: Libraries
description: Overview of incuded Astal Libraries
sidebar:
order: 0
---
## Libs
docs/src/content/docs/libraries/references.md
+49
View File
@@ -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