diff options
Diffstat (limited to 'docs/guide')
| -rw-r--r-- | docs/guide/lua/examples.md | 4 | ||||
| -rw-r--r-- | docs/guide/lua/installation.md | 2 | ||||
| -rw-r--r-- | docs/guide/lua/widget.md | 8 | ||||
| -rw-r--r-- | docs/guide/typescript/examples.md | 14 | ||||
| -rw-r--r-- | docs/guide/typescript/faq.md | 19 | ||||
| -rw-r--r-- | docs/guide/typescript/first-widgets.md | 85 | ||||
| -rw-r--r-- | docs/guide/typescript/gobject.md | 2 |
7 files changed, 95 insertions, 39 deletions
diff --git a/docs/guide/lua/examples.md b/docs/guide/lua/examples.md new file mode 100644 index 0000000..be46b6e --- /dev/null +++ b/docs/guide/lua/examples.md @@ -0,0 +1,4 @@ +# Lua examples + +## [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/lua/simple-bar) + diff --git a/docs/guide/lua/installation.md b/docs/guide/lua/installation.md index b99d8df..f647ed7 100644 --- a/docs/guide/lua/installation.md +++ b/docs/guide/lua/installation.md @@ -9,7 +9,7 @@ Read more about it on the [nix page](../getting-started/nix) ## Arch ```sh -yay -S lua-libastal-git +yay -S libastal-lua-git ``` ## From Source diff --git a/docs/guide/lua/widget.md b/docs/guide/lua/widget.md index d9f99fa..593628e 100644 --- a/docs/guide/lua/widget.md +++ b/docs/guide/lua/widget.md @@ -139,18 +139,18 @@ These widgets are available by default in Lua. - Button: [Astal.Button](https://aylur.github.io/libastal/astal3/class.Button.html) - CenterBox: [Astal.CenterBox](https://aylur.github.io/libastal/astal3/class.CenterBox.html) - CircularProgress: [Astal.CircularProgress](https://aylur.github.io/libastal/astal3/class.CircularProgress.html) -- DrawingArea: [Gtk.DrawingArea](https://docs.gtk.org/gtk3/astal3/class.DrawingArea.html) -- Entry: [Gtk.Entry](https://docs.gtk.org/gtk3/astal3/class.Entry.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/astal3/class.EventBox.html) - Icon: [Astal.Icon](https://aylur.github.io/libastal/astal3/class.Icon.html) - Label: [Astal.Label](https://aylur.github.io/libastal/astal3/class.Label.html) - Levelbar: [Astal.LevelBar](https://aylur.github.io/libastal/astal3/class.LevelBar.html) - Overlay: [Astal.Overlay](https://aylur.github.io/libastal/astal3/class.Overlay.html) -- Revealer: [Gtk.Revealer](https://docs.gtk.org/gtk3/astal3/class.Revealer.html) +- Revealer: [Gtk.Revealer](https://docs.gtk.org/gtk3/class.Revealer.html) - Scrollable: [Astal.Scrollable](https://aylur.github.io/libastal/astal3/class.Scrollable.html) - Slider: [Astal.Slider](https://aylur.github.io/libastal/astal3/class.Slider.html) - Stack: [Astal.Stack](https://aylur.github.io/libastal/astal3/class.Stack.html) -- Switch: [Gtk.Switch](https://docs.gtk.org/gtk3/astal3/class.Switch.html) +- Switch: [Gtk.Switch](https://docs.gtk.org/gtk3/class.Switch.html) - Window: [Astal.Window](https://aylur.github.io/libastal/astal3/class.Window.html) ## Gtk4 diff --git a/docs/guide/typescript/examples.md b/docs/guide/typescript/examples.md new file mode 100644 index 0000000..ec51e89 --- /dev/null +++ b/docs/guide/typescript/examples.md @@ -0,0 +1,14 @@ +# TypeScript Examples + +## Gtk3 + +### [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/js/simple-bar) + + +### [Notification Popups](https://github.com/Aylur/astal/tree/main/examples/js/notifications) + +### [Applauncher](https://github.com/Aylur/astal/tree/main/examples/js/applauncher) + + +### [Media Player](https://github.com/Aylur/astal/tree/main/examples/js/media-player) + diff --git a/docs/guide/typescript/faq.md b/docs/guide/typescript/faq.md index a151099..4ee616b 100644 --- a/docs/guide/typescript/faq.md +++ b/docs/guide/typescript/faq.md @@ -92,7 +92,7 @@ printerr("print this line to stderr") ## Populate the global scope with frequently accessed variables -It might be annoying to always import Gtk only for `Gtk.Align` enums. +It might be annoying to always import Gtk only for the `Gtk.Align` enum. :::code-group @@ -118,7 +118,7 @@ Object.assign(globalThis, { :::code-group -```tsx [Bar.tsx] +```tsx [Bar.tsx] {3} export default function Bar() { return <window> <box halign={START} /> @@ -131,11 +131,13 @@ export default function Bar() { :::code-group ```ts [app.ts] -import "./globals" +import "./globals" // don't forget to import it first // [!code ++] import Bar from "./Bar" App.start({ - main: Bar + main() { + Bar() + } }) ``` @@ -197,11 +199,14 @@ These happen when accessing list type properties. Gjs fails to correctly bind import Notifd from "gi://AstalNotifd" const notifd = Notifd.get_default() -notifd.notifications // ❌ // [!code error] - -notifd.get_notifications() // ✅ +notifd.notifications // [!code --] +notifd.get_notifications() // [!code ++] ``` +:::tip +Open up an issue/PR to add a [workaround](https://github.com/Aylur/astal/blob/main/lang/gjs/src/overrides.ts). +::: + ## How to create regular floating windows Use `Gtk.Window` with [Widget.astalify](/guide/typescript/widget#how-to-use-non-builtin-gtk-widgets). diff --git a/docs/guide/typescript/first-widgets.md b/docs/guide/typescript/first-widgets.md index a467382..77b2f61 100644 --- a/docs/guide/typescript/first-widgets.md +++ b/docs/guide/typescript/first-widgets.md @@ -275,7 +275,7 @@ function Counter() { <label label={bind(count).as(num => num.toString())} /> <button onClicked={increment}> Click to increment - <button> + </button> </box> } ``` @@ -354,42 +354,75 @@ inner state of widgets that does not need to be recreated. In this case you can create a [custom reactive structure](./binding#example-custom-subscribable) ::: -When there is at least one `Binding` passed as a child, the `children` -parameter will always be a flattened `Binding<Array<JSX.Element>>`. -When there is a single `Binding` passed as a child, the `child` parameter will -be a `Binding<JSX.Element>` or a flattened `Binding<Array<JSX.Element>>`. +# How children are passed + +Here is full list of how children and bound children can be passed to custom widgets. ```tsx -import { type Binding } from "astal" +import Binding from "astal/binding" -function MyContainer({ children }: { - children?: Binding<Array<JSX.Element>> -}) { - // children is a Binding over an Array of widgets -} +function Parent(props: { + child?: JSX.Element | Binding<JSX.Element> | Binding<Array<JSX.Element>> + children?: Array<JSX.Element> | Binding<Array<JSX.Element>> +}) -return <MyContainer> - <box /> - {num(n => range(n).map(i => ( - <button> - {i.toString()} - <button/> - )))} - [ - [ - <button /> - ] - <button /> - ] -</MyContainer> +// { child: JSX.Element } +<Parent> + <child /> +</Parent> + +// { children: Array<JSX.Element> } +<Parent> + <child /> + <child /> +</Parent> + +// { child: Binding<JSX.Element> } +<Parent> + {variable(c => ( + <child /> + ))} +</Parent> + +// { child: Binding<Array<JSX.Element>> } +<Parent> + {variable(c => ( + <child /> + <child /> + ))} +</Parent> + +// { children: Binding<Array<JSX.Element>> } +<Parent> + <child /> + {variable(c => ( + <child /> + ))} +</Parent> + + +// { children: Binding<Array<JSX.Element>> } +<Parent> + <child /> + {variable(c => ( + <child /> + <child /> + ))} +</Parent> ``` +:::tip +If you have a widget where you pass widgets in various ways, you can +wrap `child` in `children` in a [`Subscribable`](./faq#custom-widgets-with-bindable-properties) and handle all cases +as if they were bindings. +::: + :::info You can pass the followings as children: - widgets - deeply nested arrays of widgets -- bindings 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 diff --git a/docs/guide/typescript/gobject.md b/docs/guide/typescript/gobject.md index f7f001d..4e40845 100644 --- a/docs/guide/typescript/gobject.md +++ b/docs/guide/typescript/gobject.md @@ -74,7 +74,7 @@ class MyObj extends GObject.Object { declare myProp: string constructor() { - super({ myProp: "default-value" }) + super({ myProp: "default-value" } as any) } } ``` |