> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rebind.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# rb.window

> Find windows by title, then focus, move, resize, close or wait for them.

`rb.window` finds windows by title and acts on them. A script reaches for it to
put an app's window in place, or to wait for a window to open, gain focus or
close. On macOS most of these calls raise; see
[rb.window on macOS](https://docs.rebind.gg/concepts/platforms.md#rb-window-on-macos).

**Needs:** a coroutine for `wait`, `wait_active` and `wait_close`, so call them
inside `rb.run` or `rb.async` (see
[Where code runs](https://docs.rebind.gg/reference/sdk/globals.md#where-code-runs)).

This script waits up to 10 seconds for Notepad, brings it forward, and moves it
to 0,0 at 800 by 600:

```luau theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
-- rebind: min_sdk=3.9.0 name=example version=1.0.0
rb.run(function()
  local hw = rb.window.wait("Notepad", 10000)
  if hw then
    rb.window.activate(hw)
    rb.window.move(hw, { x = 0, y = 0, width = 800, height = 600 })
  end
end)
```

Window handles are numbers from `find`, `list`, `get_foreground` and
`from_point`. Calls whose handle is optional act on the focused window when it
is `nil`.

| Signature | Returns |
| - | - |
| `rb.window.find(title: string) -> number?` | the first visible window whose title contains `title`, ignoring case; on macOS the app name may match instead |
| `rb.window.list(title: string?) -> { WindowEntry }` | `{ handle, title, process, x, y, width, height }` per window |
| `rb.window.get_title(handle: number?) -> string` | title |
| `rb.window.get_class(handle: number?) -> string` | class name |
| `rb.window.get_pos(handle: number?) -> WindowPos` | `{ x, y, width, height }` |
| `rb.window.get_pid(handle: number?) -> number` | owning process id |
| `rb.window.activate(handle: number) -> ()` | brings the window forward; raises when the system refuses |
| `rb.window.move(handle: number?, rect: RbWindowRect?) -> ()` | `rect` takes `x`, `y`, `width`, `height`; a field left out keeps its value |
| `rb.window.set_always_on_top(handle: number, enabled: boolean) -> ()` | pins or unpins |
| `rb.window.set_transparency(handle: number, alpha: number) -> ()` | 0 transparent to 255 opaque, clamped |
| `rb.window.set_title(handle: number, title: string) -> ()` | |
| `rb.window.minimize(handle: number?) -> ()` | |
| `rb.window.maximize(handle: number?) -> ()` | |
| `rb.window.restore(handle: number?) -> ()` | |
| `rb.window.hide(handle: number?) -> ()` | |
| `rb.window.show(handle: number?) -> ()` | |
| `rb.window.close(handle: number?) -> ()` | asks the window to close; it may prompt |
| `rb.window.kill(handle: number?) -> ()` | ends the owning process; unsaved work is lost |
| `rb.window.is_visible(handle: number) -> boolean` | |
| `rb.window.is_active(handle: number?) -> boolean` | whether it is focused |
| `rb.window.get_foreground() -> number?` | the focused window |
| `rb.window.from_point(x: number, y: number) -> number?` | the top-level window under the point |
| `rb.window.get_state(handle: number?) -> string` | `"minimized"`, `"maximized"` or `"normal"`; Windows only |
| `rb.window.wait(title: string, timeout: number?) -> number?` | the handle once a window matches, `nil` on timeout |
| `rb.window.wait_active(title: string, timeout: number?) -> boolean` | `true` once a matching window is focused, `false` on timeout |
| `rb.window.wait_close(title: string, timeout: number?) -> boolean` | `true` once no window matches, `false` on timeout |

The wait calls take `timeout` in milliseconds (default 5000) and check every
50 ms.


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