.. include:: /include/substitutions.txt
.. include:: /include/external_links.txt
.. include:: /include/custom_roles.txt
.. _dialog boxes and user messaging:

*******************************
Dialog Boxes and User Messaging
*******************************

The following are the different dialog-box-related functions in ``sublime.py`` (as of
build 4200):

.. code-block:: py

    def status_message(msg: str):
        """ Show a message in the status bar. """
        sublime_api.status_message(msg)


    def error_message(msg: str):
        """ Display an error dialog. """
        sublime_api.error_message(msg)


    def message_dialog(msg: str):
        """ Display a message dialog. """
        sublime_api.message_dialog(msg)


    def ok_cancel_dialog(msg: str, ok_title="", title="") -> bool:
        """
        Show a *ok / cancel* question dialog.

        :param msg: The message to show in the dialog.
        :param ok_title: Text to display on the *ok* button.
        :param title: Title for the dialog. Windows only. :since:`4099`

        :returns: Whether the user pressed the *ok* button.
        """
        return sublime_api.ok_cancel_dialog(msg, title, ok_title)


    def yes_no_cancel_dialog(msg: str, yes_title="", no_title="", title="") -> DialogResult:
        """
        Show a *yes / no / cancel* question dialog.

        :param msg: The message to show in the dialog.
        :param yes_title: Text to display on the *yes* button.
        :param no_title: Text to display on the *no* button.
        :param title: Title for the dialog. Windows only. :since:`4099`
        """
        return DialogResult(sublime_api.yes_no_cancel_dialog(msg, title, yes_title, no_title))


    def open_dialog(
            callback: Callable[[str | list[str] | None], None],
            file_types: list[tuple[str, list[str]]] = [],
            directory: Optional[str] = None,
            multi_select=False,
            allow_folders=False):
        """
        Show the open file dialog.

        .. since:: 4075

        :param callback: Called with selected path(s) or ``None`` once the dialog is closed.
        :param file_types: A list of allowed file types, consisting of a description
                           and a list of allowed extensions.
        :param directory: The directory the dialog should start in.  Will use the
                          virtual working directory if not provided.
        :param multi_select: Whether to allow selecting multiple files. When ``True``
                             the callback will be called with a list.
        :param allow_folders: Whether to also allow selecting folders. Only works on
                              macOS. If you only want to select folders use
                              `select_folder_dialog`.
        """
        flags = 0
        if multi_select:
            flags |= 1
        if allow_folders:
            flags |= 2

        if not multi_select:
            def cb(files):
                return callback(files[0] if files else None)
        else:
            cb = callback

        sublime_api.open_dialog(file_types, directory or '', flags, cb)


    def save_dialog(
            callback: Callable[[str | None], None],
            file_types: list[tuple[str, list[str]]] = [],
            directory: Optional[str] = None,
            name: Optional[str] = None,
            extension: Optional[str] = None):
        """
        Show the save file dialog

        .. since:: 4075

        :param callback: Called with selected path or ``None`` once the dialog is closed.
        :param file_types: A list of allowed file types, consisting of a description
                           and a list of allowed extensions.
        :param directory: The directory the dialog should start in.  Will use the
                          virtual working directory if not provided.
        :param name: The default name of the file in the save dialog.
        :param extension: The default extension used in the save dialog.
        """
        sublime_api.save_dialog(file_types, directory or '', name or '', extension or '', callback)


    def select_folder_dialog(
            callback: Callable[[str | list[str] | None], None],
            directory: Optional[str] = None,
            multi_select=False):
        """
        Show the select folder dialog.

        .. since:: 4075

        :param callback: Called with selected path(s) or ``None`` once the dialog is closed.
        :param directory: The directory the dialog should start in.  Will use the
                          virtual working directory if not provided.
        :param multi_select: Whether to allow selecting multiple files. When ``True``
                             the callback will be called with a list.
        """
        if not multi_select:
            def cb(folders):
                return callback(folders[0] if folders else None)
        else:
            cb = callback

        sublime_api.select_folder_dialog(directory or '', multi_select, cb)


    def choose_font_dialog(callback: Callable[[Value], None], default: dict[str, Value] = None):
        """
        Show a dialog for selecting a font.

        .. since:: 4157

        :param callback: Called with the font options, matching the format used in
                         settings (eg. ``{ "font_face": "monospace" }``). May be
                         called more than once, or will be called with ``None`` if
                         the dialog is cancelled.
        :param default: The default values to select/return. Same format as the
                        argument passed to `callback`.
        """
        font_face: Value = ''
        font_size: Value = None
        if default is not None:
            font_face = default.get("font_face") or ""
            try:
                font_size = int(default.get("font_size"))  # type: ignore
            except ValueError:
                font_size = None

        sublime_api.choose_font_dialog(callback, font_face, font_size)