# Dialogs

## Overview

The dialogs library (at 0:/os/dialogs.lib) provides the following system dialogs across apps:

- File selection (Open)
- File save location selection (Save)
- Print setup/submission
- Message Box popups

## Message Box

message_box displays a popup window with text and buttons.

    gui::dialogs::MessageBoxResult message_box(
        const char* title,
        const char* message,
        gui::dialogs::MessageBoxButtons buttons = gui::dialogs::MESSAGE_BOX_OK,
        char* out_message = nullptr,
        int out_message_len = 0);

### Button Sets

Value | Buttons
--- | ---
MESSAGE_BOX_OK | OK
MESSAGE_BOX_OK_CANCEL | OK, Cancel
MESSAGE_BOX_YES_NO | Yes, No
MESSAGE_BOX_YES_NO_CANCEL | Yes, No, Cancel

### Results

Value | Meaning
--- | ---
MESSAGE_BOX_RESULT_OK | The user selected OK.
MESSAGE_BOX_RESULT_CANCEL | The user selected Cancel or closed a cancelable dialog.
MESSAGE_BOX_RESULT_YES | The user selected Yes.
MESSAGE_BOX_RESULT_NO | The user selected No, or closed a Yes/No dialog.
MESSAGE_BOX_RESULT_NONE | The dialog could not be loaded or invoked.

### Example

    #include <gui/dialogs.hpp>

    void show_confirm() {
        auto result = gui::dialogs::message_box(
            "Close Document",
            "Discard unsaved changes?",
            gui::dialogs::MESSAGE_BOX_YES_NO_CANCEL);

        if (result == gui::dialogs::MESSAGE_BOX_RESULT_YES) {
            /* discard and close */
        }
    }

Example MESSAGE_BOX_YES_NO_CANCEL dialog.

## File Dialogs

File dialog helpers allow applications to use graphical file selection views (similar to the Files app) to select paths for Open/Save operations.

    bool open_file(
        const char* title,
        const char* initial_path,
        char* out_path,
        int out_path_len,
        char* out_message = nullptr,
        int out_message_len = 0);

    bool save_file(
        const char* title,
        const char* initial_path,
        const char* suggested_name,
        char* out_path,
        int out_path_len,
        char* out_message = nullptr,
        int out_message_len = 0);

Use `initial_path` to select the starting directory or current file context. `save_file` also accepts a `suggested_name` for the filename field.

### Open Example

    char path[256];
    char message[160];

    if (gui::dialogs::open_file("Open File", "", path, sizeof(path),
                                message, sizeof(message))) {
        /* open path */
    }

### Save Example

    char path[256];

    if (gui::dialogs::save_file("Save File", "", "untitled.txt",
                                path, sizeof(path))) {
        /* write path */
    }

Save-file dialog as used by the MontaukOS Word Processor app.

## Print Dialogs

Print dialog helpers allow applications to expose printer configuration to the user, and submit a file for printing.

    bool configure_print(
        const char* title,
        const char* initial_printer_uri,
        const char* job_name,
        char* out_printer_uri,
        int out_printer_uri_len,
        char* out_printer_name,
        int out_printer_name_len,
        uint32_t* out_copies = nullptr,
        char* out_message = nullptr,
        int out_message_len = 0);

    bool print_file(
        const char* title,
        const char* source_path,
        const char* job_name,
        char* out_job_id,
        int out_job_id_len,
        char* out_message = nullptr,
        int out_message_len = 0);

## Include

    #include <gui/dialogs.hpp>

Copyright © 2026 Montauk Operating System Project. All rights reserved.
Page last revised 26 May 2026.

Back to Documentation Index