Window

Window operations including messages, dialogs, editors, and UI components.

Window

Window(client: VSCodeClient)

VS Code window operations.

Source code in vscode_sockpuppet/window.py

def __init__(self, client: VSCodeClient):
    self.client = client
    self._events = WindowEvents(client)
    self._tab_groups: Optional[TabGroups] = None
    # Expose strongly-typed Event objects on the Window namespace.
    self._on_did_change_active_text_editor: Event[TextEditorSelectionEvent] = Event(
        self.client, "window.onDidChangeActiveTextEditor"
    )
    self._on_did_change_text_editor_selection: Event[TextEditorSelectionEvent] = Event(
        self.client, "window.onDidChangeTextEditorSelection"
    )
    self._on_did_change_visible_text_editors: Event[VisibleTextEditorsEvent] = Event(
        self.client, "window.onDidChangeVisibleTextEditors"
    )
    self._on_did_open_terminal: Event[TerminalEvent] = Event(
        self.client, "window.onDidOpenTerminal"
    )
    self._on_did_close_terminal: Event[TerminalEvent] = Event(
        self.client, "window.onDidCloseTerminal"
    )
    self._on_did_change_terminal_state: Event[TerminalStateEvent] = Event(
        self.client, "window.onDidChangeTerminalState"
    )
    self._on_did_change_text_editor_visible_ranges: Event[TextEditorVisibleRangesEvent] = (
        Event(self.client, "window.onDidChangeTextEditorVisibleRanges")
    )
    self._on_did_change_text_editor_options: Event[TextEditorOptionsEvent] = Event(
        self.client, "window.onDidChangeTextEditorOptions"
    )
    self._on_did_change_text_editor_view_column: Event[TextEditorViewColumnEvent] = Event(
        self.client, "window.onDidChangeTextEditorViewColumn"
    )
    self._on_did_change_window_state: Event[WindowStateEvent] = Event(
        self.client, "window.onDidChangeWindowState"
    )

tab_groups property

tab_groups: TabGroups

Get the tab groups manager.

on_did_change_active_text_editor property

on_did_change_active_text_editor: Event[TextEditorSelectionEvent]

Event fired when the active text editor changes.

on_did_change_text_editor_selection property

on_did_change_text_editor_selection: Event[TextEditorSelectionEvent]

Event fired when the selection in an editor changes.

on_did_change_visible_text_editors property

on_did_change_visible_text_editors: Event[VisibleTextEditorsEvent]

Event fired when the visible text editors change.

on_did_open_terminal property

on_did_open_terminal: Event[TerminalEvent]

Event fired when a terminal is opened.

on_did_close_terminal property

on_did_close_terminal: Event[TerminalEvent]

Event fired when a terminal is closed.

on_did_change_terminal_state property

on_did_change_terminal_state: Event[TerminalStateEvent]

Event fired when a terminal's state changes.

on_did_change_text_editor_visible_ranges property

on_did_change_text_editor_visible_ranges: Event[TextEditorVisibleRangesEvent]

Event fired when visible ranges in an editor change.

on_did_change_text_editor_options property

on_did_change_text_editor_options: Event[dict]

Event fired when text editor options change.

on_did_change_text_editor_view_column property

on_did_change_text_editor_view_column: Event[dict]

Event fired when an editor's view column changes.

on_did_change_window_state property

on_did_change_window_state: Event[WindowStateEvent]

Event fired when the window state changes (focus).

show_information_message

show_information_message(message: str, *items: str) -> Optional[str]

Show an information message.

Parameters:

Name	Type	Description	Default
message	str	The message to show	required
*items	str	Optional items to show as buttons	()

Returns:

Type	Description
Optional[str]	The selected item or None if dismissed

Source code in vscode_sockpuppet/window.py

