Guide API
Skip to main content

Dialog

Struct Dialog 

Source
pub struct Dialog { /* private fields */ }
Expand description

A modal dialog window: a Window with dialog-specific field overrides and the Esc/Enter/ok-cancel key handling.

Build with Dialog::new, then run it modally via Program::exec_view. See the module docs for the overview.

§Turbo Vision heritage

Ports TDialog (tdialog.cpp/dialogs.h), which derived from the window class. That inheritance is embed-and-delegate composition (deviation D2): the dialog holds a Window and forwards to it.

Implementations§

Source§

impl Dialog

Source

pub fn new(bounds: Rect, title: Option<String>) -> Self

Construct the dialog over bounds with an optional title.

Use Dialog instead of Window whenever the view will be run modally via Program::exec_view: the dialog sets sensible modal defaults (gray scheme, move+close decoration, no number, no grow-with-owner) and wires the Esc/Enter/OK/Cancel key handling so the caller gets a result command back without writing any extra event logic.

After construction, populate the dialog with insert_child or the convenience helper button_row, then pass the Dialog to exec_view.

The four overrides applied here:

  • Window number 0 — no number is drawn in the title bar.
  • Decoration flags move | close (no grow, no zoom) — the frame shows a close icon but neither a grow handle nor a zoom icon.
  • GrowMode all-zero — the dialog does not track its owner’s resize.
  • WindowPalette::Gray — the gray dialog color scheme; pushed down to the frame child (via the window’s internal set_palette) so the frame renders the Role::FrameGray* family immediately.
Source

pub fn set_button_layout(&mut self, layout: ButtonLayout)

Choose how button_row sizes its faces (default Classic).

Leave it Classic — the default — and every face is the fixed minimum width, exactly as before, so no existing dialog changes. Switch to Uniform or Ragged when a row carries labels longer than the minimum (“Discard”, “Keep editing”), which would otherwise render hard against the drop shadow. Call before button_row.

§Turbo Vision heritage

tvision-rs extension to TDialog.

Source

pub fn set_button_min_width(&mut self, width: i32)

Set the minimum button face width — a floor in the Uniform/Ragged layouts, and the exact width in Classic (where the minimum is also the maximum). Defaults to STD_BUTTON’s width; raise it for wider fixed faces, e.g. to match a house style. Call before button_row.

Source

pub fn insert_child(&mut self, view: Box<dyn View>) -> ViewId

Insert a child view into the dialog’s embedded window/group.

Exposed publicly so that example/application code can assemble custom dialogs by adding their fields, buttons, and labels before running the dialog modally.

Source

pub fn child_mut(&mut self, id: ViewId) -> Option<&mut dyn View>

Reach a direct child of the dialog’s embedded window/group by id.

Mirrors Window::child_mut; used by FileDialog to run a child’s post-insert, context-bearing init (e.g. reading a directory listing) and to read it back via as_any_mut + downcast.

Source

pub fn gather_list(&self) -> FieldValue

Gather the dialog’s whole record as one ordered FieldValue::List. Forwards to Window::gather_list.

Source

