Tab

Provides a class that represents an iTerm2 tab.

class Tab(connection, tab_id, root, tmux_window_id=None, tmux_connection_id=None, minimized_sessions=[], tab_group_id=None, tab_group_name=None, tab_group_color=None, tab_group_collapsed=False)

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_add_to_tab_group(group: TabGroup) → None

Adds this tab to an existing tab group.

If the tab already belonged to a different group, it is moved out of that group and into this one. iTerm2 reorders tabs so the group’s members remain consecutive.

The group must be in the same window as this tab.

Parameters:

group – The TabGroup to join.

Throws:

RPCException if something goes wrong (for example, if the group is not in this tab’s window).

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() → 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_remove_from_tab_group() → None

Removes this tab from its tab group, if any.

iTerm2 moves the tab out of the group so the remaining members stay consecutive. If the tab was the group’s only member, the group is dissolved. This is a no-op if the tab is not in a group.

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: NavigationDirection) → str | None

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: None | 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: Splitter

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: List[Session]

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

This excludes minimized sessions. Use all_sessions to get both visible and minimized sessions in this tab.

Returns:

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

property tab_group: TabGroup | None

The tab group this tab belongs to, or None if it is not in a group.

A tab group is a named, colored collection of adjacent tabs. Its members are always kept consecutive in the tab bar; iTerm2 reorders tabs as needed to maintain that invariant.

Returns:

A TabGroup or None.

property tab_id: str

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: None | str

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: Window | None

Returns the window this tab belongs to.

---

Indices and tables

• Index

• Search Page