1 files changed, 158 insertions, 0 deletions
diff --git a/docs/guide/lua/widget.md b/docs/guide/lua/widget.md
new file mode 100644
index 0000000..d9f99fa
--- /dev/null
+++ b/docs/guide/lua/widget.md
@@ -0,0 +1,158 @@
+# Widget
+
+## Gtk3
+
+### Additional widget properties
+
+These are properties that Astal additionally adds to Gtk.Widgets
+
+- class_name: `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).
+- click_through: `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`
+
+```lua
+local function MyWidget()
+    local button = Widget.Button()
+    -- setup button
+    return button
+end
+```
+
+using `setup`
+
+```lua
+local function MyWidget()
+    return Widget.Button({
+        setup = function(self)
+            -- setup button
+        end,
+    })
+end
+```
+
+#### hook
+
+Shorthand for connecting and disconnecting to [Subscribable and Connectable](./binding#subscribable-and-connectable-interface) objects.
+
+without `hook`
+
+```lua
+local function MyWidget()
+    local id = gobject.on_signal:connect(callback)
+    local unsub = variable:subscribe(callback)
+
+    return Widget.Box({
+        on_destroy = function()
+            GObject.signal_handler_disconnect(gobject, id)
+            unsub()
+        end,
+    })
+end
+```
+
+with `hook`
+
+```lua
+local function MyWidget()
+    return Widget.Box({
+        setup = function(self)
+            self:hook(gobject, "signal", callback)
+            self:hook(variable, callback)
+        end,
+    })
+end
+```
+
+#### toggle_class_name
+
+Toggle class names based on a condition.
+
+```lua
+local function MyWidget()
+    return Widget.Box({
+        setup = function(self)
+            self:toggle_class_name("classname", some_condition)
+        end,
+    })
+end
+```
+
+### How to use non builtin Gtk widgets
+
+Using the `astalify` function you can wrap widgets
+to behave like builtin widgets.
+It 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
+
+```lua
+local astal = require("astal.gtk3")
+local astalify = astal.astalify
+local Gtk = astal.Gtk
+local Gdk = astal.Gdk
+
+local ColorButton = astalify(Gtk.ColorButton)
+
+local function MyWidget()
+    return ColorButton({
+        setup = function(self)
+            -- setup ColorButton instance
+        end,
+        use_alpha = true,
+        rgba = Gdk.RGBA({
+            red = 1,
+            green = 0,
+            blue = 0,
+            alpha = 0.5,
+        }),
+        on_color_set = function(self)
+            print(self.rgba:to_string())
+        end
+    })
+end
+```
+
+### Builtin Widgets
+
+You can check the [source code](https://github.com/Aylur/astal/blob/main/lang/lua/astal/gtk3/widget.lua) to have a full list of builtin widgets.
+
+These widgets are available by default in Lua.
+
+- 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
+
+🚧 Work in Progress 🚧