Command

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 guide.

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

exit()

Closes the application.

focus

focus(id)

Focuses the text_input (or editor) with that id.

Parameter	Description
id	The id you passed to the widget.

focus_next

focus_next()

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

focus_previous

focus_previous()

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

select_all

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

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

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

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

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

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

editor_actions()

The names Command.editor_action accepts.

select_editor_ranges

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

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

scroll_to_end(id)

Scrolls the scrollable with that id to the end.

Parameter	Description
id	The scrollable’s id.

batch

batch(commands)

Runs several commands.

Parameter	Description
commands	List of Command.

message

message(message)

Sends message to update again on the next cycle.

Parameter	Description
message	Any Python value, or a callable.

perform

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).

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

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

copy(text)

Copies text to the system clipboard.

Parameter	Description
text	The text.

paste

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

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

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

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

open_window(window)

Opens a new window for that pz.Window instance.

Parameter	Description
window	The window.

close_window

close_window(window=None)

Closes the window.

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

drag_window

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

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

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

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

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

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

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

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

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

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.