diff options
Diffstat (limited to 'docs/guide/ags')
| -rw-r--r-- | docs/guide/ags/cli-app.md | 167 | ||||
| -rw-r--r-- | docs/guide/ags/faq.md | 379 | ||||
| -rw-r--r-- | docs/guide/ags/first-widgets.md | 401 | ||||
| -rw-r--r-- | docs/guide/ags/installation.md | 65 | ||||
| -rw-r--r-- | docs/guide/ags/theming.md | 161 | ||||
| -rw-r--r-- | docs/guide/ags/utilities.md | 174 | ||||
| -rw-r--r-- | docs/guide/ags/variable.md | 141 | ||||
| -rw-r--r-- | docs/guide/ags/widget.md | 227 |
8 files changed, 0 insertions, 1715 deletions
diff --git a/docs/guide/ags/cli-app.md b/docs/guide/ags/cli-app.md deleted file mode 100644 index ec6d174..0000000 --- a/docs/guide/ags/cli-app.md +++ /dev/null @@ -1,167 +0,0 @@ -# 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 -``` - -## Toggling Windows by their name - -In order for AGS to know about your windows, you have to register them. -You can do this by specifying a **unique** `name` and calling `App.add_window` - -```tsx {4} -import { App } from "astal" - -function Bar() { - return <window name="Bar" setup={self => App.add_window(self)}> - <box /> - </window> -} -``` - -You can also invoke `App.add_window` by simply passing the `App` to the `application` prop. - -```tsx {4} -import { App } from "astal" - -function Bar() { - return <window name="Bar" application={App}> - <box /> - </window> -} -``` - -:::warning -When assigning the `application` prop make sure `name` comes before. -Props are set sequentially and if name is applied after application it won't work. -::: - -```sh -ags -t Bar -``` - -## 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 deleted file mode 100644 index cb5d609..0000000 --- a/docs/guide/ags/faq.md +++ /dev/null @@ -1,379 +0,0 @@ -# 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> -``` - -## Avoiding unnecessary re-rendering - -As mentioned before, any object can be bound that implements the `Subscribable` interface. - -```ts -interface Subscribable<T = unknown> { - subscribe(callback: (value: T) => void): () => void - get(): T -} -``` - -This can be used to our advantage to create a reactive `Map` object. - -```ts -import { type Subscribable } from "astal/binding" -import { Gtk } from "astal" - -export class VarMap<K, T = Gtk.Widget> implements Subscribable { - #subs = new Set<(v: Array<[K, T]>) => void>() - #map: Map<K, T> - - #notifiy() { - const value = this.get() - for (const sub of this.#subs) { - sub(value) - } - } - - #delete(key: K) { - const v = this.#map.get(key) - - if (v instanceof Gtk.Widget) { - v.destroy() - } - - this.#map.delete(key) - } - - constructor(initial?: Iterable<[K, T]>) { - this.#map = new Map(initial) - } - - add(key: K, value: T) { - this.#delete(key) - this.#map.set(key, value) - this.#notifiy() - } - - delete(key: K) { - this.#delete(key) - this.#notifiy() - } - - get() { - return [...this.#map.entries()] - } - - subscribe(callback: (v: Array<[K, T]>) => void) { - this.#subs.add(callback) - return () => this.#subs.delete(callback) - } -} -``` - -And this `VarMap<key, Widget>` can be used as an alternative to `Variable<Array<Widget>>`. - -```tsx -function MappedBox() { - const map = new VarMap([ - [1, <MyWidget id={id} />] - [2, <MyWidget id={id} />] - ]) - - const conns = [ - gobject.connect("added", (_, id) => map.set(id, MyWidget({ id }))), - gobject.connect("removed", (_, id) => map.delete(id, MyWidget({ id }))), - ] - - return <box onDestroy={() => conns.map(id => gobject.disconnect(id))}> - {bind(map).as(arr => arr.sort(([a], [b]) => a - b).map(([,w]) => w))} - </box> -} -``` - -## Is there a way to limit the width/height of a widget? - -Unfortunately not. You can set a minimum size with `min-width` and `min-heigth` css attributes, -but you can not set max size. diff --git a/docs/guide/ags/first-widgets.md b/docs/guide/ags/first-widgets.md deleted file mode 100644 index c4c4436..0000000 --- a/docs/guide/ags/first-widgets.md +++ /dev/null @@ -1,401 +0,0 @@ -# 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 and deletion](/guide/ags/faq#avoiding-unnecessary-re-rendering) -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 deleted file mode 100644 index 0adcf68..0000000 --- a/docs/guide/ags/installation.md +++ /dev/null @@ -1,65 +0,0 @@ -# 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 deleted file mode 100644 index cb0ebff..0000000 --- a/docs/guide/ags/theming.md +++ /dev/null @@ -1,161 +0,0 @@ -# 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 [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu dart-sass -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -npm install -g sass # not packaged on Fedora -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -npm install -g sass # not packaged on Ubuntu -``` - -::: - -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 deleted file mode 100644 index 42589d3..0000000 --- a/docs/guide/ags/utilities.md +++ /dev/null @@ -1,174 +0,0 @@ -# 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 deleted file mode 100644 index 96e8d38..0000000 --- a/docs/guide/ags/variable.md +++ /dev/null @@ -1,141 +0,0 @@ -# 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 deleted file mode 100644 index 1fe755f..0000000 --- a/docs/guide/ags/widget.md +++ /dev/null @@ -1,227 +0,0 @@ -# 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) |