25. Popups

Sublime Text has a feature you can use from within Plugins that creates an overlay that:

• displays miniHTML content, and

• overlaps part of the editing area over a view.

Popups are attached to Views and thus, the API to use them is also a set of methods in the sublime.View class, shown below with class PopupFlags used by the sublime.View.show_popup() method.

class PopupFlags(enum.IntFlag):
    """
    Flags for use with popups.

    See `View.show_popup`.
    """
    NONE = 0
    """ """
    COOPERATE_WITH_AUTO_COMPLETE = 2
    """ Causes the popup to display next to the auto complete menu. """
    HIDE_ON_MOUSE_MOVE = 4
    """
    Causes the popup to hide when the mouse is moved, clicked or scrolled.
    """
    HIDE_ON_MOUSE_MOVE_AWAY = 8
    """
    Causes the popup to hide when the mouse is moved (unless towards the popup),
    or when clicked or scrolled.
    """
    KEEP_ON_SELECTION_MODIFIED = 16
    """
    Prevent the popup from hiding when the selection is modified.
    """
    HIDE_ON_CHARACTER_EVENT = 32
    """
    Hide the popup when a character is typed.
    """

# . . .

class View:

    # . . .

    def show_popup_menu(self, items: list[str], on_done: Callable[[int], None], flags=0):
        """
        Show a popup menu at the caret, for selecting an item in a list.

        :param items: The list of entries to show in the list.
        :param on_done: Called once with the index of the selected item. If the
                        popup was cancelled ``-1`` is passed instead.
        :param flags: must be ``0``, currently unused.
        """
        return sublime_api.view_show_popup_table(self.view_id, items, on_done, flags, -1)

    def show_popup(self, content: str, flags=PopupFlags.NONE, location: Point = -1,
                   max_width: DIP = 320, max_height: DIP = 240,
                   on_navigate: Optional[Callable[[str], None]] = None,
                   on_hide: Optional[Callable[[], None]] = None):
        """
        Show a popup displaying HTML content.

        :param content: The HTML content to display.
        :param flags: Flags controlling popup behavior. See `PopupFlags`.
        :param location: The `Point` at which to display the popup. If ``-1``
                         the popup is shown at the current postion of the caret.
        :param max_width: The maximum width of the popup.
        :param max_height: The maximum height of the popup.
        :param on_navigate:
            Called when a link is clicked in the popup. Passed the value of the
            ``href`` attribute of the clicked link.
        :param on_hide: Called when the popup is hidden.
        """
        sublime_api.view_show_popup(
            self.view_id, location, content, flags, max_width, max_height,
            on_navigate, on_hide)

    def update_popup(self, content: str):
        """
        Update the content of the currently visible popup.
        """
        sublime_api.view_update_popup_content(self.view_id, content)

    def is_popup_visible(self) -> bool:
        """
        :returns: Whether a popup is currently shown.
        """
        return sublime_api.view_is_popup_visible(self.view_id)

    def hide_popup(self):
        """
        Hide the current popup.
        """
        sublime_api.view_hide_popup(self.view_id)

    def is_auto_complete_visible(self) -> bool:
        """
        :returns: Whether the auto-complete menu is currently visible.
        """
        return sublime_api.view_is_auto_complete_visible(self.view_id)

    def preserve_auto_complete_on_focus_lost(self):
        """
        Sets the auto complete popup state to be preserved the next time the
        `View` loses focus. When the `View` regains focus, the auto complete
        window will be re-shown, with the previously selected entry
        pre-selected.
        """
        sublime_api.view_preserve_auto_complete_on_focus_lost(self.view_id)