> ## Documentation Index
> Fetch the complete documentation index at: https://gabibou-ui.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Events and lifecycle

> Subscribe to UI events and release resources with their owner.

This page documents lifecycle behavior in Gabibou UI 1.5.0-rc.22. Short constructors and options-table constructors share the same events and cleanup rules.

## Window events

`window:On(name, callback)` subscribes to a window event and returns a disconnectable subscription.

| Event | Callback arguments |
| - | - |
| `TabChanged` | `tab, previousTab` |
| `VisibilityChanged` | `visible` |
| `ThemeChanged` | `themeName, themeTable` |
| `StyleChanged` | `styleTable` |
| `MotionChanged` | `motionTable` |
| `ReducedMotionChanged` | `enabled` |
| `NavigationChanged` | `navigationTable` |

Table arguments are copies. `MotionChanged` reports changes to tween policy; reduced motion has its own event.

Library-managed callbacks belong to their window or control. Destroying that owner cancels its callback tasks and disconnects its event subscriptions (including `Changed`) and `Connect` handlers. When a control callback raises an error, the player sees a short notification titled after the control (for example "Auto farm failed") with the script path and line number removed. The full message stays in `window.LastError` and the output. Callbacks that finish after destruction do not create stale notifications or update `LastError`. `window:Hide()` and `window:Show()` only change visibility, so they preserve subscriptions and callbacks. A callback that destroys its own owner is allowed to finish its current call. Tasks started directly by your code with `task.spawn` are not managed by the library; cancel them in your own cleanup path.

## Control events

`control:On(name, callback)` supports `Changed`, `HoverEnter`, `HoverLeave`, `Activated`, `FocusGained`, and `FocusLost` when the control exposes the corresponding signal. `Changed` receives `(newValue, oldValue)` when a value changes through `control:Set(..., true)`, `window:SetValues(..., true)`, or user interaction. `ImportConfig(..., true)` calls the control callbacks for imported values but does not emit `Changed`.

For `Input`, focus events follow its text box. For `ColorPicker`, focus events follow the hex field. Button-like controls use Roblox selection focus events, including keyboard and gamepad selection. A captured Keybind emits `Changed` when its assignment changes; its action callback runs only when the assigned key is pressed outside capture mode.

```lua theme={null}
local changed = window:Get("volume"):On("Changed", function(value, previous)
    print(previous, "->", value)
end)

-- Disconnect this subscription before the window closes if needed.
changed:Disconnect()
```

## Own connections and cleanup

`window:Connect(signal, callback)` and `control:Connect(signal, callback)` create a Roblox connection scoped to that owner. `window:Own(resource)` and `control:Own(resource)` accept an `RBXScriptConnection` or a table with `Disconnect()`. They do not accept a bare cleanup function.

```lua theme={null}
local RunService = game:GetService("RunService")
local status = window:Get("status")
status:Connect(RunService.Heartbeat, function(deltaTime)
    -- Update this control while it remains alive.
end)

window:OnDestroy(function()
    -- Cancel application tasks not owned by the UI library.
end)
```

`window:OnDestroy(callback)` is for external resources. The window cleans up its controls, subscriptions, connections, callback tasks, managed tweens, and notifications. Tasks started directly by your callback remain your responsibility; cancel them in an owner cleanup path.

## Loader and launch cleanup

A yielding loader `OnError(loader, title, index)` callback belongs to its loader. Destroying the loader cancels that callback, including if it starts another `Run()` attempt.

If a launch window is destroyed while a custom control builder is running, the launch session becomes `Destroyed` and cleans up its owned resources. It does not report `Ready` or call `OnReady`. After key authentication succeeds, cancelling the launch still calls the launch session's `OnCancel(session)` but does not call the gate's `KeySystem.OnCancel(gate)`.

Destroy a control with `control:Destroy()` and a window with `window:Destroy()`. `UI:DestroyAll()` closes all windows, gates, loaders, and launch sessions created by that library instance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.