# Command

> API reference for Pyzed commands: the side effects returned by update and callbacks, such as focusing fields, closing and background tasks.

Source: https://albakore.github.io/pyzed/reference/command/

<!-- Generated by docs/scripts/gen_api.py. Edit docs/scripts/api_docs_en.py. -->

A `Command` is an effect the runtime performs for you. Return it from `update`,
`on_start`, `on_key` or any callback. You can also return a list or a tuple of
commands. See the [commands and tasks](https://albakore.github.io/pyzed/guides/commands/) guide.

```python
from pyzed import Command

def on_key(self, combo):
    if combo == "ctrl-p":
        self.finder_open = True
        return Command.focus("finder")
```

## Static methods

### `Command`

The command class. Don't instantiate it directly: use its static methods.

### `exit`

```python
exit()
```

Closes the application.

### `focus`

```python
focus(id)
```

Focuses the `text_input` (or editor) with that `id`.

| Parameter | Description |
| --- | --- |
| `id` | The `id` you passed to the widget. |

### `focus_next`

```python
focus_next()
```

Moves the keyboard focus to the next field of the window, wrapping around (what Tab does).

### `focus_previous`

```python
focus_previous()
```

Moves the keyboard focus to the previous field of the window (what Shift+Tab does).

### `select_all`

```python
select_all(id)
```

Focuses the `text_input` with that `id` and selects all its text (typing replaces it).

| Parameter | Description |
| --- | --- |
| `id` | The input's `id`. |

### `set_editor_text`

```python
set_editor_text(id, text)
```

Replaces the content of the `code_editor` with that `id`. Editors are uncontrolled: `text` is only the initial value.

| Parameter | Description |
| --- | --- |
| `id` | The editor's `id`. |
| `text` | The new text. |

### `set_editor_cursor`

```python
set_editor_cursor(id, line, column)
```

Moves the editor cursor (line and column start at 1). Works even if the editor hasn't been drawn yet.

| Parameter | Description |
| --- | --- |
| `id` | The editor's `id`. |
| `line` | Line (from 1). |
| `column` | Column (from 1). |

### `fold_all`

```python
fold_all(id, fold=True)
```

Folds every block of the editor (`fold=False` unfolds them all). Works even if the editor hasn't been drawn yet.

| Parameter | Description |
| --- | --- |
| `id` | The editor's `id`. |
| `fold` | `True` to fold, `False` to unfold. |

### `fold_line`

```python
fold_line(id, line, fold=True)
```

Folds (or unfolds) the block that starts at `line`, by indentation. Works even if the editor hasn't been drawn yet.

| Parameter | Description |
| --- | --- |
| `id` | The editor's `id`. |
| `line` | Line (from 1) where the block starts. |
| `fold` | `True` to fold, `False` to unfold. |

### `editor_action`

```python
editor_action(id, name)
```

Runs a named editor action in the editor with that `id`, as if its key was pressed: Zed's action name in snake case (`"undo"`, `"select_next"`, `"move_line_up"`, `"toggle_comments"`…). Raises `ValueError` for an unknown name.

| Parameter | Description |
| --- | --- |
| `id` | The editor's `id`. |
| `name` | The action's name (`Command.editor_actions()` lists them; `"editor::SelectNext"` works too). |

### `editor_actions`

```python
editor_actions()
```

The names `Command.editor_action` accepts.

### `select_editor_ranges`

```python
select_editor_ranges(id, ranges)
```

Selects ranges of the editor, one cursor each; the first one is the primary cursor. Unfolds what hides them and works even if the editor hasn't been drawn yet.

| Parameter | Description |
| --- | --- |
| `id` | The editor's `id`. |
| `ranges` | `[(line, column, end_line, end_column)]`, from 1, with exclusive ends (an empty range is a plain cursor). |

### `replace_editor_ranges`

```python
replace_editor_ranges(id, edits)
```

Replaces ranges of the editor with texts as one undo step, and calls the editor's `on_change` (search and replace).

| Parameter | Description |
| --- | --- |
| `id` | The editor's `id`. |
| `edits` | `[((line, column, end_line, end_column), text)]`, from 1, with exclusive ends. |

### `scroll_to_end`

```python
scroll_to_end(id)
```

Scrolls the `scrollable` with that `id` to the end.

| Parameter | Description |
| --- | --- |
| `id` | The scrollable's `id`. |

### `batch`

```python
batch(commands)
```

Runs several commands.

| Parameter | Description |
| --- | --- |
| `commands` | List of `Command`. |

### `message`

```python
message(message)
```

Sends `message` to `update` again on the next cycle.

| Parameter | Description |
| --- | --- |
| `message` | Any Python value, or a callable. |

### `perform`

```python
perform(function, then=None)
```

Runs `function()` in the background and delivers the result to `then(result)` on the UI thread. `function` can be regular (runs on a thread) or `async def` (runs on Pyzed's asyncio loop). If it returns a generator (regular or async), `then` is called with each value. It also accepts an already created coroutine or generator (`fetch(url)` instead of `fetch`). Without `then`, results go to `update`. If `function` raises, the error is printed.

| Parameter | Description |
| --- | --- |
| `function` | Function with no arguments that does the slow work. |
| `then` | Callable that receives the result (or `None` to send it to `update`). |

```python
def load(self):
    self.loading = True
    return Command.perform(lambda: requests.get(URL).json(), self.received)

def received(self, data):
    self.loading, self.data = False, data
```

### `scroll_to`

```python
scroll_to(id, x=0.0, y=0.0)
```

Scrolls the `scrollable` with that `id` to an absolute position in pixels.

| Parameter | Description |
| --- | --- |
| `id` | The scrollable's `id`. |
| `x` | Horizontal offset. |
| `y` | Vertical offset. |

### `copy`

```python
copy(text)
```

Copies `text` to the system clipboard.

| Parameter | Description |
| --- | --- |
| `text` | The text. |

### `paste`

```python
paste(then)
```

Reads the clipboard and calls `then(text)` (empty string if it is empty).

| Parameter | Description |
| --- | --- |
| `then` | Callable that receives the text. |

### `paste_image`

```python
paste_image(then)
```

Reads an image from the clipboard (a screenshot, a copied picture) and calls `then(png)` with its PNG bytes, or `then(None)` when the clipboard holds no image.

| Parameter | Description |
| --- | --- |
| `then` | Callable that receives the PNG bytes or `None`. |

### `pick_files`

```python
pick_files(
    then,
    *,
    title=None,
    filters=None,
    directory=None,
    multiple=True,
    folder=False,
)
```

Opens the system's file dialog and calls `then(paths)` with the chosen paths (an empty list when it is cancelled).

| Parameter | Description |
| --- | --- |
| `then` | Callable that receives the list of paths. |
| `title` | The dialog's title. |
| `filters` | A list of `(name, extensions)` pairs, like `[("Images", ["png", "jpg"])]`. |
| `directory` | The folder it opens in. |
| `multiple` | `False` picks a single file. |
| `folder` | `True` picks folders instead of files. |

### `save_file`

```python
save_file(then, *, title=None, filters=None, directory=None, file_name=Ellipsis)
```

Opens the system's "Save as" dialog and calls `then(paths)` with the chosen path in a list (an empty list when it is cancelled).

| Parameter | Description |
| --- | --- |
| `then` | Callable that receives the list with the path. |
| `title` | The dialog's title. |
| `filters` | A list of `(name, extensions)` pairs, like `[("Images", ["png", "jpg"])]`. |
| `directory` | The folder it opens in. |
| `file_name` | The name it suggests. |

## Windows and clipboard

### `open_window`

```python
open_window(window)
```

Opens a new window for that `pz.Window` instance.

| Parameter | Description |
| --- | --- |
| `window` | The window. |

### `close_window`

```python
close_window(window=None)
```

Closes the window.

| Parameter | Description |
| --- | --- |
| `window` | The window (`pz.Window`). Without it, the one that produced the message. |

### `drag_window`

```python
drag_window(window=None)
```

Starts moving the window with the mouse (use it when a custom title bar is pressed).

| Parameter | Description |
| --- | --- |
| `window` | The window (`pz.Window`). Without it, the one that produced the message. |

### `minimize_window`

```python
minimize_window(window=None)
```

Minimizes the window.

| Parameter | Description |
| --- | --- |
| `window` | The window (`pz.Window`). Without it, the one that produced the message. |

### `toggle_maximize_window`

```python
toggle_maximize_window(window=None)
```

Maximizes the window, or restores it if it already is.

| Parameter | Description |
| --- | --- |
| `window` | The window (`pz.Window`). Without it, the one that produced the message. |

### `maximize_window`

```python
maximize_window(maximized=True, window=None)
```

Maximizes the window, or restores it with `maximized=False`.

| Parameter | Description |
| --- | --- |
| `maximized` | `False` restores it. |
| `window` | The window (`pz.Window`). Without it, the one that produced the message. |

### `drag_resize_window`

```python
drag_resize_window(direction, window=None)
```

Starts resizing the window with the mouse from an edge or corner (for windows without system decorations; `ui.window_frame` and `pz.window_edges` already do it).

| Parameter | Description |
| --- | --- |
| `direction` | `"n"`, `"s"`, `"e"`, `"w"`, `"ne"`, `"nw"`, `"se"` or `"sw"`. |
| `window` | The window (`pz.Window`). Without it, the one that produced the message. |

### `show_window_menu`

```python
show_window_menu(window=None)
```

Shows the system's window menu (move, size, close…) under the pointer. Only Windows has one.

| Parameter | Description |
| --- | --- |
| `window` | The window (`pz.Window`). Without it, the one that produced the message. |

### `set_fullscreen`

```python
set_fullscreen(fullscreen=True, window=None)
```

Enters or leaves fullscreen.

| Parameter | Description |
| --- | --- |
| `fullscreen` | `True` for fullscreen. |
| `window` | The window (`pz.Window`). Without it, the one that produced the message. |

### `resize_window`

```python
resize_window(width, height, window=None)
```

Resizes the window (logical pixels).

| Parameter | Description |
| --- | --- |
| `width` | Width. |
| `height` | Height. |
| `window` | The window (`pz.Window`). Without it, the one that produced the message. |

### `move_window`

```python
move_window(x, y, window=None)
```

Moves the window to a position on the screen.

| Parameter | Description |
| --- | --- |
| `x` | Horizontal position. |
| `y` | Vertical position. |
| `window` | The window (`pz.Window`). Without it, the one that produced the message. |

### `focus_window`

```python
focus_window(window=None)
```

Brings the window to the front and focuses it.

| Parameter | Description |
| --- | --- |
| `window` | The window (`pz.Window`). Without it, the one that produced the message. |