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=[])

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: Union[None, iterm2.session.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: iterm2.session.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[iterm2.session.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_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: Union[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: Optional[iterm2.window.Window]

Returns the window this tab belongs to.

Indices and tables