def show_information_message(self, message: str, *items: str) -> Optional[str]:
    """
    Show an information message.

    Args:
        message: The message to show
        *items: Optional items to show as buttons

    Returns:
        The selected item or None if dismissed
    """
    return self.client._send_request(
        "window.showInformationMessage",
        {"message": message, "items": list(items)},
    )

show_warning_message

show_warning_message(message: str, *items: str) -> Optional[str]

Show a warning message.

Parameters:

Name	Type	Description	Default
message	str	The message to show	required
*items	str	Optional items to show as buttons	()

Returns:

Type	Description
Optional[str]	The selected item or None if dismissed

Source code in vscode_sockpuppet/window.py

def show_warning_message(self, message: str, *items: str) -> Optional[str]:
    """
    Show a warning message.

    Args:
        message: The message to show
        *items: Optional items to show as buttons

    Returns:
        The selected item or None if dismissed
    """
    return self.client._send_request(
        "window.showWarningMessage",
        {"message": message, "items": list(items)},
    )

show_error_message

show_error_message(message: str, *items: str) -> Optional[str]

Show an error message.

Parameters:

Name	Type	Description	Default
message	str	The message to show	required
*items	str	Optional items to show as buttons	()

Returns:

Type	Description
Optional[str]	The selected item or None if dismissed

Source code in vscode_sockpuppet/window.py

def show_error_message(self, message: str, *items: str) -> Optional[str]:
    """
    Show an error message.

    Args:
        message: The message to show
        *items: Optional items to show as buttons

    Returns:
        The selected item or None if dismissed
    """
    return self.client._send_request(
        "window.showErrorMessage",
        {"message": message, "items": list(items)},
    )

show_quick_pick

show_quick_pick(items: list[str], options: Optional[QuickPickOptions] = None) -> Optional[str]

Show a quick pick menu.

Parameters:

Name	Type	Description	Default
items	list[str]	The items to pick from	required
options	Optional[QuickPickOptions]	Quick pick options (QuickPickOptions TypedDict)	None

Returns:

Type	Description
Optional[str]	The selected item(s) or None if dismissed

Source code in vscode_sockpuppet/window.py

def show_quick_pick(
    self, items: list[str], options: Optional[QuickPickOptions] = None
) -> Optional[str]:
    """
    Show a quick pick menu.

    Args:
        items: The items to pick from
        options: Quick pick options (QuickPickOptions TypedDict)

    Returns:
        The selected item(s) or None if dismissed
    """
    return self.client._send_request(
        "window.showQuickPick", {"items": items, "options": options or {}}
    )

show_input_box

show_input_box(options: Optional[InputBoxOptions] = None) -> Optional[str]

Show an input box.

Parameters:

Name	Type	Description	Default
options	Optional[InputBoxOptions]	Input box options (InputBoxOptions TypedDict)	None

Returns:

Type	Description
Optional[str]	The entered text or None if dismissed

Source code in vscode_sockpuppet/window.py

def show_input_box(self, options: Optional[InputBoxOptions] = None) -> Optional[str]:
    """
    Show an input box.

    Args:
        options: Input box options (InputBoxOptions TypedDict)

    Returns:
        The entered text or None if dismissed
    """
    return self.client._send_request("window.showInputBox", {"options": options or {}})

show_open_dialog

show_open_dialog(options: Optional[OpenDialogOptions] = None) -> Optional[list[str]]

Show a file open dialog to the user.

Parameters:

Name	Type	Description	Default
options	Optional[OpenDialogOptions]	Dialog options (OpenDialogOptions TypedDict)	None

Returns:

Type	Description
Optional[list[str]]	List of selected file/folder URIs, or None if canceled

Example

Select a single Python file

uris = client.window.show_open_dialog({ 'canSelectFiles': True, 'canSelectFolders': False, 'canSelectMany': False, 'filters': {'Python': ['py']}, 'title': 'Select a Python file' })

Select multiple files or folders

uris = client.window.show_open_dialog({ 'canSelectFiles': True, 'canSelectFolders': True, 'canSelectMany': True, 'title': 'Select files or folders' })

