Tab

Provides a class that represents an iTerm2 tab.

class Tab(connection, tab_id, root, tmux_window_id=None, tmux_connection_id=None)

Represents a tab.

Don’t create this yourself. Instead, use App.

async async_close(force: bool = False) → None

Closes the tab.

Parameters

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

Throws

RPCException if something goes wrong.

See also

Example “Close Tabs to the Right

async async_get_variable(name: str) → Any

Fetches a tab variable.

See Badges documentation for more information on variables.

Parameters

name (str) – The variable’s name.

Returns

The variable’s value or None if it is undefined.

Throws

RPCException if something goes wrong.

See also

Example “Sort Tabs

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 tab. 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_select(order_window_front: bool = True) → None

Deprecated in favor of async_activate.

async async_set_title(title: str)

Changes the tab’s title.

This is equivalent to editing the tab’s title with the menu item Edit Tab Title. The title is an interpolated string.

Parameters

title (str) – The new title. Set it to an empty string to use the default value (the current session’s title).

Throws

RPCException if something goes wrong.

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

Sets a user-defined variable in the tab.

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.

async async_update_layout() → None

Adjusts the layout of the sessions in this tab.

Change the Session.preferred_size of any sessions you wish to adjust before calling this.

Throws

RPCException if something goes wrong.

property current_session
Returns

The active session in this tab or None if it could not be determined.

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

A human readable description of the tab and its sessions.

property root

A tab’s sessions are stored in a tree. This returns the root of that tree.

An interior node of the tree is a Splitter. That corresponds to a collection of adjacent sessions with split pane dividers that are all either vertical or horizontal.

Leaf nodes are Sessions.

Returns

The root of the session tree.

property sessions

A tab contains a list of sessions, which are its split panes.

Returns

The sessions belonging to this tab, in no particular order.

property tab_id

Each tab has a globally unique identifier.

Returns

The tab’s identifier, a string.

property tmux_window_id

Returns this tab’s tmux window id or None.

Returns

A tmux window id or None if this is not a tmux integration window.

property window

Returns the window this tab belongs to.


Indices and tables