From ede8890a08b3fbbb1f6df3b8c277ab6424d1befd Mon Sep 17 00:00:00 2001 From: Aylur Date: Tue, 15 Oct 2024 01:22:24 +0000 Subject: docs: better explain ags --- docs/guide/typescript/widget.md | 214 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 docs/guide/typescript/widget.md (limited to 'docs/guide/typescript/widget.md') diff --git a/docs/guide/typescript/widget.md b/docs/guide/typescript/widget.md new file mode 100644 index 0000000..03ba9ea --- /dev/null +++ b/docs/guide/typescript/widget.md @@ -0,0 +1,214 @@ +# Widget + +## Gtk3 + +### Additional widget properties + +These are properties that Astal 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. + +- [Astal3 widgets](https://aylur.github.io/libastal/astal3/index.html#classes) +- [Gtk widgets](https://docs.gtk.org/gtk3/#classes) + +### Additional widget methods + +#### setup + +`setup` is a convenience prop to remove the need to predefine widgets +before returning them in cases where a reference is needed. + +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 +} +``` + +#### hook + +Shorthand for connection and disconnecting to [Subscribable and Connectable](./binding#subscribable-and-connectable-interface) objects. + +without `hook` + +```tsx +function MyWidget() { + const id = gobject.connect("signal", callback) + const unsub = variable.subscribe(callback) + + return { + gobject.disconnect(id) + unsub() + }} + /> +} +``` + +with `hook` + +```tsx +function MyWidget() { + return { + self.hook(gobject, "signal", callback) + self.hook(variable, callback) + }} + /> +} +``` + +#### toggleClassName + +Toggle classNames based on a condition + +```tsx +function MyWidget() { + return { + self.toggleClassName("classname", someCondition) + }} + /> +} +``` + +### How to use non builtin Gtk widgets + +Using the `Widget.astalify` mixin you can subclass widgets +to behave like builtin widgets. +The `astalify` mixin 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 +- sets up signal handlers that are passed as props prefixed with `on` + +```tsx +import { Widget, Gtk, GObject, Gdk } from "astal/gtk3" + +// subclass, register, define constructor props +class ColorButton extends Widget.astalify(Gtk.ColorButton) { + static { GObject.registerClass(this) } + + constructor(props: Widget.ConstructProps< + ColorButton, + Gtk.ColorButton.ConstructorProps, + { onColorSet: [] } // signals of Gtk.ColorButton have to be manually typed + >) { + super(props as any) + } +} + +function MyWidget() { + function setup(button: ColorButton) { + + } + + return { + 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. +::: + +### 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 + 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 +} +``` + +### Builtin Widgets + +You can check the [source code](https://github.com/aylur/astal/blob/main/lang/gjs/src/gtk3/index.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) + +## Gtk4 + +🚧 Work in Progress 🚧 -- cgit v1.2.3 From b33c3bf91dbbea13b1a2c8603e00809b22cd42c8 Mon Sep 17 00:00:00 2001 From: Aylur Date: Tue, 15 Oct 2024 13:36:16 +0000 Subject: docs: fix links --- docs/guide/typescript/widget.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'docs/guide/typescript/widget.md') diff --git a/docs/guide/typescript/widget.md b/docs/guide/typescript/widget.md index 03ba9ea..d16d194 100644 --- a/docs/guide/typescript/widget.md +++ b/docs/guide/typescript/widget.md @@ -191,23 +191,23 @@ You can check the [source code](https://github.com/aylur/astal/blob/main/lang/gj 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) +- box: [Astal.Box](https://aylur.github.io/libastal/astal3/class.Box.html) +- 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) +- 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) +- 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) +- window: [Astal.Window](https://aylur.github.io/libastal/astal3/class.Window.html) ## Gtk4 -- cgit v1.2.3 From 5d37115078b6641437b6479943b679ec2d899b18 Mon Sep 17 00:00:00 2001 From: Aylur Date: Wed, 16 Oct 2024 10:24:16 +0000 Subject: docs: update widget subclass example --- docs/guide/typescript/widget.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs/guide/typescript/widget.md') diff --git a/docs/guide/typescript/widget.md b/docs/guide/typescript/widget.md index d16d194..3bdf394 100644 --- a/docs/guide/typescript/widget.md +++ b/docs/guide/typescript/widget.md @@ -104,13 +104,14 @@ The `astalify` mixin will apply the following: - sets up signal handlers that are passed as props prefixed with `on` ```tsx -import { Widget, Gtk, GObject, Gdk } from "astal/gtk3" +import GObject from "gi://GObject" +import { Gtk, Gdk, Widget, astalify, type ConstructProps } from "astal/gtk3" // subclass, register, define constructor props -class ColorButton extends Widget.astalify(Gtk.ColorButton) { +class ColorButton extends astalify(Gtk.ColorButton) { static { GObject.registerClass(this) } - constructor(props: Widget.ConstructProps< + constructor(props: ConstructProps< ColorButton, Gtk.ColorButton.ConstructorProps, { onColorSet: [] } // signals of Gtk.ColorButton have to be manually typed @@ -152,7 +153,8 @@ 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" +import { Binding, Variable } from "astal" +import { Widget } from "astal/gtk3" export interface ToggleButtonProps extends Widget.ButtonProps { onToggled?: (self: Widget.Button, on: boolean) => void -- cgit v1.2.3 From ab64f9eadf5c64d5353f7dce681d3ed3abd7df4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=28=E2=97=95=E1=B4=A5=E2=97=95=29?= Date: Sun, 27 Oct 2024 00:10:56 +0800 Subject: docs: fix gtk3 widget broken links (#60) --- docs/guide/typescript/widget.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/guide/typescript/widget.md') diff --git a/docs/guide/typescript/widget.md b/docs/guide/typescript/widget.md index 3bdf394..7ed69e3 100644 --- a/docs/guide/typescript/widget.md +++ b/docs/guide/typescript/widget.md @@ -197,18 +197,18 @@ These widgets are available by default in JSX. - 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 -- cgit v1.2.3