19. Dialog Boxes and User Messaging

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

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)