Source code in vscode_sockpuppet/window.py

def show_open_dialog(self, options: Optional[OpenDialogOptions] = None) -> Optional[list[str]]:
    """
    Show a file open dialog to the user.

    Args:
        options: Dialog options (OpenDialogOptions TypedDict)

    Returns:
        List of selected file/folder URIs, or None if canceled

    Example:
        # Select a single Python file
        uris = client.window.show_open_dialog({
            'canSelectFiles': True,
            'canSelectFolders': False,
            'canSelectMany': False,
            'filters': {'Python': ['py']},
            'title': 'Select a Python file'
        })

        # Select multiple files or folders
        uris = client.window.show_open_dialog({
            'canSelectFiles': True,
            'canSelectFolders': True,
            'canSelectMany': True,
            'title': 'Select files or folders'
        })
    """
    result = self.client._send_request("window.showOpenDialog", {"options": options or {}})
    return result.get("uris") if result else None

show_save_dialog

show_save_dialog(options: Optional[SaveDialogOptions] = None) -> Optional[str]

Show a file save dialog to the user.

Parameters:

Name	Type	Description	Default
options	Optional[SaveDialogOptions]	Dialog options (SaveDialogOptions TypedDict)	None

Returns:

Type	Description
Optional[str]	Selected save location URI, or None if canceled

Example

Save a Python file

uri = client.window.show_save_dialog({ 'filters': {'Python': ['py']}, 'title': 'Save Python file', 'saveLabel': 'Save' })

if uri: # Write to the selected location client.fs.write_text(uri, 'print("Hello")')

Source code in vscode_sockpuppet/window.py

def show_save_dialog(self, options: Optional[SaveDialogOptions] = None) -> Optional[str]:
    """
    Show a file save dialog to the user.

    Args:
        options: Dialog options (SaveDialogOptions TypedDict)

    Returns:
        Selected save location URI, or None if canceled

    Example:
        # Save a Python file
        uri = client.window.show_save_dialog({
            'filters': {'Python': ['py']},
            'title': 'Save Python file',
            'saveLabel': 'Save'
        })

        if uri:
            # Write to the selected location
            client.fs.write_text(uri, 'print("Hello")')
    """
    result = self.client._send_request("window.showSaveDialog", {"options": options or {}})
    return result.get("uri") if result else None

show_workspace_folder_pick

show_workspace_folder_pick(options: Optional[dict] = None) -> Optional[dict]

Show a workspace folder picker to the user.

Parameters:

Name	Type	Description	Default
options	Optional[dict]	Optional picker options (placeHolder, ignoreFocusOut)	None

Returns:

Type	Description
Optional[dict]	A dict with uri, name, and index for the selected folder,
Optional[dict]	or None if canceled.

Source code in vscode_sockpuppet/window.py

def show_workspace_folder_pick(self, options: Optional[dict] = None) -> Optional[dict]:
    """
    Show a workspace folder picker to the user.

    Args:
        options: Optional picker options (placeHolder, ignoreFocusOut)

    Returns:
        A dict with `uri`, `name`, and `index` for the selected folder,
        or None if canceled.
    """
    result = self.client._send_request(
        "window.showWorkspaceFolderPick", {"options": options or {}}
    )
    return result if result else None

show_text_document

show_text_document(uri: str, options: Optional[TextDocumentShowOptions] = None) -> dict

Show a text document.

Parameters:

Name	Type	Description	Default
uri	str	The URI of the document to show	required
options	Optional[TextDocumentShowOptions]	View options (TextDocumentShowOptions TypedDict)	None

Returns:

Type	Description
dict	Success status

Source code in vscode_sockpuppet/window.py

