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}