tvision_rs/dialog/mod.rs
1//! The modal dialog window.
2//!
3//! [`Dialog`] is the view you run modally: hand it to
4//! [`exec_view`](crate::app::Program::exec_view) and it returns the command that
5//! closed it ([`Command::OK`](crate::command::Command::OK), `CANCEL`, …). It
6//! **embeds a [`Window`](crate::window::Window)** exactly as `Window` embeds a
7//! [`Group`](crate::view::Group), and forwards almost the whole
8//! [`View`](crate::view::View) trait to that window. The dialog's *own* behaviour
9//! is just three things it overrides:
10//!
11//! * **`handle_event`** — let the window handle the event first, then the dialog
12//! keys (Esc → post a Cancel command, Enter → broadcast Default) and the
13//! modal-result commands (OK / Cancel / Yes / No → end the modal loop while the
14//! dialog is modal).
15//! * **`valid`** — Cancel is *always* valid (cancelling a dialog can never be
16//! vetoed); every other command defers to the embedded group, so a control with
17//! a failing validator can keep the dialog open.
18//! * **constructor field overrides** — no grow-with-owner, decoration flags
19//! `move | close` (no grow, no zoom), and the gray dialog color scheme.
20//!
21//! The modal loop is the program's single
22//! [`pump_once`](crate::app::Program::pump_once) driven in a bounded top-level
23//! loop by [`exec_view`](crate::app::Program::exec_view); ending the modal is a
24//! downward [`Deferred::EndModal`](crate::view::Deferred) request routed to the
25//! loop owner rather than an up-pointer call.
26//!
27//! Data-bearing dialogs work today: child controls (input lines, clusters, …)
28//! carry typed values, optional [`Validator`](crate::validate::Validator)s gate
29//! focus-release and close, and the group's gather/scatter walk collects them — see
30//! [`FileDialog`] for a worked example.
31//!
32//! The layout constants ([`STD_BUTTON`], [`BUTTON_GAP`], the margins and
33//! [`BUTTON_ROW_FROM_BOTTOM`]) name the classic Turbo Vision metrics, recovered
34//! from `msgbox.cpp` and `tfildlg.cpp`, so dialogs need not invent their own
35//! coordinates. [`Dialog::button_row`] lays out a row of buttons with them.
36//!
37//! **Guide:** [Dialogs & data](../../../apps/dialogs.html).
38//!
39//! # Turbo Vision heritage
40//! Ports `TDialog` (`tdialog.cpp`/`dialogs.h`), which derived from the window
41//! class. That inheritance becomes embed-and-delegate composition (deviation D2) —
42//! the dialog holds a [`Window`](crate::window::Window) and forwards to it; the
43//! single modal loop and the downward end-modal request are deviation D9.
44
45mod colorpick;
46#[allow(clippy::module_inception)]
47mod dialog;
48mod filedlg;
49mod layout;
50mod msgbox;
51mod theme_editor;
52
53pub use colorpick::{ColorPicker, Tab};
54pub use dialog::Dialog;
55pub use filedlg::{
56 CD_HELP_BUTTON, CD_NO_LOAD_DIR, CD_NORMAL, ChDirDialog, DirCollection, DirEntry, DirListBox,
57 FA_DIREC, FD_CLEAR_BUTTON, FD_HELP_BUTTON, FD_NO_LOAD_DIR, FD_OK_BUTTON, FD_OPEN_BUTTON,
58 FD_REPLACE_BUTTON, FileCollection, FileDialog, FileInfoPane, FileInputLine, FileList,
59 SearchRec, search_rec_compare,
60};
61pub use layout::{
62 BUTTON_GAP, BUTTON_ROW_FROM_BOTTOM, ButtonLayout, ButtonRowAlign, MARGIN_LEFT, MARGIN_RIGHT,
63 MARGIN_TOP, STD_BUTTON,
64};
65pub use msgbox::{MessageBoxButtons, MessageBoxKind};
66pub(crate) use msgbox::{build_input_box, build_message_box};
67pub(crate) use theme_editor::ThemeEditorBody;