def show_text_document(
    self, uri: str, options: Optional[TextDocumentShowOptions] = None
) -> dict:
    """
    Show a text document.

    Args:
        uri: The URI of the document to show
        options: View options (TextDocumentShowOptions TypedDict)

    Returns:
        Success status
    """
    return self.client._send_request(
        "window.showTextDocument", {"uri": uri, "options": options or {}}
    )

visible_text_editors

visible_text_editors() -> list[dict]

Get a list of currently visible text editors.

Returns:

Type	Description
list[dict]	A list of dicts with uri, viewColumn, and selection info.

Source code in vscode_sockpuppet/window.py

def visible_text_editors(self) -> list[dict]:
    """
    Get a list of currently visible text editors.

    Returns:
        A list of dicts with `uri`, `viewColumn`, and `selection` info.
    """
    return self.client._send_request("window.visibleTextEditors", {})

get_state

get_state() -> WindowState

Get the current window state (focused flag).

Returns:

Type	Description
WindowState	A dict with focused boolean indicating window focus.

Source code in vscode_sockpuppet/window.py

def get_state(self) -> WindowState:
    """
    Get the current window state (focused flag).

    Returns:
        A dict with `focused` boolean indicating window focus.
    """
    return self.client._send_request("window.state", {})

create_output_channel

create_output_channel(name: str, text: Optional[str] = None, show: bool = False, preserve_focus: bool = True) -> dict

Create an output channel.

Parameters:

Name	Type	Description	Default
name	str	The name of the output channel	required
text	Optional[str]	Optional text to append	None
show	bool	Whether to show the channel	False
preserve_focus	bool	Whether to preserve focus when showing	True

Returns:

Type	Description
dict	Success status

Source code in vscode_sockpuppet/window.py

def create_output_channel(
    self,
    name: str,
    text: Optional[str] = None,
    show: bool = False,
    preserve_focus: bool = True,
) -> dict:
    """
    Create an output channel.

    Args:
        name: The name of the output channel
        text: Optional text to append
        show: Whether to show the channel
        preserve_focus: Whether to preserve focus when showing

    Returns:
        Success status
    """
    return self.client._send_request(
        "window.createOutputChannel",
        {
            "name": name,
            "text": text,
            "show": show,
            "preserveFocus": preserve_focus,
        },
    )

create_terminal

create_terminal(name: Optional[str] = None, shell_path: Optional[str] = None, shell_args: Optional[list] = None) -> Terminal

Create a terminal.

Parameters:

Name	Type	Description	Default
name	Optional[str]	The name of the terminal	None
shell_path	Optional[str]	Path to the shell executable	None
shell_args	Optional[list]	Arguments for the shell	None

Returns:

Type	Description
Terminal	Terminal instance for interacting with the terminal

Example

Create a simple terminal

terminal = window.create_terminal(name="My Terminal")

Create with custom shell

terminal = window.create_terminal( name="Bash", shell_path="/bin/bash" )

Use the terminal

terminal.send_text("echo 'Hello!'") terminal.show()

Source code in vscode_sockpuppet/window.py

def create_terminal(
    self,
    name: Optional[str] = None,
    shell_path: Optional[str] = None,
    shell_args: Optional[list] = None,
) -> Terminal:
    """
    Create a terminal.

    Args:
        name: The name of the terminal
        shell_path: Path to the shell executable
        shell_args: Arguments for the shell

    Returns:
        Terminal instance for interacting with the terminal

    Example:
        # Create a simple terminal
        terminal = window.create_terminal(name="My Terminal")

        # Create with custom shell
        terminal = window.create_terminal(
            name="Bash",
            shell_path="/bin/bash"
        )

        # Use the terminal
        terminal.send_text("echo 'Hello!'")
        terminal.show()
    """
    from .terminal import Terminal

    result = self.client._send_request(
        "window.createTerminal",
        {
            "name": name,
            "shellPath": shell_path,
            "shellArgs": shell_args,
        },
    )
    return Terminal(self.client, result["terminalId"], name)

set_status_bar_message

