Status Bar¶

Status bar customization interfaces.

class StatusBarComponent(short_description: str, detailed_description: str, knobs: List[iterm2.statusbar.Knob], exemplar: str, update_cadence: Optional[float], identifier: str, icons: List[iterm2.statusbar.StatusBarComponent.Icon] = [], format: iterm2.statusbar.StatusBarComponent.Format = <Format.PLAIN_TEXT: 0>)¶

Describes a script-provided status bar component showing a text value provided by a user-provided coroutine.

Parameters

short_description – Short description shown below the component in the picker UI.
detailed_description – Tool tip for the component in the picker UI.
knobs – List of configuration knobs. See the various Knob classes for details.
exemplar – Example value to show in the picker UI as the sample content of the component.
update_cadence – How frequently in seconds to reload the value, or None if it does not need to be reloaded on a timer.
identifier – A string uniquely identifying this component. Use a backwards domain name. For example, com.example.calculator for a calculator component provided by example.com.
icons – An array of StatusBarComponent.Icon objects. Should contain one with scale 1 and one with scale 2, of size 16x17 points. May be empty if you don’t want an icon.

async async_register(connection: iterm2.connection.Connection, coro, timeout: Union[None, float] = None, onclick: Optional[Callable[[str, Any], Coroutine[Any, Any, None]]] = None)¶

Registers the statusbar component.

Parameters

connection (Connection) – A Connection.
coro – An async function. Its arguments are reflected upon to determine the RPC’s signature. Only the names of the arguments are used. All arguments should be keyword arguments as any may be omitted at call time. It should take a special argument named “knobs” that is a dictionary with configuration settings. It may return a string or a list of strings. If it returns a list of strings then the longest one that fits will be used.
timeout – How long iTerm2 should wait before giving up on this function’s ever returning. None means to use the default timeout.
onclick – A coroutine to run when the user clicks on the status bar component. It should take one argument, which is the session_id of the session owning the status bar component that was clicked on.

Example:

component = iterm2.StatusBarComponent(
    short_description = "Session ID",
    detailed_description = "Show the session's identifier",
    knobs = [],
    exemplar = "[session ID]",
    update_cadence = None,
    identifier = "com.iterm2.example.statusbar-rpc")

@iterm2.StatusBarRPC
async def session_id_status_bar_coro(
        knobs,
        session_id = iterm2.Reference("id")):
    # This status bar component shows the current session ID,
    # which is useful for debugging scripts.
    return session_id

@iterm2.RPC
async def my_status_bar_click_handler(session_id):
    # When you click the status bar it opens a popover with the
    # message "Hello World"
    await component.async_open_popover(
            session_id,
            "Hello world",
            iterm2.Size(200, 200))

await component.async_register(
        connection,
        session_id_status_bar_coro,
        onclick = my_status_bar_click_handler)

class CheckboxKnob(name: str, default_value: bool, key: str)¶

A status bar configuration knob to select a checkbox.

Parameters

name – Description of the knob.
default_value – Default value (Boolean).
key – A unique string key identifying this knob.

class StringKnob(name: str, placeholder: str, default_value: str, key: str)¶

A status bar configuration knob to select a string.

Parameters

name – Description of the knob.
placeholder – Placeholder value (shown in gray) for the text field when it has no content.
default_value – Default value.
key – A unique string key identifying this knob.

class PositiveFloatingPointKnob(name: str, default_value: float, key: str)¶

A status bar configuration knob to select a positive floating point value.

Parameters

name – Description of the knob.
default_value – Default value.
key – A unique string key identifying this knob.

class ColorKnob(name: str, default_value: iterm2.color.Color, key: str)¶

A status bar configuration knob to select color.

Parameters

name – Description of the knob.
default_value – Default value.
key – A unique string key identifying this knob

class Icon(scale: float, base64_data: str)¶

Contains a status bar icon.

The scale gives the ratio between pixels and points. For example, a 32x34 image with scale 2 has a size of 16x17 points.

Status bar icons should be 16x17 points. Use a two point margin around the edges. The text baseline is 3.5 points up from the bottom of the image.

Parameters

scale – 2 for a retina (high-DPI) image, or 1 for a regular (low-DPI) image.
base64_data – Base64-encoded data with the icon’s image in PNG format.

Status Bar¶

Indices and tables¶