Dialog Library

Common dialogs for file operations, confirmations, and user input

The Dialog library provides reusable UI dialogs for common interactions like file selection, confirmations, text input, and alerts. All dialogs integrate with the application window system.

Loading the Library

local Dialog = require("Dialog")

Dialog.fileOpen(startPath, options)

Creates a file picker dialog for selecting files to open. Displays a navigable directory listing with visual distinction between files and directories.

Parameters

Parameter	Type	Description
`startPath`	string	Starting directory path (default: "/")
`options.app`	Application	Required. Application instance
`options.fs`	SafeFS	SafeFS instance for adding allowed paths when file is selected
`options.title`	string	Dialog title (default: "Open File")
`options.width`	number	Dialog width in pixels (default: 400)
`options.height`	number	Dialog height in pixels (default: 300)

Returns

Dialog object with methods: openDialog(callback), onSuccess(callback), onCancel(callback), show(), close()

Example

local dialog = Dialog.fileOpen("/home", { app = app, fs = fs })
dialog:openDialog(function(path)
    if path then
        print("Selected: " .. path)
        local content = fs:read(path)
    else
        print("Cancelled")
    end
end)

Dialog.fileSave(startPath, defaultName, options)

Creates a file save dialog with a filename input field. Users can navigate directories and type a filename for saving.

Parameters

Parameter	Type	Description
`startPath`	string	Starting directory path (default: "/")
`defaultName`	string	Default filename (default: "untitled")
`options.app`	Application	Required. Application instance
`options.fs`	SafeFS	SafeFS instance for adding allowed paths
`options.title`	string	Dialog title (default: "Save File")
`options.width`	number	Dialog width (default: 400)
`options.height`	number	Dialog height (default: 350)

Example

local dialog = Dialog.fileSave("/home/Documents", "document.txt", { app = app })
dialog:openDialog(function(path)
    if path then
        fs:write(path, "File contents here")
    end
end)

Dialog.confirm(message, yesText, noText, options)

Creates a confirmation dialog with two buttons. Useful for destructive actions or important decisions.

Parameters

Parameter	Type	Description
`message`	string	Message to display (default: "Confirm?")
`yesText`	string	Text for confirm button (default: "Yes")
`noText`	string	Text for cancel button (default: "No")
`options.app`	Application	Required. Application instance
`options.title`	string	Dialog title (default: "Confirm")
`options.width`	number	Dialog width (default: 300)
`options.height`	number	Dialog height (default: 150)

Returns

Dialog object with methods: openDialog(callback), onYes(callback), onNo(callback), show(), close()

Example

local dialog = Dialog.confirm("Delete this file?", "Delete", "Cancel", { app = app })
dialog:openDialog(function(confirmed)
    if confirmed then
        fs:remove(filePath)
    end
end)

Dialog.prompt(message, autocompleteValues, options)

Creates a text input dialog with optional autocomplete suggestions. Suggestions are filtered as the user types.

Parameters

Parameter	Type	Description
`message`	string	Prompt message (default: "Enter value:")
`autocompleteValues`	table	Array of strings for autocomplete suggestions (optional)
`options.app`	Application	Required. Application instance
`options.title`	string	Dialog title (default: "Prompt")
`options.width`	number	Dialog width (default: 350)
`options.height`	number	Dialog height (default: 200)

Example

-- Simple prompt
local dialog = Dialog.prompt("Enter your name:", nil, { app = app })
dialog:openDialog(function(text)
    if text then
        print("Hello, " .. text)
    end
end)

-- With autocomplete
local colors = {"Red", "Green", "Blue", "Yellow"}
local dialog = Dialog.prompt("Pick a color:", colors, { app = app })
dialog:openDialog(function(color)
    if color then
        setBackgroundColor(color)
    end
end)

Dialog.promptPassword(message, options)

Creates a password input dialog that masks input with asterisks. Identical to prompt but hides typed characters.

Parameters

Parameter	Type	Description
`message`	string	Prompt message (default: "Enter password:")
`options.app`	Application	Application instance (uses sandbox app if not provided)
`options.title`	string	Dialog title (default: "Password")

Example