pub fn scatter_list(&mut self, record: &FieldValue, ctx: &mut Context<'_>)

Scatter an ordered FieldValue::List record back into the dialog. Forwards to Window::scatter_list.

Source

pub fn button_row( &mut self, buttons: &[(&str, Command, ButtonFlags)], align: ButtonRowAlign, ) -> Vec<ViewId>

Insert a conventional button row: 10×2 buttons, BUTTON_GAP apart, top edge at height - BUTTON_ROW_FROM_BOTTOM. align centers or right-groups the row. Returns the inserted ids in the given order.

Face widths follow the dialog’s ButtonLayout and minimum (see set_button_layout / set_button_min_width); the default is Classic at STD_BUTTON, i.e. every face a fixed 10 columns. Switch to Uniform or Ragged for labels longer than the minimum (“Discard”, “Keep editing”), which would otherwise render hard against the drop shadow.

§Turbo Vision heritage

tvision-rs extension to TDialog. The metrics are the classic Turbo Vision ones. C++ has no public button-row call: an application places each button itself, and only messageBox (msgbox.cpp) lays out its own row internally.

Source

pub fn set_flags(&mut self, flags: WindowFlags)

Override the decoration flags after construction.

Mirrors Window::set_flags; used by FileDialog and ChDirDialog to add the grow flag on top of the Dialog defaults (move | close). Re-pushes to the frame child so the grow handle draws immediately.

Source

pub fn flags(&self) -> WindowFlags

Read the current decoration flags.

Mirrors Window::flags; exposed so FileDialog / ChDirDialog tests can assert the grow flag is set post-construction.

Source

pub fn set_palette(&mut self, palette: WindowPalette)

Override the colour scheme after construction. Mirrors Window::set_palette.

Source

pub fn set_grow_mode(&mut self, grow_mode: GrowMode)

Override the grow mode after construction. Mirrors Window::set_grow_mode.

Source

pub fn set_drag_mode(&mut self, drag_mode: DragMode)

Override the drag mode after construction. Mirrors Window::set_drag_mode.

Source

pub fn set_min_size(&mut self, min: Point)

Raise the dialog’s interactive-resize floor (forwards to the embedded Window; see Window::set_min_size).

Source

pub fn with_flags(self, flags: WindowFlags) -> Self

Builder form of set_flags.

Source

pub fn with_palette(self, palette: WindowPalette) -> Self

Builder form of set_palette.

Source

pub fn with_grow_mode(self, grow_mode: GrowMode) -> Self

Builder form of set_grow_mode.

Source

pub fn with_drag_mode(self, drag_mode: DragMode) -> Self

Builder form of set_drag_mode.

Source

pub fn with_min_size(self, min: Point) -> Self

Builder form of set_min_size.

Trait Implementations§

Source§

impl View for Dialog

Source§

fn handle_event(&mut self, ev: &mut Event, ctx: &mut Context<'_>)

Lets the embedded window route the event first, then applies the dialog’s own keys and modal-result commands:

  • Esc posts a Command::CANCEL command.
  • Enter broadcasts Command::DEFAULT so the default button fires.
  • An Command::OK / CANCEL / YES / NO command, when this dialog is running modally, ends the modal loop with that command as the result.

Each arm self-guards: if the window routing already consumed the event it is now Event::Nothing and none of the matches fire.

Source§

fn valid(&mut self, cmd: Command, ctx: &mut Context<'_>) -> bool

Command::CANCEL is always valid (cancelling a dialog can never be vetoed); otherwise defer to the embedded group, which aggregates the children — a control with a failing Validator vetoes the close through this path.

Source§

fn value(&self) -> Option<FieldValue>

The dialog’s whole record: gather_list, an ordered FieldValue::List of its data-bearing controls’ values. This is what a view-launched modal (Context::request_exec_view) hands back to its requester via View::set_modal_data. set_value stays a no-op: scattering needs a Context, so use scatter_list.

§Turbo Vision heritage

TGroup::getData as seen through TView::getData on the dialog.

Source§

fn state(&self) -> &ViewState

Borrow the embedded ViewState (the view’s data members).
Source§

fn state_mut(&mut self) -> &mut ViewState

Mutably borrow the embedded ViewState.
Source§

fn draw(&mut self, ctx: &mut DrawCtx<'_>)

Paint the view through ctx. Must be overridden. Read more
Source§

fn set_state(&mut self, flag: StateFlag, enable: bool, ctx: &mut Context<'_>)

Flip a propagating state flag and run its side effects. The base flips the flag and, for StateFlag::Focused, emits the focus broadcast (RECEIVED_FOCUS/RELEASED_FOCUS) via ctx. Read more
Source§

fn set_modal_answer(&mut self, cmd: Command)

Stash the user’s choice from an async modal message box this view requested via Context::request_message_box (the answer_to/RouteModalAnswer round-trip). Default: no-op. Overridden by views that drive a Yes/No/Cancel prompt out of valid (e.g. FileEditor caches it for the re-validate).
Source§

fn set_modal_data(&mut self, data: FieldValue)

Deliver a finished modal’s typed result record to the view that launched it. Defaulted no-op; a launcher view overrides it to load the record. Two producers call it: Read more
Source§

fn set_value_ctx(&mut self, v: FieldValue, ctx: &mut Context<'_>)

Scatter a typed FieldValue into this control with a Context. Default: calls set_value (the context-free setter). Override when scatter needs deferred publishing (e.g. ListBox republishes its vertical scrollbar via focus_item).
Source§

fn awaken(&mut self)

Post-construction initialization hook. Called once after the view has been inserted into its group and the group’s layout is complete — the earliest point at which a view may safely resolve sibling ids or run initialization that requires a fully-wired tree. Override when a widget needs to do work that cannot happen during construction (e.g. reading a linked control’s current value). Base is a no-op.
Source§

fn size_limits(&self, owner_size: Point) -> (Point, Point)

The (min, max) size this view may take inside an owner of owner_size. Read more
Source§

fn change_bounds(&mut self, bounds: Rect)

Apply bounds to this view and propagate as needed. Read more
Source§

fn on_bounds_changed(&mut self, ctx: &mut Context<'_>)

Called by the pump after change_bounds is applied via Deferred::ChangeBounds — provides a Context for re-publishing state that depends on the new bounds (e.g. scrollbar params). Default implementation is a no-op. Read more
Source§

fn cursor_request(&self) -> Option<Point>

The view-local hardware-cursor position this view wants shown, or None to hide it. Base: Some(cursor) iff the view is focused with a visible cursor, else None. Read more
Source§

fn caret_size(&self) -> u8

The caret size this view wants while its cursor is shown, as a percentage of the character cell (1..=100). Base: CARET_INSERT (a block) when the cursor_ins state is set, else CARET_NORMAL (the normal caret). The event loop reads it along the same focused chain as cursor_request; Group overrides it to descend into its current child. Read more
Source§

fn find_mut(&mut self, id: ViewId) -> Option<&mut dyn View>

Resolve id to a descendant of this view (never self — the parent identifies a view by id). A leaf has no descendants, so the base returns None; a Group overrides to search its children and recurse; a Group-embedding view delegates to its inner group. This is the “tree-walk via Context” — the uniform way the event loop / a capture handler acts on a view it holds only by id (move a window’s bounds, flip the dragging flag, …).
Source§

fn remove_descendant(&mut self, id: ViewId, ctx: &mut Context<'_>) -> bool

Remove the descendant named by id from whichever group owns it. Returns true if it was found+removed. Distinct from find_mut because removal happens in the owner’s child Vec (a view cannot remove itself — it doesn’t know its owner) and must run the owning group’s reset_current. Base: false (a leaf owns nothing).
Source§

fn focus_descendant(&mut self, id: ViewId, ctx: &mut Context<'_>) -> bool

Focus (select) the descendant named by id within whichever group owns it — the tree-op behind a label focusing its linked control. Returns true if id was found in this subtree (selectable or not — finding it stops the walk). Distinct from find_mut because focusing happens in the owning group (a view cannot select itself within itself): the owning Group calls focus_child after applying the selectable gate. Base: false (a leaf owns nothing). Read more
Source§

fn has_focusable_leaf(&self) -> bool

Whether this view’s subtree contains a focusable leaf (visible, enabled, selectable). Base: whether THIS view is itself a focusable leaf; Group overrides to recurse into children; wrapper views delegate. Used by the hierarchical Tab traversal to skip selectable-but-empty subtrees.
Source§

fn focus_to_edge(&mut self, backward: bool, ctx: &mut Context<'_>) -> bool

Focus the first (Tab, backward = false) or last (Shift-Tab, backward = true) focusable leaf in this view’s subtree, establishing the full focus path down to it. Returns true if a focusable leaf was focused. Read more
Source§

fn reset_current(&mut self, ctx: &mut Context<'_>)

Establish this view’s INTERNAL currency — for a group-bearing view, set its current child to the first visible+selectable child. The insert-time currency cascade cannot run inside the context-less Group::insert, so exec_view calls this on a freshly-inserted modal BEFORE focusing it, so the modal’s first selectable child is current on open (otherwise the modal is keyboard-dead until a nav event — see the seam note in exec_view). Base: no-op (a leaf has no internal currency); Group overrides; Window/Dialog delegate.
Source§

fn settle_currency(&mut self, ctx: &mut Context<'_>)

Run any pending insert-time reset-current cascades in this subtree. Read more
Source§

fn set_visible_descendant( &mut self, id: ViewId, visible: bool, ctx: &mut Context<'_>, ) -> bool

Tree-op: set the visible flag of the descendant named by id from its OWNING group, running the owning group’s currency tail. Toggling visibility on a selectable view re-picks the owner’s current child, in both directions (show and hide). Returns true if id was found in this subtree. Read more
Source§

fn number(&self) -> Option<i16>

The window number for Alt-N selection. Base views are unnumbered (None); Window overrides to return its number when > 0 (0 means unnumbered → None).
Source§

fn tile(&mut self, r: Rect)

Tree-op: lay this subtree’s tileable windows out in a grid (the tile command). Base: no-op (only Desktop lays out windows). r is the desktop-local layout rect. Mirrors select_window_num: the live loop drives the desktop by id through &mut dyn View.
Source§

fn cascade(&mut self, r: Rect)

Tree-op: lay this subtree’s tileable windows out cascaded (the cascade command). Base: no-op; Desktop overrides.
Source§

fn update_menu_commands(&mut self, cs: &CommandSet)

The menu command-graying broker hook. Defaulted no-op; menu views override to re-gray their menu tree against the program’s live disabled-command set (denylist — the argument is the set of commands currently disabled; an item grays iff its command is in it). The free fn menu::menu_view::update_menu_commands implements the re-gray walk. Read more
Source§

fn set_menu_current(&mut self, current: Option<usize>)

The menu-highlight write-back hook. Defaulted no-op; menu views (MenuBar / MenuBox) override to set their MenuViewState::current — the write-only display cache their draw reads to pick the selected colour. Read more
Source§

fn get_help_ctx(&self) -> HelpCtx

The effective help context for status-line switching. Returns HelpCtx::DRAGGING while the view is being dragged, otherwise the view’s own ViewState::help_ctx. Read more
Source§

fn descendant_global_bounds(&self, id: ViewId, acc: Point) -> Option<Rect>

Resolve descendant id to its absolute bounds, given acc = this view’s own absolute origin. Base returns None (a leaf owns no descendants); a Group overrides to walk its children accumulating origins, and a Group-embedding view delegates to its inner group. The THistory open path needs its linked input line’s bounds in the root/absolute frame, because exec_view root-inserts the modal and the modal frame hit-tests in absolute coords (the documented ROOT-INSERT + (0,0) caveat). Mirrors find_mut’s recursion but returns geometry, not a borrow.
Source§

fn set_indicator_value(&mut self, location: Point, modified: bool)

The editor→indicator status-push broker hook. Defaulted no-op; the editor’s status Indicator overrides it to store the new cursor location + modified flag. Driven by Deferred::IndicatorSetValue: the editor (a leaf) cannot reach its indicator sibling inline, so it requests this and the pump calls the method by id — virtual dispatch, not a downcast.
Source§

fn apply_page_sync(&mut self, idx: usize, ctx: &mut Context<'_>)

The tab-bar→page-stack switch broker hook. Defaulted no-op; PageStack overrides it to make page idx active. Driven by Deferred::PageStackSync: the pump reads the bound tab bar’s value and calls this method by id — virtual dispatch, not a downcast.
Source§

fn set_value(&mut self, _v: FieldValue)

Load a typed FieldValue into this control. Read more
Source§

fn calc_bounds(&mut self, owner_size: Point, delta: Point) -> Rect

The new bounds after the owner resized to owner_size (delta = new - old). Computes the size limits via the overridable size_limits hook — so a widget override (e.g. a window’s minimum) participates — then delegates the grow math to ViewState::calc_bounds (the single source). Returns the bounds; it does not apply them (change_bounds does).
Source§

fn grabs_focus_on_click(&self) -> bool

Whether a mouse-down inside this view should auto-select (focus) it — the per-view opt-out for the group’s mouse-down auto-select (see Group::route_event). Default true (the common case); a Button overrides to return its grab-focus flag. A view returning false is not focused by a click but still receives the click (so it can act, e.g. press, without becoming the current view).
Source§

fn select_window_num(&mut self, num: i16, ctx: &mut Context<'_>) -> bool

Tree-op: ask this subtree to select the window numbered num. Returns whether one matched. Consistent with the find_mut / remove_descendant tree-op family: the live loop holds a subtree only by id (here, the desktop) and asks it to act. Default: no-op (false). Desktop overrides.
Source§

fn apply_scroll_sync( &mut self, _h: Option<i32>, _v: Option<i32>, _ctx: &mut Context<'_>, )

The shared scrollbar read-sync broker hook. Defaulted no-op; scroll-aware widgets override it to apply a freshly-read scrollbar delta to themselves. The pump passes the horizontal/vertical scrollbar values (None if that bar is absent or unresolved), each read via View::value. Overridden by the list viewers (delegate to list_viewer::apply_scroll), Scroller, the outline viewer, and the editor — every sibling-scrollbar read sync routes through this one method instead of a pump downcast. Read more
Source§

fn as_any_mut(&mut self) -> Option<&mut dyn Any>

Downcast hook for the rare parent→child push that needs the concrete type (e.g. a window pushing its zoomed flag to its frame). Base returns None; only views that must be reached concretely override it. (Any requires 'static, which every view is.)

Auto Trait Implementations§

§

impl !RefUnwindSafe for Dialog

§

impl !Send for Dialog

§

impl !Sync for Dialog

§

impl !UnwindSafe for Dialog

§

impl Freeze for Dialog

§

impl Unpin for Dialog

§

impl UnsafeUnpin for Dialog

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.