270 lines
7.3 KiB
HTML
270 lines
7.3 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="description" content="MontaukOS dialogs library API">
|
|
<title>Dialogs Library - MontaukOS</title>
|
|
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
<link href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600&display=swap" rel="stylesheet">
|
|
<style>
|
|
body {
|
|
font-family: 'Open Sans', Arial, sans-serif;
|
|
max-width: 960px;
|
|
margin: 0 auto;
|
|
padding: 1em;
|
|
line-height: 1.5;
|
|
display: flex;
|
|
gap: 2em;
|
|
}
|
|
p { margin: 0 0 0.5em; }
|
|
h2 { margin: 0.5em 0; }
|
|
h3 { margin: 0.75em 0 0.35em; }
|
|
.sidebar {
|
|
width: 160px;
|
|
flex-shrink: 0;
|
|
}
|
|
.sidebar ul {
|
|
list-style: none;
|
|
padding: 0;
|
|
}
|
|
.sidebar li {
|
|
margin: 0.5em 0;
|
|
}
|
|
.sidebar a {
|
|
color: #0066CC;
|
|
text-decoration: none;
|
|
font-weight: 600;
|
|
}
|
|
.sidebar a:hover {
|
|
color: #004499;
|
|
text-decoration: underline;
|
|
}
|
|
.sidebar .current {
|
|
color: #004499;
|
|
}
|
|
.sidebar hr {
|
|
border: none;
|
|
border-top: 1px solid #999;
|
|
margin: 0.75em 0;
|
|
}
|
|
.main {
|
|
flex: 1;
|
|
min-width: 0;
|
|
}
|
|
a { color: #0000EE; }
|
|
a:visited { color: #0066CC; }
|
|
hr { border-style: solid; border-width: 1px 0 0 0; border-color: #999; }
|
|
pre { background: #f0f0f0; padding: 0.5em; overflow-x: auto; }
|
|
code { background: #f0f0f0; padding: 0 0.15em; }
|
|
pre code { padding: 0; }
|
|
table {
|
|
border-collapse: collapse;
|
|
width: 100%;
|
|
margin: 0.5em 0;
|
|
}
|
|
th, td {
|
|
border: 1px solid #999;
|
|
padding: 0.35em 0.5em;
|
|
text-align: left;
|
|
vertical-align: top;
|
|
}
|
|
th { background: #f0f0f0; }
|
|
.center { text-align: center; }
|
|
.box {
|
|
border: 1px solid #999;
|
|
padding: 0.5em;
|
|
margin: 0.5em 0;
|
|
}
|
|
.figure {
|
|
margin: 0.75em 0;
|
|
}
|
|
.figure img {
|
|
display: block;
|
|
max-width: 100%;
|
|
height: auto;
|
|
border: 1px solid #999;
|
|
}
|
|
.figure p {
|
|
color: #555;
|
|
font-size: 0.9em;
|
|
margin: 0.25em 0 0;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<div class="sidebar">
|
|
<ul>
|
|
<li><a href="../../index.html">Home</a></li>
|
|
<li><a href="../index.html">Documentation</a></li>
|
|
</ul>
|
|
<hr>
|
|
<ul>
|
|
<li><a href="../introduction.html">Introduction</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="main">
|
|
<div class="center">
|
|
<h1>Dialogs</h1>
|
|
</div>
|
|
|
|
<hr>
|
|
|
|
<h2>Overview</h2>
|
|
<p>
|
|
The dialogs library (at 0:/os/libdialogs.lib) provides the following system dialogs across apps:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>File selection (Open)</li>
|
|
<li>File save location selection (Save)</li>
|
|
<li>Print setup/submission</li>
|
|
<li>Message Box popups</li>
|
|
</ul>
|
|
|
|
<h2>Message Box</h2>
|
|
<p>
|
|
<i>message_box</i> displays a popup window with text and buttons.
|
|
</p>
|
|
|
|
<pre><code>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);</code></pre>
|
|
|
|
<h3>Button Sets</h3>
|
|
<table>
|
|
<tr><th>Value</th><th>Buttons</th></tr>
|
|
<tr><td>MESSAGE_BOX_OK</td><td>OK</td></tr>
|
|
<tr><td>MESSAGE_BOX_OK_CANCEL</td><td>OK, Cancel</td></tr>
|
|
<tr><td>MESSAGE_BOX_YES_NO</td><td>Yes, No</td></tr>
|
|
<tr><td>MESSAGE_BOX_YES_NO_CANCEL</td><td>Yes, No, Cancel</td></tr>
|
|
</table>
|
|
|
|
<h3>Results</h3>
|
|
<table>
|
|
<tr><th>Value</th><th>Meaning</th></tr>
|
|
<tr><td>MESSAGE_BOX_RESULT_OK</td><td>The user selected OK.</td></tr>
|
|
<tr><td>MESSAGE_BOX_RESULT_CANCEL</td><td>The user selected Cancel or closed a cancelable dialog.</td></tr>
|
|
<tr><td>MESSAGE_BOX_RESULT_YES</td><td>The user selected Yes.</td></tr>
|
|
<tr><td>MESSAGE_BOX_RESULT_NO</td><td>The user selected No, or closed a Yes/No dialog.</td></tr>
|
|
<tr><td>MESSAGE_BOX_RESULT_NONE</td><td>The dialog could not be loaded or invoked.</td></tr>
|
|
</table>
|
|
|
|
<h3>Example</h3>
|
|
<pre><code>#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 */
|
|
}
|
|
}</code></pre>
|
|
|
|
<div class="figure">
|
|
<img src="assets/discard_dialog.png" width="337" height="181" alt="Message box asking whether to discard unsaved changes">
|
|
<p>Example <i>MESSAGE_BOX_YES_NO_CANCEL</i> dialog.</p>
|
|
</div>
|
|
|
|
<h2>File Dialogs</h2>
|
|
<p>
|
|
File dialog helpers allow applications to use graphical file selection views (similar to the Files app) to select paths for Open/Save operations.
|
|
</p>
|
|
|
|
<pre><code>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);</code></pre>
|
|
|
|
<p>
|
|
Use <code>initial_path</code> to select the starting directory or current file
|
|
context. <code>save_file</code> also accepts a <code>suggested_name</code> for
|
|
the filename field.
|
|
</p>
|
|
|
|
<h3>Open Example</h3>
|
|
<pre><code>char path[256];
|
|
char message[160];
|
|
|
|
if (gui::dialogs::open_file("Open File", "", path, sizeof(path),
|
|
message, sizeof(message))) {
|
|
/* open path */
|
|
}</code></pre>
|
|
|
|
<h3>Save Example</h3>
|
|
<pre><code>char path[256];
|
|
|
|
if (gui::dialogs::save_file("Save File", "", "untitled.txt",
|
|
path, sizeof(path))) {
|
|
/* write path */
|
|
}</code></pre>
|
|
|
|
<div class="figure">
|
|
<img src="assets/save_dialog.png" width="749" height="581" alt="Save file dialog showing folders and a filename field">
|
|
<p>Save-file dialog as used by the MontaukOS Word Processor app.</p>
|
|
</div>
|
|
|
|
<h2>Print Dialogs</h2>
|
|
<p>
|
|
Print dialog helpers allow applications to expose printer configuration to the user, and submit a file for printing.
|
|
</p>
|
|
|
|
<pre><code>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);</code></pre>
|
|
|
|
|
|
<h2>Include</h2>
|
|
<pre><code>#include <gui/dialogs.hpp></code></pre><br>
|
|
|
|
<hr>
|
|
<p class="center">Copyright © 2026 Montauk Operating System. All rights reserved.<br><br>Page last revised 26 May 2026.</p>
|
|
|
|
<hr>
|
|
|
|
<div class="center">
|
|
<a href="../index.html">Back to Documentation Index</a>
|
|
</div>
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|