.. include:: /include/substitutions.txt
.. include:: /include/external_links.txt
.. include:: /include/custom_roles.txt
.. _popups:

******
Popups
******

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

- displays :term:`miniHTML` content, and
- overlaps part of the editing area over a view.

Popups are attached to :term:`Views <View>` 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.

.. code-block:: py

    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)