local dialog = Dialog.promptPassword("Enter your password:", { app = app })
dialog:openDialog(function(password)
    if password then
        authenticate(username, password)
    end
end)

Dialog.alert(message, options)

Creates an instant alert dialog with just an OK button. Unlike other dialogs, it shows immediately without needing to call openDialog().

Parameters

Parameter	Type	Description
`message`	string	Message to display (default: "Alert")
`options.app`	Application	Application instance (uses sandbox app if not provided)
`options.title`	string	Dialog title (default: "Alert")
`options.width`	number	Dialog width (default: 300)
`options.height`	number	Dialog height (default: 150)

Returns

Dialog object with close() method

Example

-- Shows immediately
Dialog.alert("Operation completed!", { app = app, title = "Success" })

-- Can also store reference to close programmatically
local alertDialog = Dialog.alert("Processing...", { app = app })
-- Later:
alertDialog:close()

Dialog.html(html, options)

Creates a dialog that renders HTML content using the moon browser engine. HTML scripts have access to the calling process's environment via window.env.

Parameters

Parameter	Type	Description
`html`	string	Required. HTML string to render
`options.app`	Application	Application instance (uses sandbox app if not provided)
`options.title`	string	Dialog title (default: "HTML Dialog")
`options.width`	number	Dialog width (default: 400)
`options.height`	number	Dialog height (default: 200)
`options.env`	table	Environment table exposed to HTML scripts as `window.env`
`options.onClose`	function	Callback when dialog is closed

HTML Script Environment

Scripts in the HTML have access to:

window.env - The environment table passed in options
window.close() - Close the dialog
window.alert(msg) - Show an alert
window.width / window.height - Dialog dimensions
document.close() - Close the dialog

Example

local html = [[
<html>
<body style="background:#2c2c2c; color:white; padding:20px;">
    <h2>Welcome</h2>
    <p>Click the button below:</p>
    <button onclick="window.env.onButtonClick(); window.close()">
        Click Me
    </button>
</body>
</html>
]]

local dialog = Dialog.html(html, {
    app = app,
    title = "Custom Dialog",
    width = 300,
    height = 200,
    env = {
        onButtonClick = function()
            print("Button was clicked!")
        end
    }
})

Dialog.customDialog(...)

Creates a dynamic dialog with mixed content based on arguments. Supports labels, text inputs, number inputs, password fields, checkboxes, and buttons.

Argument Types

Argument	Description
`"STRING"`	Text input field
`"NUMBER"`	Number-only input field
`"PASSWORD"`	Password input (masked with asterisks)
`"BOOLEAN"`	Checkbox
`"\n"`	Line break (new row)
`"BUTTON=Label"`	Button with the specified label
Any other string	Text label

Callback

The last argument must be a callback function. It receives all input values in order, followed by the clicked button label.

Callback return values:

nil or no return - Close the dialog
true - Keep the dialog open
number - Clear the input at that index and focus it (for validation)

Example

Dialog.customDialog(
    "Name:", "STRING", "\n",
    "Age:", "NUMBER", "\n",
    "Password:", "PASSWORD", "\n",
    "Remember me:", "BOOLEAN", "\n",
    "BUTTON=Cancel", "BUTTON=Login",
    { app = app, title = "Login" },
    function(name, age, password, remember, buttonClicked)
        if buttonClicked == "Cancel" then
            return -- Close dialog
        end

        if name == "" then
            return 1 -- Clear and focus first input
        end

        if password == "" then
            return 3 -- Clear and focus password input
        end

        -- Process login...
        print("Logging in as: " .. name)
    end
):show()

Dialog Patterns

New Pattern (Recommended)

Use openDialog(callback) for a single callback that receives the result:

Dialog.confirm("Save changes?", "Save", "Discard", { app = app })
    :openDialog(function(result)
        if result then
            saveDocument()
        end
    end)

Old Pattern

Use separate onSuccess/onCancel or onYes/onNo callbacks:

local dialog = Dialog.confirm("Delete?", "Yes", "No", { app = app })
dialog:onYes(function()
    deleteItem()
    dialog:close()
end)
dialog:onNo(function()
    dialog:close()
end)
dialog:show()