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

Selects this tab.

Parameters

order_window_front (bool) – Whether the window this session is in should be brought to the front and given keyboard focus.

See also

Example “Function Key Tabs

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_move_to_window() → iterm2.window.Window

Moves this tab to its own window, provided there are multiple tabs in the window it belongs to.

Returns

The new window ID.

Throws

RPCException if something goes wrong.

async async_select(order_window_front: bool = True) → None

Deprecated in favor of async_activate.

async async_select_pane_in_direction(direction: iterm2.tab.NavigationDirection) → Optional[str]

Activates a split pane adjacent to the currently selected pane. Requires iTerm2 version 3.3.2.

Parameters

direction (NavigationDirection) – Specifies the direction to move. For example, LEFT will cause the pane to the left of the currently active one.

Returns

The ID of the newly selected session ID, or None if there was no session in that direction.

Throws

RPCException if something goes wrong.

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_connection_id

Returns the connection ID.

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