diff options
22 files changed, 291 insertions, 167 deletions
diff --git a/docs/default.nix b/docs/default.nix index 3a75834..3d91a63 100644 --- a/docs/default.nix +++ b/docs/default.nix @@ -10,6 +10,7 @@ genRefForPkg = { name, pkg, + version ? "0.1", outPath, metaData, }: let @@ -18,13 +19,14 @@ in '' mkdir -p $out/${outPath} cat ${urlmap} > urlmap.js - gi-docgen generate -C ${data} ${output}/share/gir-1.0/${name}-0.1.gir - cp -r ${name}-0.1/* $out/${outPath} + gi-docgen generate -C ${data} ${output}/share/gir-1.0/${name}-${version}.gir + cp -r ${name}-${version}/* $out/${outPath} ''; genLib = name: namespace: { description, version, + api-ver ? "0.1", authors ? "Aylur", dependencies ? {}, out ? "libastal/${name}", @@ -33,6 +35,7 @@ name = "Astal${namespace}"; pkg = name; outPath = out; + version = api-ver; metaData = { library = { inherit description authors; @@ -106,10 +109,14 @@ in installPhase = '' runHook preInstall - ${genLib "astal" "" { - out = "libastal"; - description = "Astal core library"; - version = ../core/version; + ${genLib "io" "IO" { + description = "Astal IO library"; + version = ../lib/astal/io/version; + }} + ${genLib "astal3" "" { + api-ver = "3.0"; + description = "Astal GTK3 library"; + version = ../lib/astal/gtk3/version; dependencies = {inherit (dependency) "Gtk-3.0";}; }} ${genLib "apps" "Apps" { 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/getting-started/installation.md b/docs/guide/getting-started/installation.md index af82cf5..6ad951a 100644 --- a/docs/guide/getting-started/installation.md +++ b/docs/guide/getting-started/installation.md @@ -10,6 +10,8 @@ Read more about it on the [nix page](./nix#astal) maintainer: [@kotontrion](https://github.com/kotontrion) +<!--TODO: fix aur package names--> + :::code-group ```sh [Core Library] @@ -28,7 +30,6 @@ yay -S libastal-meta ```sh git clone https://github.com/aylur/astal.git -cd astal/core ``` 2. Install the following dependencies @@ -51,7 +52,18 @@ sudo apt install meson valac libgtk-3-dev libgtk-layer-shell-dev gobject-introsp 3. Build and install with `meson` +- astal-io + +```sh +cd lib/astal/io +meson setup build +meson install -C build +``` + +- astal3 + ```sh +cd lib/astal/gtk3 meson setup build meson install -C build ``` diff --git a/docs/guide/getting-started/introduction.md b/docs/guide/getting-started/introduction.md index 92d2ff1..af176c3 100644 --- a/docs/guide/getting-started/introduction.md +++ b/docs/guide/getting-started/introduction.md @@ -2,22 +2,25 @@ ## 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](https://aylur.github.io/libastal) has some Gtk widgets that come packaged, -the most important one is the [Window](https://aylur.github.io/libastal/class.Window.html) which is the main toplevel component using [gtk-layer-shell](https://github.com/wmww/gtk-layer-shell). +Astal (_meaning "desk"_) is a suite of libraries in Vala and C. +The core library [astal3](https://aylur.github.io/libastal/astal3) and +[astal4](https://aylur.github.io/libastal/astal4) (not yet available) +has some Gtk widgets that come packaged, +the most important one being the [Window](https://aylur.github.io/libastal/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. +The other part of the core library [astal-io](https://aylur.github.io/libastal/astal-io) +which contains some utility GLib shortcut for running external processes, +reading, writing and monitoring files, timeout and interval functions. ## Why Astal? -What makes Astal convenient to use is not the core library, as it could easily be replaced +What makes Astal convenient to use is not the core libraries, as they can easily be replaced by the standard library of any of your favorite language that has bindings to Gtk, it is the -accompanying libraries (_formerly known as "services" in AGS_) +accompanying libraries (_formerly known as "services" in AGS_). Have you ever wanted to write a custom bar, custom notification popups or an applauncher, but gave up because writing a workspace widget, implementing the notification daemon or handling a search filter was too much of a hassle? -Astal libraries have you [covered](/guide/libraries/references), you don't have to worry about these, +Astal libraries have you [covered](../libraries/references#astal-libraries), you don't have to worry about these, you just define the layout, style it with CSS and that's it. diff --git a/docs/guide/getting-started/nix.md b/docs/guide/getting-started/nix.md index 81f4e4d..5c0db28 100644 --- a/docs/guide/getting-started/nix.md +++ b/docs/guide/getting-started/nix.md @@ -1,3 +1,8 @@ +--- +next: + link: '/guide/getting-started/supported-languages' + text: 'Supported Languages' +--- # Nix ## Astal @@ -74,11 +79,16 @@ Using Astal on Nix will require you to package your project. } ``` +```nix [<i class="devicon-typescript-plain"></i> TypeScript] +# The usage of AGS (read below) is recommended +# Usage without AGS is not yet documented +``` + ::: ## AGS -The recommended way to use AGS on NixOS is through the home-manager module. +The recommended way to use [AGS](../ags/first-widgets#first-widgets) on NixOS is through the home-manager module. Example content of a `flake.nix` file that contains your `homeConfigurations`. @@ -144,7 +154,7 @@ Example content of `home.nix` file ::: -AGS by default only includes the core `libastal` library. +AGS by default only includes the core `astal3/astal4` and `astal-io` libraries. If you want to include any other [library](../libraries/references) you have to add them to `extraPackages`. You can also add binaries which will be added to the gjs runtime. @@ -158,7 +168,11 @@ The AGS flake does not expose the `astal` cli to the home environment, you have :::code-group ```nix [<i class="devicon-nixos-plain"></i> home.nix] -home.packages = [ inputs.ags.packages.${pkgs.system}.astal ]; +home.packages = [ inputs.ags.packages.${pkgs.system}.default ]; +``` + +```sh [<i class="devicon-bash-plain"></i> sh] +astal --help ``` ::: diff --git a/docs/guide/getting-started/supported-languages.md b/docs/guide/getting-started/supported-languages.md index 4cb7f3a..47d5dbd 100644 --- a/docs/guide/getting-started/supported-languages.md +++ b/docs/guide/getting-started/supported-languages.md @@ -1,9 +1,15 @@ # Supported Languages +There are currently two languages that have an additional +Astal package: Lua and Gjs. Their purpose is to abstract away +Gtk by implementing a state management and UI declaring solution. + ## JavaScript -The main intended usage of Astal is in TypeScript with [AGS](/guide/ags/first-widgets). -It supports JSX and has a state management solution similar to web frameworks. +The main intended usage of Astal is in TypeScript+JSX. +It is recommended to use [AGS](/guide/ags/first-widgets) to scaffold and run projects in TypeScript. +However, if you are familiar with JavaScript's tooling +ecosystem you can also setup an environment yourself. Only a minimal knowledge of JavaScript's syntax is needed to get started. :::info @@ -17,11 +23,7 @@ Examples: ## Lua -Similar to how there is a [TypeScript](https://github.com/Aylur/astal/tree/main/core/gjs) lib for GJS, there is also an accompanying library for [Lua](https://github.com/Aylur/astal/tree/main/core/lua). -<!--TODO: open issue and link performance issue--> -Unfortunately, I have encountered very heavy [performance issues](https://github.com/aylur/astal) with [lgi](https://github.com/lgi-devs/lgi), -and so currently I don't recommend using Lua for full desktop shells, but only for static -components that don't render child nodes dynamically, bars and panels for example. +Lua is well-supported, but I would still recommend TypeScript, as Lua lacks a type system, which in turn limits editor support. Examples: @@ -30,10 +32,9 @@ Examples: ## Python -There was a WIP [library for python](https://github.com/aylur/astal/tree/feat/python), to make it behave similar to the above two -but I don't plan on finishing it, because I'm not a fan of python. -If you are interested in picking it up, feel free to open a PR. -Nonetheless you can still use python the OOP way [pygobject](https://pygobject.gnome.org/tutorials/gobject/subclassing.html) intended it. +There is a WIP [package for python](https://github.com/aylur/astal/tree/feat/python), +to bring declaritivity to Python similar to the above two languages. +However, you can still use python the OOP way [pygobject](https://pygobject.gnome.org/tutorials/gobject/subclassing.html) intended it in the meantime. Examples: @@ -44,7 +45,7 @@ Examples: Vala is a language that simply put uses C# syntax and compiles to C. It is the language most of Astal is written in. I would still recommend -using TypeScript or Lua over Vala as they don't need a build step. +using TypeScript or Lua over Vala as they are simpler to work with. Examples: diff --git a/docs/guide/lua/first-widgets.md b/docs/guide/lua/first-widgets.md new file mode 100644 index 0000000..2abe7c5 --- /dev/null +++ b/docs/guide/lua/first-widgets.md @@ -0,0 +1,3 @@ +# First Widgets + +🚧 Lua documentation is in Progress 🚧 diff --git a/docs/guide/lua/installation.md b/docs/guide/lua/installation.md new file mode 100644 index 0000000..48241f9 --- /dev/null +++ b/docs/guide/lua/installation.md @@ -0,0 +1,3 @@ +# Installation + +🚧 Lua documentation is in Progress 🚧 diff --git a/docs/guide/ags/binding.md b/docs/guide/typescript/binding.md index f1592a0..05645ab 100644 --- a/docs/guide/ags/binding.md +++ b/docs/guide/typescript/binding.md @@ -132,9 +132,10 @@ function MappedBox() { ## Example Custom Connectable -This was formerly known as a "Service" in AGS. -Astal provides [decorator functions](./gobject#example-usage) that make it easy to subclass gobjects, however -you can read more about GObjects and subclassing on [gjs.guide](https://gjs.guide/guides/gobject/subclassing.html#gobject-subclassing). +Astal provides [decorator functions](./gobject#example-usage) +that make it easy to subclass gobjects, however +you can read more about GObjects and subclassing +on [gjs.guide](https://gjs.guide/guides/gobject/subclassing.html#gobject-subclassing). Objects coming from [libraries](../libraries/references#astal-libraries) usually have a singleton gobject you can access with `.get_default()`. diff --git a/docs/guide/ags/cli-app.md b/docs/guide/typescript/cli-app.md index ec6d174..3407e06 100644 --- a/docs/guide/ags/cli-app.md +++ b/docs/guide/typescript/cli-app.md @@ -1,9 +1,13 @@ # CLI and App -`App` is a singleton **instance** of [Astal.Application](https://aylur.github.io/libastal/class.Application.html). +`App` is a singleton **instance** of an [Astal.Application](https://aylur.github.io/libastal/class.Application.html). + +Depending on gtk version import paths will differ ```ts -import { App } from "astal" +import { App } from "astal/gtk3" + +import { App } from "astal/gtk4" ``` ## Entry point @@ -21,10 +25,6 @@ App.start({ ::: -:::warning -You can not instantiate widgets outside of the main function. -::: - ## Instance identifier You can run multiple instance by defining a unique instance name. @@ -32,47 +32,48 @@ You can run multiple instance by defining a unique instance name. ```ts App.start({ instanceName: "my-instance", // defaults to "astal" - main() {}, + main() { }, }) ``` ## Messaging from CLI -If you want to interact with an instance from the cli, you can do so by sending a message. +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") }, + main() { }, }) ``` :::code-group -```sh [ags] -ags -m "say hi" +```sh [astal] +astal say hi # hi cli ``` -```sh [astal] -astal say hi +```sh [ags] +ags -m "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. +If you want to run arbitrary JavaScript from CLI, you can use `App.eval` +which will evaluate the passed string as the body of an `async` function. ```ts App.start({ main() {}, - requestHandler(js: string, res) { + requestHandler(js, res) { App.eval(js).then(res).catch(res) }, }) @@ -81,23 +82,23 @@ App.start({ If the string does not contain a semicolon, a single expression is assumed and returned implicity. ```sh -ags -m "'hello'" +astal "'hello'" # hello ``` If the string contains a semicolon, you have to return explicitly ```sh -ags -m "'hello';" +astal "'hello';" # undefined -ags -m "return 'hello';" +astal "return 'hello';" # hello ``` ## Toggling Windows by their name -In order for AGS to know about your windows, you have to register them. +In order for Astal 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} @@ -127,18 +128,24 @@ 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 +:::code-group + +```sh [astal] +astal -t Bar +``` + +```sh [ags] ags -t Bar ``` -## App without AGS +::: + +## Bundled scripts -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 +The produced scripts when bundling can run as the main instance and a "client" instance. -The first time you run your bundled script the `main` function gets executed. +The first time you execute your bundled script the `main` function gets called. While that instance is running any subsequent execution of the script will call the `client` function. diff --git a/docs/guide/ags/faq.md b/docs/guide/typescript/faq.md index 76d8e72..76d8e72 100644 --- a/docs/guide/ags/faq.md +++ b/docs/guide/typescript/faq.md diff --git a/docs/guide/ags/first-widgets.md b/docs/guide/typescript/first-widgets.md index 6dba7b3..3664bfa 100644 --- a/docs/guide/ags/first-widgets.md +++ b/docs/guide/typescript/first-widgets.md @@ -1,15 +1,5 @@ # 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 @@ -24,14 +14,30 @@ then run `ags` in the terminal ags ``` -Done! You have now a custom written bar using Gtk. +:::details Usage without AGS +🚧 Not yet documented. 🚧 +::: + +That's it! 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/). +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 AGS init command will generate the following files + +```txt +. +├── @girs/ # generated types +├── widget/ +│ └── Bar.tsx +├── app.ts # entry proint +├── env.d.ts # additional types +├── style.css +└── tsconfig.json # needed by LSPs +``` + ## 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. @@ -81,7 +87,7 @@ function MyButton(): JSX.Element { ``` ```ts [MyButton.ts] -import { Widget } from "astal" +import { Widget } from "astal/gtk3" function MyButton(): Widget.Button { return new Widget.Button( @@ -369,7 +375,11 @@ 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>>`. ```tsx -function MyContainer({ children }) { +import { type Binding } from "astal" + +function MyContainer({ children }: { + children?: Binding<Array<JSX.Element>> +}) { // children is a Binding over an Array of widgets } diff --git a/docs/guide/ags/gobject.md b/docs/guide/typescript/gobject.md index 83b7c45..f7f001d 100644 --- a/docs/guide/ags/gobject.md +++ b/docs/guide/typescript/gobject.md @@ -1,6 +1,5 @@ # Subclassing GObject.Object -These were formerly known as custom services in AGS. Astal provides decorator functions that make it easy to subclass gobjects. ## Example Usage diff --git a/docs/guide/typescript/installation.md b/docs/guide/typescript/installation.md new file mode 100644 index 0000000..4c31b6e --- /dev/null +++ b/docs/guide/typescript/installation.md @@ -0,0 +1,89 @@ +# Installation + +It is recommended to use [AGS](https://github.com/aylur/ags) +to scaffold and run projects in TypeScript. + +It lets you + +- generate TypeScript types using [ts-for-gir](https://github.com/gjsify/ts-for-gir) +- generate a tsconfig which is used by LSPs +- bundle your TypeScript and JavaScript code using [esbuild](https://esbuild.github.io/). + +::: details Trivia +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+TypeScript+JSX projects. +::: + +## 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#agsFull -- --help +``` + +## From source + +1. [Install Astal](../getting-started/installation.md) if you have not already + +2. Install the Astal GJS package + +```sh +git clone https://github.com/aylur/astal +cd lang/gjs +meson setup --prefix /usr build +meson install -C build +``` + +:::tip +You might be wondering why it is recommended to install a JavaScript +package on the system instead of installing it as a node module. +It is solely to keep it in **sync** with the core `astal-sh` and `astal3`/`astal4` package. +::: + +3. 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 +git checkout v2 # https://github.com/Aylur/ags/pull/504 +cd ags/src +go install +``` + +:::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 +sudo mv $GOPATH/bin/ags /usr/bin/ags +``` + +::: + +## Without AGS + +🚧 Setting up a dev environment without AGS is not yet documented. 🚧 diff --git a/docs/guide/ags/theming.md b/docs/guide/typescript/theming.md index cb0ebff..10a3981 100644 --- a/docs/guide/ags/theming.md +++ b/docs/guide/typescript/theming.md @@ -23,7 +23,9 @@ You can pass a path to a file or css as a string in `App.start` :::code-group ```ts [app.ts] -const inlineCss = ` +import style from "inline:./style.css" + +const inlineCssInCode = ` window { background-color: transparent; } @@ -31,6 +33,7 @@ window { App.start({ css: "./style.css", + css: style, css: `${SRC}/style.css'`, css: inlineCss, }) @@ -39,8 +42,9 @@ App.start({ ::: :::info -The global `SRC` will point to the directory `app.ts` is in. +When using AGS 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. +If you are not using AGS you should inline import CSS instead. ::: ## Css Property on Widgets @@ -86,11 +90,20 @@ You can reset stylesheets with `App.resetCss` 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 +::: code-group + +```sh [astal] +# to bring up the inspector run +astal --inspector +``` + +```sh [ags] # to bring up the inspector run ags --inspector ``` +::: + ## Using SCSS Gtk's CSS only supports a subset of what the web offers. @@ -128,6 +141,11 @@ App.start({ ::: +:::details Without AGS +AGS uses a plugin to transpile scss files before importing them. +If you are not using AGS, you can use a plugin for your chosen bundler. +::: + :::tip If you for example want to set scss varibles from JS, You can inline import, compose, and transpile yourself. diff --git a/docs/guide/ags/utilities.md b/docs/guide/typescript/utilities.md index aae255c..9bc56b2 100644 --- a/docs/guide/ags/utilities.md +++ b/docs/guide/typescript/utilities.md @@ -2,8 +2,6 @@ ## File functions -Import them from `astal` or `astal/file` - ```ts import { readFile, @@ -39,8 +37,6 @@ function monitorFile( ## Timeouts and Intervals -Import them from `astal` or `astal/time` - ```ts import { interval, timeout, idle } from "astal" ``` @@ -96,8 +92,6 @@ timer.cancel() ## Process functions -Import them from `astal` or `astal/proc` - ```ts import { subprocess, exec, execAsync } from "astal" ``` diff --git a/docs/guide/ags/variable.md b/docs/guide/typescript/variable.md index 4207f61..4207f61 100644 --- a/docs/guide/ags/variable.md +++ b/docs/guide/typescript/variable.md diff --git a/docs/guide/ags/widget.md b/docs/guide/typescript/widget.md index 01cff81..03ba9ea 100644 --- a/docs/guide/ags/widget.md +++ b/docs/guide/typescript/widget.md @@ -1,6 +1,8 @@ # Widget -## Additional widget properties +## Gtk3 + +### Additional widget properties These are properties that Astal additionally adds to Gtk.Widgets @@ -11,12 +13,12 @@ These are properties that Astal additionally adds to Gtk.Widgets To have a full list of available properties, reference the documentation of the widget. -- [Astal widgets](https://aylur.github.io/libastal/index.html#classes) +- [Astal3 widgets](https://aylur.github.io/libastal/astal3/index.html#classes) - [Gtk widgets](https://docs.gtk.org/gtk3/#classes) -## Additional widget methods +### Additional widget methods -### setup +#### setup `setup` is a convenience prop to remove the need to predefine widgets before returning them in cases where a reference is needed. @@ -43,7 +45,7 @@ function MyWidget() { } ``` -### hook +#### hook Shorthand for connection and disconnecting to [Subscribable and Connectable](./binding#subscribable-and-connectable-interface) objects. @@ -76,7 +78,7 @@ function MyWidget() { } ``` -### toggleClassName +#### toggleClassName Toggle classNames based on a condition @@ -90,7 +92,7 @@ function MyWidget() { } ``` -## How to use non builtin Gtk widgets +### How to use non builtin Gtk widgets Using the `Widget.astalify` mixin you can subclass widgets to behave like builtin widgets. @@ -102,7 +104,7 @@ 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" +import { Widget, Gtk, GObject, Gdk } from "astal/gtk3" // subclass, register, define constructor props class ColorButton extends Widget.astalify(Gtk.ColorButton) { @@ -144,7 +146,7 @@ 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 +### TypeScript Type of widgets are available through `Widget`. Here is an example Widget that takes in and handles a possibly `Binding` prop. @@ -183,9 +185,9 @@ export default function ToggleButton(btnprops: ToggleButtonProps) { } ``` -## Builtin Widgets +### 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. +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. @@ -206,3 +208,7 @@ These widgets are available by default in JSX. - 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 🚧 diff --git a/docs/index.md b/docs/index.md index f22ae19..8f5287b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,7 +5,7 @@ pageClass: home-page hero: name: "Astal" text: "Create Beautiful Widgets With Ease" - tagline: "The Framework to Craft Desktop Shells and <i>beautiful</i> <i>functional</i> Wayland Widgets with GTK!" + tagline: "The Linux Suite and Framework to Craft Desktop Shells and <i>beautiful</i> <i>functional</i> Wayland Widgets with GTK!" image: /icon.svg actions: - theme: brand @@ -21,10 +21,10 @@ hero: features: - title: Use Your Preferred Language icon: <i style="color:var(--vp-c-brand-3)" class="devicon-typescript-plain"></i> - details: The main focus of Astal is TypeScript using JSX. But you can use the libraries in any language that supports <a href="https://en.wikipedia.org/wiki/List_of_language_bindings_for_GTK">Gobject Introspection</a>. + details: The main focus of Astal is TypeScript+JSX. But you can use the libraries in any language that supports <a href="https://en.wikipedia.org/wiki/List_of_language_bindings_for_GTK">Gobject Introspection</a>. - title: No bash scripts needed icon: <i style="color:var(--vp-c-brand-3)" class="devicon-bash-plain"></i> - details: Includes modules to work with Network, Bluetooth, Battery, Audio and more. + details: Includes modules to work with Network, Bluetooth, Battery, Audio and <a href="/astal/guide/libraries/references#astal-libraries">more</a>. - title: Use any Gtk widget icon: <i style="color:var(--vp-c-brand-3)" class="fl-gtk"></i> details: With Astal you work with Gtk directly. You are not limited to only a set of them. @@ -56,6 +56,7 @@ features: .VPFeature a { font-weight: bold; + color: var(--vp-c-brand-2); } .VPFooter { diff --git a/docs/result-dev b/docs/result-dev new file mode 120000 index 0000000..52fdae0 --- /dev/null +++ b/docs/result-dev @@ -0,0 +1 @@ +/nix/store/080gmk15wbbjx258rxzsq19ykjdrvl39-astal-0.1.0-dev
\ No newline at end of file diff --git a/docs/vitepress.config.ts b/docs/vitepress.config.ts index 47ed81e..843d3d3 100644 --- a/docs/vitepress.config.ts +++ b/docs/vitepress.config.ts @@ -59,8 +59,8 @@ export default defineConfig({ ], }, { - text: "AGS", - base: "/guide/ags", + text: "TypeScript", + base: "/guide/typescript", collapsed: false, items: [ { text: "Installation", link: "/installation" }, @@ -76,11 +76,22 @@ export default defineConfig({ ], }, { + text: "Lua", + base: "/guide/lua", + collapsed: false, + items: [ + { text: "Installation", link: "/installation" }, + { text: "First Widgets", link: "/first-widgets" }, + ], + }, + { text: "Libraries", collapsed: true, items: [ { text: "References", link: "/guide/libraries/references" }, - { text: "Astal", link: "https://aylur.github.io/libastal" }, + { text: "AstalIO", link: "https://aylur.github.io/libastal/astal-io" }, + { text: "Astal3", link: "https://aylur.github.io/libastal/astal3" }, + { text: "Astal4", link: "https://aylur.github.io/libastal/astal4" }, { text: "Apps", link: "/guide/libraries/apps" }, { text: "Auth", link: "/guide/libraries/auth" }, { text: "Battery", link: "/guide/libraries/battery" }, diff --git a/lang/gjs/meson.build b/lang/gjs/meson.build new file mode 100644 index 0000000..8f3058f --- /dev/null +++ b/lang/gjs/meson.build @@ -0,0 +1,9 @@ +project('astal-gjs') + +datadir = get_option('prefix') / get_option('datadir') +pkgdata = datadir / 'astal' / 'gjs' + +install_data('index.ts', install_dir: pkgdata) +install_subdir('lib', install_dir: pkgdata) +install_subdir('gtk3', install_dir: pkgdata) +install_subdir('gtk4', install_dir: pkgdata) |