Window

class Window(connection, window_id, tabs, frame, number)

Represents a terminal window.

Do not create an instance of Window by calling the initializer yourself. To get a reference to an existing window, use App and query its windows property. To create a new window, use async_create().

async async_activate() → None

Gives the window keyboard focus and orders it to the front.

Note that this won’t activate the app. Use the async_activate() method on App to activate the app. You’ll probably want to call both methods.

async async_close(force: bool = False)

Closes the window.

Parameters

force (bool) – If True, the user will not be prompted for a confirmation.

Throws

RPCException if something goes wrong.

async static async_create(connection: iterm2.connection.Connection, profile: Optional[str] = None, command: Optional[str] = None, profile_customizations: Optional[iterm2.profile.LocalWriteOnlyProfile] = None) → Optional[iterm2.window.Window]

Creates a new window.

Parameters

  • connection (Connection) – A Connection.

  • profile (str) – The name of the profile to use for the new window.

  • command (str) – A command to run in lieu of the shell in the new session. Mutually exclusive with profile_customizations.

  • profile_customizations (LocalWriteOnlyProfile) – LocalWriteOnlyProfile giving changes to make in profile. Mutually exclusive with command.

Returns

A new Window or None if the session ended right away.

Throws

CreateWindowException if something went wrong.

See also

Example “Create Window — Custom Escape Sequence”

async async_create_tab(profile: Optional[str] = None, command: Optional[str] = None, index: Optional[int] = None, profile_customizations: Union[None, iterm2.profile.LocalWriteOnlyProfile] = None) → Optional[iterm2.tab.Tab]

Creates a new tab in this window.

Parameters

  • profile – The profile name to use or None for the default profile.

  • command – The command to run in the new session, or None for the default for the profile. Mutually exclusive with profile_customizations.

  • index – The index in the window where the new tab should go (0=first position, etc.)

  • profile_customizations – LocalWriteOnlyProfile giving changes to make in profile. Mutually exclusive with command.

Returns

Tab or None if the session closed right away.

Throws

CreateTabException if something goes wrong.

async async_create_tmux_tab(tmux_connection: iterm2.tmux.TmuxConnection) → Optional[iterm2.tab.Tab]

Creates a new tmux tab in this window.

This may not be called from within a Transaction.

Parameters

tmux_connection – The tmux connection to own the new tab.

Returns

A newly created tab, or None if it could not be created.

Throws

CreateTabException if something went wrong.

See also

Example “Tmux Integration”

async async_get_frame() → iterm2.util.Frame

Gets the window’s frame.

The origin (0,0) is the bottom right of the main screen.

Returns

This window’s frame. This includes window decoration such as the title bar.

Throws

GetPropertyException if something goes wrong.

async async_get_fullscreen() → bool

Checks if the window is full-screen.

Returns

Whether the window is full screen.

Throws

GetPropertyException if something goes wrong.

async async_invoke_function(invocation: str, timeout: float = - 1)

Invoke an RPC. Could be a registered function by this or another script of a built-in function.

This invokes the RPC in the context of this window. Note that most user-defined RPCs expect to be invoked in the context of a session. Default variables will be pulled from that scope. If you call a function from the wrong context it may fail because its defaults will not be set properly.

Parameters

  • invocation (str) – A function invocation string.

  • timeout (float) – Max number of secondsto wait. Negative values mean to use the system default timeout.

Returns

The result of the invocation if successful.

Throws

RPCException if something goes wrong.

async async_restore_window_arrangement(name: str) → None

Restore a window arrangement as tabs in this window.

Parameters

name (str) – The name to restore.

Throws

SavedArrangementException if the named arrangement does not exist.

async async_save_window_as_arrangement(name: str) → None

Save the current window as a new arrangement.

Parameters

name (str) – The name to save as. Will overwrite if one already exists with this name.

async async_set_frame(frame: iterm2.util.Frame) → None

Sets the window’s frame.

Parameters

frame (Frame) – The desired frame.

Throws

SetPropertyException if something goes wrong.

async async_set_fullscreen(fullscreen: bool)

Changes the window’s full-screen status.

Parameters

fullscreen (bool) – Whether you wish the window to be full screen.

Throws

SetPropertyException if something goes wrong (such as that the fullscreen status could not be changed).

async async_set_tabs(tabs: List[iterm2.tab.Tab])

Changes the tabs and their order.

The provided tabs may belong to any window. They will be moved if needed. Windows entirely denuded of tabs will be closed.

All provided tabs will be inserted in the given order starting at the first positions. Any tabs already belonging to this window not in the list will remain after the provided tabs.

Parameters

tabs – a list of tabs, forming the new set of tabs in this window.

Throws

RPCException if something goes wrong.

See also

async async_set_variable(name: str, value: Any) → None

Sets a user-defined variable in the window.

See the Scripting Fundamentals documentation for more information on user-defined variables.

Parameters

  • name (str) – The variable’s name. Must begin with user..

  • value – The new value to assign.

Throws

RPCException if something goes wrong.

property current_tab: Optional[iterm2.tab.Tab]
Returns

The current tab in this window or None if it could not be determined.

pretty_str(indent: str = '') → str
Returns

A nicely formatted string describing the window, its tabs, and their sessions.

property tabs: List[iterm2.tab.Tab]
Returns

a list of iterm2.tab.Tab objects.

property window_id: str
Returns

the window’s unique identifier.

class CreateTabException

Something went wrong creating a tab.

class SetPropertyException

Something went wrong setting a property.

class GetPropertyException

Something went wrong fetching a property.

class SavedArrangementException

A problem was encountered while saving or restoring an arrangement.

Indices and tables