Guide API
Skip to main content

tvision_rs/
help.rs

1//! Help contexts.
2//!
3//! A [`HelpCtx`] identifies which help topic applies to the focused view — the
4//! status line and a help viewer use it to show context-sensitive help. Like
5//! [`Command`], a help context's identity is a **namespaced static string**, so
6//! app- and view-defined contexts mint their own collision-safely via
7//! [`HelpCtx::custom`] under their own dotted prefix.
8//!
9//! [`Command`]: crate::command::Command
10//!
11//! **Guide:** [Menus, status line & help](../../../apps/menus.html).
12//!
13//! # Turbo Vision heritage
14//!
15//! Ports the `hc*` help-context family (`views.h`). Contexts were originally plain
16//! `int`s used to index a help file's topic table; here the identity is a
17//! namespaced `&'static str` instead (deviation D1).
18
19/// Identifies which help topic applies to the focused view.
20///
21/// A help context's identity is a **namespaced static string** so app/view-
22/// defined contexts cannot collide. Equality and hashing compare the string
23/// *contents*.
24///
25/// [`Default`] is [`HelpCtx::NO_CONTEXT`].
26///
27/// # Turbo Vision heritage
28///
29/// Ports the `hc*` family (`views.h`), which were plain `int`s; here the identity
30/// is a namespaced `&'static str` (deviation D1).
31#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
32pub struct HelpCtx(&'static str);
33
34impl Default for HelpCtx {
35    fn default() -> Self {
36        HelpCtx::NO_CONTEXT
37    }
38}
39
40impl HelpCtx {
41    /// Mint an application- or view-specific help context from a namespaced
42    /// name. Pick a dotted prefix unique to your app/view so it cannot collide
43    /// with the framework's `tv.*` vocabulary or another extension's.
44    pub const fn custom(name: &'static str) -> HelpCtx {
45        HelpCtx(name)
46    }
47
48    /// The context's namespaced name (e.g. `"tv.no_context"`).
49    pub const fn name(self) -> &'static str {
50        self.0
51    }
52
53    /// No help topic — also the zero/default context.
54    pub const NO_CONTEXT: HelpCtx = HelpCtx("tv.no_context");
55    /// The context active while a view is being dragged (see
56    /// [`ViewState::get_help_ctx`](crate::view::ViewState::get_help_ctx)).
57    pub const DRAGGING: HelpCtx = HelpCtx("tv.dragging");
58}
59
60#[cfg(test)]
61mod tests {
62    use super::*;
63
64    #[test]
65    fn custom_round_trips() {
66        let h = HelpCtx::custom("myapp.editor");
67        assert_eq!(h.name(), "myapp.editor");
68    }
69
70    #[test]
71    fn default_is_no_context() {
72        assert_eq!(HelpCtx::default(), HelpCtx::NO_CONTEXT);
73        assert_eq!(HelpCtx::NO_CONTEXT.name(), "tv.no_context");
74    }
75
76    #[test]
77    fn constants_distinct() {
78        assert_ne!(HelpCtx::NO_CONTEXT, HelpCtx::DRAGGING);
79        assert_eq!(HelpCtx::DRAGGING.name(), "tv.dragging");
80    }
81}