set_status_bar_message(text: str, hide_after_timeout: Optional[int] = None) -> dict

Set a status bar message.

Parameters:

Name	Type	Description	Default
text	str	The message to show	required
hide_after_timeout	Optional[int]	Optional timeout in milliseconds	None

Returns:

Type	Description
dict	Success status

Source code in vscode_sockpuppet/window.py

def set_status_bar_message(self, text: str, hide_after_timeout: Optional[int] = None) -> dict:
    """
    Set a status bar message.

    Args:
        text: The message to show
        hide_after_timeout: Optional timeout in milliseconds

    Returns:
        Success status
    """
    return self.client._send_request(
        "window.setStatusBarMessage",
        {"text": text, "hideAfterTimeout": hide_after_timeout},
    )

create_webview_panel

create_webview_panel(title: str, html: str, view_type: Optional[str] = None, panel_id: Optional[str] = None, show_options: int = 1, options: Optional[WebviewOptions] = None) -> WebviewPanel

Create a webview panel with custom HTML content.

Parameters:

Name	Type	Description	Default
title	str	The title of the webview panel	required
html	str	The HTML content to display	required
view_type	Optional[str]	Identifier for the webview type (auto-generated if None)	None
panel_id	Optional[str]	Unique identifier for the panel (auto-generated if None)	None
show_options	int	ViewColumn where to show (1=One, 2=Two, 3=Three)	1
options	Optional[WebviewOptions]	Webview configuration options	None

Returns:

Type	Description
WebviewPanel	The created WebviewPanel instance

Example

with window.create_webview_panel( "My Panel", "

Hello from Python!

" ) as panel: # Panel will automatically dispose when exiting context panel.update_html("

Updated content

")

Source code in vscode_sockpuppet/window.py

def create_webview_panel(
    self,
    title: str,
    html: str,
    view_type: Optional[str] = None,
    panel_id: Optional[str] = None,
    show_options: int = 1,
    options: Optional[WebviewOptions] = None,
) -> WebviewPanel:
    """
    Create a webview panel with custom HTML content.

    Args:
        title: The title of the webview panel
        html: The HTML content to display
        view_type: Identifier for the webview type (auto-generated if None)
        panel_id: Unique identifier for the panel (auto-generated if None)
        show_options: ViewColumn where to show (1=One, 2=Two, 3=Three)
        options: Webview configuration options

    Returns:
        The created WebviewPanel instance

    Example:
        with window.create_webview_panel(
            "My Panel",
            "<h1>Hello from Python!</h1>"
        ) as panel:
            # Panel will automatically dispose when exiting context
            panel.update_html("<h1>Updated content</h1>")
    """
    from .webview import WebviewOptions, WebviewPanel

    if panel_id is None:
        panel_id = str(uuid.uuid4())

    if view_type is None:
        view_type = f"sockpuppet.webview.{panel_id}"

    params = {
        "id": panel_id,
        "viewType": view_type,
        "title": title,
        "showOptions": show_options,
        "html": html,
    }

    if options:
        params["options"] = options.to_dict()
    else:
        # Default options
        params["options"] = WebviewOptions().to_dict()

    # If scripts are enabled for this webview, inject a tiny handshake
    # snippet which posts { type: 'ready' } back to Python once the
    # document is interactive/loaded. This helps prevent races where
    # Python posts messages before the webview JS has installed its
    # message listener. We avoid double-injecting by checking for a
    # unique marker.
    try:
        _inject_ready_handshake(params)
    except Exception:
        # Be conservative: if anything goes wrong, fall back to sending
        # the original HTML unchanged.
        pass

    result = self.client._send_request("window.createWebviewPanel", params)

    panel = WebviewPanel(self.client, panel_id, view_type, title)
    try:
        # Server returns initial visible/active state
        panel._visible = bool(result.get("visible", False))
        panel._active = bool(result.get("active", False))
    except Exception:
        # Ignore if result malformatted
        pass

    return panel