libnotcurses_sys/notcurses/options/
flags.rs

1/// A bitmask of [`NcOptions`][crate::NcOptions] flags.
2///
3/// # Flags
4/// - [`None`][NcFlag::None]
5/// - [`DrainInput`][NcFlag::DrainInput]
6/// - [`InhibitSetLocale`][NcFlag::InhibitSetLocale]
7/// - [`NoAlternateScreen`][NcFlag::NoAlternateScreen]
8/// - [`NoClearBitmaps`][NcFlag::NoClearBitmaps]
9/// - [`NoFontChanges`][NcFlag::NoFontChanges]
10/// - [`NoQuitSigHandlers`][NcFlag::NoQuitSigHandlers]
11/// - [`NoWinchSigHandler`][NcFlag::NoWinchSigHandler]
12/// - [`PreserveCursor`][NcFlag::PreserveCursor]
13/// - [`Scrolling`][NcFlag::Scrolling]
14/// - [`CliMode`][NcFlag::CliMode]
15/// - [`SuppressBanners`][NcFlag::SuppressBanners]
16///
17/// # Default
18/// *[`NcFlag::None`]
19#[derive(Copy, Clone, Debug, PartialEq, Eq)]
20pub struct NcFlag(pub c_api::NcFlag_u64);
21
22impl NcFlag {
23    /// No flags.
24    pub const None: Self = Self(0);
25
26    /// Input may be freely dropped.
27    ///
28    /// This ought be provided when the program does not intend to handle input.
29    /// Otherwise, input can accumulate in internal buffers, eventually preventing
30    /// Notcurses from processing terminal messages.
31    pub const DrainInput: Self = Self(c_api::NCOPTION_DRAIN_INPUT);
32
33    /// Do not call setlocale().
34    ///
35    /// notcurses_init() will call setlocale() to inspect the current locale. If
36    /// that locale is "C" or "POSIX", it will call setlocale(LC_ALL, "") to set
37    /// the locale according to the LANG environment variable. Ideally, this will
38    /// result in UTF8 being enabled, even if the client app didn't call
39    /// setlocale() itself. Unless you're certain that you're invoking setlocale()
40    /// prior to notcurses_init(), you should not set this bit. Even if you are
41    /// invoking setlocale(), this behavior shouldn't be an issue unless you're
42    /// doing something weird (setting a locale not based on LANG).
43    pub const InhibitSetLocale: Self = Self(c_api::NCOPTION_INHIBIT_SETLOCALE);
44
45    /// Do not enter alternate mode.
46    ///
47    /// If smcup/rmcup capabilities are indicated, notcurses defaults to making use
48    /// of the "alternate screen". This flag inhibits use of smcup/rmcup.
49    pub const NoAlternateScreen: Self = Self(c_api::NCOPTION_NO_ALTERNATE_SCREEN);
50
51    /// Do not try to clear any preexisting bitmaps.
52    ///
53    /// Note that they might still get cleared even if this is set, and they might
54    /// not get cleared even if this is not set.
55    pub const NoClearBitmaps: Self = Self(c_api::NCOPTION_NO_CLEAR_BITMAPS);
56
57    /// Do not modify the font.
58    ///
59    /// Notcurses might attempt to change the font slightly, to support certain
60    /// glyphs (especially on the Linux console). If this is set, no such
61    /// modifications will be made. Note that font changes will not affect anything
62    /// but the virtual console/terminal in which notcurses is running.
63    pub const NoFontChanges: Self = Self(c_api::NCOPTION_NO_FONT_CHANGES);
64
65    /// Do not handle `SIGINT`, `SIGSEGV`, `SIGABRT`, `SIGQUIT`.
66    ///
67    /// A signal handler will usually be installed for `SIGABRT`, `SIGBUS`,
68    /// `SIGFPE`, `SIGILL`, `SIGINT`, `SIGQUIT`, `SIGSEGV` and `SIGTERM`,
69    /// cleaning up the terminal on such exceptions.
70    ///
71    /// With this flag, the handler will not be installed.
72    pub const NoQuitSigHandlers: Self = Self(c_api::NCOPTION_NO_QUIT_SIGHANDLERS);
73
74    /// Do not handle `SIGWINCH`.
75    ///
76    /// A signal handler will usually be installed for `SIGWINCH`, resulting in
77    /// [`Nckey::Resize`] events being generated on input. With this flag,
78    /// the handler will not be installed.
79    ///
80    /// [`Nckey::Resize`]: crate::NcKey#associatedconstant.Resize
81    pub const NoWinchSigHandler: Self = Self(c_api::NCOPTION_NO_WINCH_SIGHANDLER);
82
83    /// Initializes the standard plane's virtual cursor to match the physical
84    /// cursor at context creation time.
85    ///
86    /// Together with [`NoAlternateScreen`] and a scrolling standard plane,
87    /// this facilitates easy scrolling-style programs in rendered mode.
88    ///
89    /// [`NoAlternateScreen`]: NcFlag#associatedconstant.NoAlternateScreen
90    pub const PreserveCursor: Self = Self(c_api::NCOPTION_PRESERVE_CURSOR);
91
92    /// Prepares the standard plane in scrolling mode, useful for CLIs. This is
93    /// equivalent to calling [`ncplane_set_scrolling`]`(notcurses_stdplane(nc), true)`.
94    ///
95    /// [`ncplane_set_scrolling`]: crate::c_api::ncplane_set_scrolling
96    pub const Scrolling: Self = Self(c_api::NCOPTION_SCROLLING);
97
98    /// "CLI mode" is just setting these four options:
99    ///
100    /// [`NoAlternateScreen`][Self::NoAlternateScreen]
101    /// | [`NoClearBitmaps`][Self::NoClearBitmaps]
102    /// | [`PreserveCursor`][Self::PreserveCursor]
103    /// | [`Scrolling`][Self::Scrolling]
104    pub const CliMode: Self = Self(
105        c_api::NCOPTION_NO_ALTERNATE_SCREEN
106            | c_api::NCOPTION_NO_CLEAR_BITMAPS
107            | c_api::NCOPTION_PRESERVE_CURSOR
108            | c_api::NCOPTION_SCROLLING,
109    );
110
111    /// Do not print banners.
112    ///
113    /// Notcurses typically prints version info in `notcurses_init` and
114    /// performance info in `notcurses_stop`. This inhibits that output.
115    pub const SuppressBanners: Self = Self(c_api::NCOPTION_SUPPRESS_BANNERS);
116}
117
118mod core_impls {
119    use super::{c_api::NcFlag_u64, NcFlag};
120
121    impl Default for NcFlag {
122        fn default() -> Self {
123            Self::None
124        }
125    }
126
127    crate::from_primitive![NcFlag, NcFlag_u64];
128    crate::unit_impl_from![NcFlag, NcFlag_u64];
129    crate::unit_impl_ops![bitwise; NcFlag, NcFlag_u64];
130    crate::unit_impl_fmt![bases+display; NcFlag];
131}
132
133pub(crate) mod c_api {
134    use crate::c_api::ffi;
135
136    /// A bitmask of [`Nc`][crate::Nc] flags.
137    ///
138    /// It's recommended to use [`NcFlag`][crate::NcFlag] instead.
139    ///
140    /// # Associated `c_api` constants
141    /// - [`NCOPTION_DRAIN_INPUT`]
142    /// - [`NCOPTION_INHIBIT_SETLOCALE`]
143    /// - [`NCOPTION_NO_ALTERNATE_SCREEN`]
144    /// - [`NCOPTION_NO_CLEAR_BITMAPS`]
145    /// - [`NCOPTION_NO_FONT_CHANGES`]
146    /// - [`NCOPTION_NO_QUIT_SIGHANDLERS`]
147    /// - [`NCOPTION_NO_WINCH_SIGHANDLER`]
148    /// - [`NCOPTION_PRESERVE_CURSOR`]
149    /// - [`NCOPTION_SCROLLING`]
150    /// - [`NCOPTION_CLI_MODE`]
151    /// - [`NCOPTION_SUPPRESS_BANNERS`]
152    pub type NcFlag_u64 = u64;
153
154    /// [`NcFlag_u64`] flag that indicates input may be freely dropped.
155    ///
156    /// This ought be provided when the program does not intend to handle input.
157    /// Otherwise, input can accumulate in internal buffers, eventually preventing
158    /// Notcurses from processing terminal messages.
159    pub const NCOPTION_DRAIN_INPUT: NcFlag_u64 = ffi::NCOPTION_DRAIN_INPUT as NcFlag_u64;
160
161    /// [`NcFlag_u64`] flag to avoid calling setlocale().
162    ///
163    /// notcurses_init() will call setlocale() to inspect the current locale. If
164    /// that locale is "C" or "POSIX", it will call setlocale(LC_ALL, "") to set
165    /// the locale according to the LANG environment variable. Ideally, this will
166    /// result in UTF8 being enabled, even if the client app didn't call
167    /// setlocale() itself. Unless you're certain that you're invoking setlocale()
168    /// prior to notcurses_init(), you should not set this bit. Even if you are
169    /// invoking setlocale(), this behavior shouldn't be an issue unless you're
170    /// doing something weird (setting a locale not based on LANG).
171    pub const NCOPTION_INHIBIT_SETLOCALE: NcFlag_u64 =
172        ffi::NCOPTION_INHIBIT_SETLOCALE as NcFlag_u64;
173
174    /// [`NcFlag_u64`] flag to avoid entering alternate mode.
175    ///
176    /// If smcup/rmcup capabilities are indicated, notcurses defaults to making use
177    /// of the "alternate screen". This flag inhibits use of smcup/rmcup.
178    pub const NCOPTION_NO_ALTERNATE_SCREEN: NcFlag_u64 =
179        ffi::NCOPTION_NO_ALTERNATE_SCREEN as NcFlag_u64;
180
181    /// [`NcFlag_u64`] flag to avoid trying to clear any preexisting bitmaps.
182    ///
183    /// Note that they might still get cleared even if this is set, and they might
184    /// not get cleared even if this is not set.
185    pub const NCOPTION_NO_CLEAR_BITMAPS: NcFlag_u64 = ffi::NCOPTION_NO_CLEAR_BITMAPS as NcFlag_u64;
186
187    /// [`NcFlag_u64`] flag to avoid modifying the font.
188    ///
189    /// Notcurses might attempt to change the font slightly, to support certain
190    /// glyphs (especially on the Linux console). If this is set, no such
191    /// modifications will be made. Note that font changes will not affect anything
192    /// but the virtual console/terminal in which notcurses is running.
193    pub const NCOPTION_NO_FONT_CHANGES: NcFlag_u64 = ffi::NCOPTION_NO_FONT_CHANGES as NcFlag_u64;
194
195    /// [`NcFlag_u64`] flag to avoid handling `SIGINT`, `SIGSEGV`,
196    /// `SIGABRT`, `SIGQUIT`.
197    ///
198    /// A signal handler will usually be installed for `SIGINT`, `SIGQUIT`,
199    /// `SIGSEGV`, `SIGTERM`, and `SIGABRT`, cleaning up the terminal on such
200    /// exceptions. With this flag, the handler will not be installed.
201    pub const NCOPTION_NO_QUIT_SIGHANDLERS: NcFlag_u64 =
202        ffi::NCOPTION_NO_QUIT_SIGHANDLERS as NcFlag_u64;
203
204    /// [`NcFlag_u64`] flag to avoid handling `SIGWINCH`.
205    ///
206    /// A signal handler will usually be installed for `SIGWINCH`, resulting in
207    /// [`NCKEY_RESIZE`][crate::c_api::NCKEY_RESIZE] events being generated on
208    /// input. With this flag, the handler will not be installed.
209    pub const NCOPTION_NO_WINCH_SIGHANDLER: NcFlag_u64 =
210        ffi::NCOPTION_NO_WINCH_SIGHANDLER as NcFlag_u64;
211
212    /// [`NcFlag_u64`] flag to initialize the standard plane's virtual cursor
213    /// to match the physical cursor at context creation time.
214    ///
215    /// Together with [`NCOPTION_NO_ALTERNATE_SCREEN`] and a scrolling standard
216    /// plane, this facilitates easy scrolling-style programs in rendered mode.
217    pub const NCOPTION_PRESERVE_CURSOR: NcFlag_u64 = ffi::NCOPTION_PRESERVE_CURSOR as NcFlag_u64;
218
219    /// [`NcFlag_u64`] flag to prepare the standard plane in scrolling mode,
220    /// useful for CLIs. This is equivalent to calling
221    /// [`ncplane_set_scrolling`]`(notcurses_stdplane(nc), true)`.
222    ///
223    /// [`ncplane_set_scrolling`]: crate::c_api::ncplane_set_scrolling
224    pub const NCOPTION_SCROLLING: NcFlag_u64 = ffi::NCOPTION_SCROLLING as NcFlag_u64;
225
226    /// [`NcFlag_u64`] flag set composed of `NCOPTION_NO_ALTERNATE_SCREEN` |
227    /// `NCOPTION_NO_CLEAR_BITMAPS` | `NCOPTION_PRESERVE_CURSOR` |
228    /// `NCOPTION_SCROLLING`.
229    pub const NCOPTION_CLI_MODE: NcFlag_u64 = NCOPTION_NO_ALTERNATE_SCREEN
230        | NCOPTION_NO_CLEAR_BITMAPS
231        | NCOPTION_PRESERVE_CURSOR
232        | NCOPTION_SCROLLING;
233
234    /// [`NcFlag_u64`] flag to avoid printing banners.
235    ///
236    /// Notcurses typically prints version info in notcurses_init() and performance
237    /// info in notcurses_stop(). This inhibits that output.
238    pub const NCOPTION_SUPPRESS_BANNERS: NcFlag_u64 = ffi::NCOPTION_SUPPRESS_BANNERS as NcFlag_u64;
239}
libnotcurses_sys/notcurses/options/flags.rs

libnotcurses_sys/notcurses/options/
flags.rs
