Struct cursive_core::Cursive
source · [−]pub struct Cursive { /* private fields */ }
Expand description
Central part of the cursive library.
It initializes ncurses on creation and cleans up on drop.
To use it, you should populate it with views, layouts, and callbacks,
then start the event loop with run()
.
It uses a list of screen, with one screen active at a time.
Implementations
sourceimpl Cursive
impl Cursive
sourcepub fn new() -> Self
pub fn new() -> Self
Creates a new Cursive root, and initialize the back-end.
You probably don’t want to use this function directly, unless you’re
using a non-standard backend. Built-in backends have dedicated functions in the
CursiveExt
trait.
sourcepub fn screen_size(&self) -> Vec2
pub fn screen_size(&self) -> Vec2
Returns the screen size given in the last layout phase.
Note: this will return (0, 0)
before the first layout phase.
sourcepub fn set_user_data<T: Any>(&mut self, user_data: T)
pub fn set_user_data<T: Any>(&mut self, user_data: T)
Sets some data to be stored in Cursive.
It can later on be accessed with Cursive::user_data()
sourcepub fn user_data<T: Any>(&mut self) -> Option<&mut T>
pub fn user_data<T: Any>(&mut self) -> Option<&mut T>
Attempts to access the user-provided data.
If some data was set previously with the same type, returns a reference to it.
If nothing was set or if the type is different, returns None
.
sourcepub fn take_user_data<T: Any>(&mut self) -> Option<T>
pub fn take_user_data<T: Any>(&mut self) -> Option<T>
Attemps to take by value the current user-data.
If successful, this will replace the current user-data with the unit
type ()
.
If the current user data is not of the requested type, None
will be
returned.
Examples
let mut siv = cursive_core::Cursive::new();
// Start with a simple `Vec<i32>` as user data.
siv.set_user_data(vec![1i32, 2, 3]);
assert_eq!(siv.user_data::<Vec<i32>>(), Some(&mut vec![1i32, 2, 3]));
// Let's mutate the data a bit.
siv.with_user_data(|numbers: &mut Vec<i32>| numbers.push(4));
// If mutable reference is not enough, we can take the data by value.
let data: Vec<i32> = siv.take_user_data().unwrap();
assert_eq!(data, vec![1i32, 2, 3, 4]);
// At this point the user data was removed and is no longer available.
assert_eq!(siv.user_data::<Vec<i32>>(), None);
sourcepub fn with_user_data<F, T, R>(&mut self, f: F) -> Option<R> where
F: FnOnce(&mut T) -> R,
T: Any,
pub fn with_user_data<F, T, R>(&mut self, f: F) -> Option<R> where
F: FnOnce(&mut T) -> R,
T: Any,
Runs the given closure on the stored user data, if any.
If no user data was supplied, or if the type is different, nothing will be run.
Otherwise, the result will be returned.
sourcepub fn set_window_title<S: Into<String>>(&mut self, title: S)
pub fn set_window_title<S: Into<String>>(&mut self, title: S)
Sets the title for the terminal window.
Note that not all backends support this.
sourcepub fn show_debug_console(&mut self)
pub fn show_debug_console(&mut self)
Show the debug console.
Currently, this will show logs if logger::init()
was called.
sourcepub fn toggle_debug_console(&mut self)
pub fn toggle_debug_console(&mut self)
Show the debug console, or hide it if it’s already visible.
Examples
siv.add_global_callback('~', Cursive::toggle_debug_console);
sourcepub fn cb_sink(&self) -> &CbSink
pub fn cb_sink(&self) -> &CbSink
Returns a sink for asynchronous callbacks.
Returns the sender part of a channel, that allows to send
callbacks to self
from other threads.
Callbacks will be executed in the order of arrival on the next event cycle.
Notes
Callbacks need to be Send
, which can be limiting in some cases.
In some case send_wrapper
may help you work around that.
Examples
let mut siv = Cursive::new();
// quit() will be called during the next event cycle
siv.cb_sink().send(Box::new(|s| s.quit())).unwrap();
Selects the menubar.
Sets the menubar autohide feature.
- When enabled (default), the menu is only visible when selected.
- When disabled, the menu is always visible and reserves the top row.
Access the menu tree used by the menubar.
This allows to add menu items to the menubar.
Examples
let mut siv = Cursive::new();
siv.menubar()
.add_subtree(
"File",
menu::Tree::new()
.leaf("New", |s| s.add_layer(Dialog::info("New file!")))
.subtree(
"Recent",
menu::Tree::new().with(|tree| {
for i in 1..100 {
tree.add_leaf(format!("Item {}", i), |_| ())
}
}),
)
.delimiter()
.with(|tree| {
for i in 1..10 {
tree.add_leaf(format!("Option {}", i), |_| ());
}
})
.delimiter()
.leaf("Quit", |s| s.quit()),
)
.add_subtree(
"Help",
menu::Tree::new()
.subtree(
"Help",
menu::Tree::new()
.leaf("General", |s| {
s.add_layer(Dialog::info("Help message!"))
})
.leaf("Online", |s| {
s.add_layer(Dialog::info("Online help?"))
}),
)
.leaf("About", |s| {
s.add_layer(Dialog::info("Cursive v0.0.0"))
}),
);
siv.add_global_callback(event::Key::Esc, |s| s.select_menubar());
sourcepub fn current_theme(&self) -> &Theme
pub fn current_theme(&self) -> &Theme
Returns the currently used theme.
sourcepub fn update_theme(&mut self, f: impl FnOnce(&mut Theme))
pub fn update_theme(&mut self, f: impl FnOnce(&mut Theme))
Updates the current theme.
sourcepub fn load_theme_file<P: AsRef<Path>>(
&mut self,
filename: P
) -> Result<(), Error>
pub fn load_theme_file<P: AsRef<Path>>(
&mut self,
filename: P
) -> Result<(), Error>
Loads a theme from the given file.
filename
must point to a valid toml file.
Must have the toml
feature enabled.
sourcepub fn load_toml(&mut self, content: &str) -> Result<(), Error>
pub fn load_toml(&mut self, content: &str) -> Result<(), Error>
Loads a theme from the given string content.
Content must be valid toml.
Must have the toml
feature enabled.
sourcepub fn set_fps(&mut self, fps: u32)
pub fn set_fps(&mut self, fps: u32)
Sets the refresh rate, in frames per second.
Note that the actual frequency is not guaranteed.
Between 0 and 30. Call with fps = 0
to disable (default value).
sourcepub fn set_autorefresh(&mut self, autorefresh: bool)
pub fn set_autorefresh(&mut self, autorefresh: bool)
Enables or disables automatic refresh of the screen.
This is a shortcut to call set_fps
with 30
or 0
depending on
autorefresh
.
sourcepub fn fps(&self) -> Option<NonZeroU32>
pub fn fps(&self) -> Option<NonZeroU32>
Returns the current refresh rate, if any.
Returns None
if no auto-refresh is set. Otherwise, returns the rate
in frames per second.
sourcepub fn screen_mut(&mut self) -> &mut StackView
pub fn screen_mut(&mut self) -> &mut StackView
Returns a mutable reference to the currently active screen.
sourcepub fn active_screen(&self) -> ScreenId
pub fn active_screen(&self) -> ScreenId
Returns the id of the currently active screen.
sourcepub fn add_screen(&mut self) -> ScreenId
pub fn add_screen(&mut self) -> ScreenId
Adds a new screen, and returns its ID.
sourcepub fn add_active_screen(&mut self) -> ScreenId
pub fn add_active_screen(&mut self) -> ScreenId
Convenient method to create a new screen, and set it as active.
sourcepub fn set_screen(&mut self, screen_id: ScreenId)
pub fn set_screen(&mut self, screen_id: ScreenId)
Sets the active screen. Panics if no such screen exist.
sourcepub fn call_on<V, F, R>(&mut self, sel: &Selector<'_>, callback: F) -> Option<R> where
V: View,
F: FnOnce(&mut V) -> R,
pub fn call_on<V, F, R>(&mut self, sel: &Selector<'_>, callback: F) -> Option<R> where
V: View,
F: FnOnce(&mut V) -> R,
Tries to find the view pointed to by the given selector.
Runs a closure on the view once it’s found, and return the result.
If the view is not found, or if it is not of the asked type, returns None.
Examples
let mut siv = Cursive::new();
siv.add_layer(views::TextView::new("Text #1").with_name("text"));
siv.add_global_callback('p', |s| {
s.call_on(
&view::Selector::Name("text"),
|view: &mut views::TextView| {
view.set_content("Text #2");
},
);
});
sourcepub fn call_on_name<V, F, R>(&mut self, name: &str, callback: F) -> Option<R> where
V: View,
F: FnOnce(&mut V) -> R,
pub fn call_on_name<V, F, R>(&mut self, name: &str, callback: F) -> Option<R> where
V: View,
F: FnOnce(&mut V) -> R,
Tries to find the view identified by the given id.
Convenient method to use call_on
with a view::Selector::Id
.
Examples
let mut siv = Cursive::new();
siv.add_layer(views::TextView::new("Text #1").with_name("text"));
siv.add_global_callback('p', |s| {
s.call_on_name("text", |view: &mut views::TextView| {
view.set_content("Text #2");
});
});
sourcepub fn call_on_all_named<V, F>(&mut self, name: &str, callback: F) where
V: View,
F: FnMut(&mut V),
pub fn call_on_all_named<V, F>(&mut self, name: &str, callback: F) where
V: View,
F: FnMut(&mut V),
Call the given closure on all views with the given name and the correct type.
sourcepub fn find_name<V>(&mut self, id: &str) -> Option<ViewRef<V>> where
V: View,
pub fn find_name<V>(&mut self, id: &str) -> Option<ViewRef<V>> where
V: View,
Convenient method to find a view wrapped in NamedView
.
This looks for a NamedView<V>
with the given name, and return
a ViewRef
to the wrapped view. The ViewRef
implements
DerefMut<Target=T>
, so you can treat it just like a &mut T
.
Examples
use cursive_core::traits::Nameable;
siv.add_layer(TextView::new("foo").with_name("id"));
// Could be called in a callback
let mut view: ViewRef<TextView> = siv.find_name("id").unwrap();
view.set_content("bar");
Note that you must specify the exact type for the view you’re after; for example, using the
wrong item type in a SelectView
will not find anything:
use cursive_core::traits::Nameable;
let select = SelectView::new().item("zero", 0u32).item("one", 1u32);
siv.add_layer(select.with_name("select"));
// Specifying a wrong type will not return anything.
assert!(siv.find_name::<SelectView<String>>("select").is_none());
// Omitting the type will use the default type, in this case `String`.
assert!(siv.find_name::<SelectView>("select").is_none());
// But with the correct type, it works fine.
assert!(siv.find_name::<SelectView<u32>>("select").is_some());
sourcepub fn focus_name(&mut self, name: &str) -> Result<EventResult, ViewNotFound>
pub fn focus_name(&mut self, name: &str) -> Result<EventResult, ViewNotFound>
Moves the focus to the view identified by name
.
Convenient method to call focus
with a view::Selector::Name
.
sourcepub fn focus(&mut self, sel: &Selector<'_>) -> Result<EventResult, ViewNotFound>
pub fn focus(&mut self, sel: &Selector<'_>) -> Result<EventResult, ViewNotFound>
Moves the focus to the view identified by sel
.
sourcepub fn add_global_callback<F, E: Into<Event>>(&mut self, event: E, cb: F) where
F: FnMut(&mut Cursive) + 'static,
pub fn add_global_callback<F, E: Into<Event>>(&mut self, event: E, cb: F) where
F: FnMut(&mut Cursive) + 'static,
Adds a global callback.
Will be triggered on the given key press when no view catches it.
Examples
let mut siv = Cursive::new();
siv.add_global_callback('q', |s| s.quit());
sourcepub fn set_on_post_event<F, E>(&mut self, trigger: E, cb: F) where
F: FnMut(&mut Cursive) + 'static,
E: Into<EventTrigger>,
pub fn set_on_post_event<F, E>(&mut self, trigger: E, cb: F) where
F: FnMut(&mut Cursive) + 'static,
E: Into<EventTrigger>,
Registers a callback for ignored events.
This is the same as add_global_callback
, but can register any EventTrigger
.
sourcepub fn set_on_pre_event<F, E>(&mut self, trigger: E, cb: F) where
F: FnMut(&mut Cursive) + 'static,
E: Into<EventTrigger>,
pub fn set_on_pre_event<F, E>(&mut self, trigger: E, cb: F) where
F: FnMut(&mut Cursive) + 'static,
E: Into<EventTrigger>,
Registers a priotity callback.
If an event matches the given trigger, it will not be sent to the view tree and will go to the given callback instead.
Note that regular “post-event” callbacks will also be skipped for these events.
sourcepub fn set_on_pre_event_inner<E, F>(&mut self, trigger: E, cb: F) where
E: Into<EventTrigger>,
F: Fn(&Event) -> Option<EventResult> + 'static,
pub fn set_on_pre_event_inner<E, F>(&mut self, trigger: E, cb: F) where
E: Into<EventTrigger>,
F: Fn(&Event) -> Option<EventResult> + 'static,
Registers an inner priority callback.
See OnEventView
for more information.
sourcepub fn set_on_event_inner<E, F>(&mut self, trigger: E, cb: F) where
E: Into<EventTrigger>,
F: Fn(&Event) -> Option<EventResult> + 'static,
pub fn set_on_event_inner<E, F>(&mut self, trigger: E, cb: F) where
E: Into<EventTrigger>,
F: Fn(&Event) -> Option<EventResult> + 'static,
Registers an inner callback.
See OnEventView
for more information.
sourcepub fn set_global_callback<F, E: Into<Event>>(&mut self, event: E, cb: F) where
F: FnMut(&mut Cursive) + 'static,
pub fn set_global_callback<F, E: Into<Event>>(&mut self, event: E, cb: F) where
F: FnMut(&mut Cursive) + 'static,
Sets the only global callback for the given event.
Any other callback for this event will be removed.
See also Cursive::add_global_callback
.
sourcepub fn debug_name(&mut self, name: &str) -> Option<&'static str>
pub fn debug_name(&mut self, name: &str) -> Option<&'static str>
Fetches the type name of a view in the tree.
sourcepub fn clear_global_callbacks<E>(&mut self, event: E) where
E: Into<Event>,
pub fn clear_global_callbacks<E>(&mut self, event: E) where
E: Into<Event>,
Removes any callback tied to the given event.
Examples
use cursive_core::Cursive;
let mut siv = Cursive::new();
siv.add_global_callback('q', |s| s.quit());
siv.clear_global_callbacks('q');
sourcepub fn reset_default_callbacks(&mut self)
pub fn reset_default_callbacks(&mut self)
This resets the default callbacks.
Currently this mostly includes exiting on Ctrl-C.
sourcepub fn add_layer<T>(&mut self, view: T) where
T: IntoBoxedView,
pub fn add_layer<T>(&mut self, view: T) where
T: IntoBoxedView,
Add a layer to the current screen.
Examples
use cursive_core::{views, Cursive};
let mut siv = Cursive::new();
siv.add_layer(views::TextView::new("Hello world!"));
sourcepub fn add_fullscreen_layer<T>(&mut self, view: T) where
T: IntoBoxedView,
pub fn add_fullscreen_layer<T>(&mut self, view: T) where
T: IntoBoxedView,
Adds a new full-screen layer to the current screen.
Fullscreen layers have no shadow.
sourcepub fn pop_layer(&mut self) -> Option<Box<dyn View>>
pub fn pop_layer(&mut self) -> Option<Box<dyn View>>
Convenient method to remove a layer from the current screen.
sourcepub fn reposition_layer(&mut self, layer: LayerPosition, position: Position)
pub fn reposition_layer(&mut self, layer: LayerPosition, position: Position)
Convenient stub forwarding layer repositioning.
sourcepub fn on_event(&mut self, event: Event)
pub fn on_event(&mut self, event: Event)
Processes an event.
- If the menubar is active, it will be handled the event.
- The view tree will be handled the event.
- If ignored, global_callbacks will be checked for this event.
sourcepub fn is_running(&self) -> bool
pub fn is_running(&self) -> bool
Returns true
until quit(&mut self)
is called.
sourcepub fn run_dummy(&mut self)
pub fn run_dummy(&mut self)
Runs a dummy event loop.
Initializes a dummy backend for the event loop.
sourcepub fn runner(&mut self, backend: Box<dyn Backend>) -> CursiveRunner<&mut Self>
pub fn runner(&mut self, backend: Box<dyn Backend>) -> CursiveRunner<&mut Self>
Returns a new runner on the given backend.
Used to manually control the event loop. In most cases, running
Cursive::run_with
will be easier.
The runner will borrow self
; when dropped, it will clear out the
terminal, and the cursive instance will be ready for another run if
needed.
sourcepub fn into_runner(self, backend: Box<dyn Backend>) -> CursiveRunner<Self>
pub fn into_runner(self, backend: Box<dyn Backend>) -> CursiveRunner<Self>
Returns a new runner on the given backend.
Used to manually control the event loop. In most cases, running
Cursive::run_with
will be easier.
The runner will embed self
; when dropped, it will clear out the
terminal, and the cursive instance will be dropped as well.
sourcepub fn run_with<F>(&mut self, backend_init: F) where
F: FnOnce() -> Box<dyn Backend>,
pub fn run_with<F>(&mut self, backend_init: F) where
F: FnOnce() -> Box<dyn Backend>,
Initialize the backend and runs the event loop.
Used for infallible backend initializers.
sourcepub fn try_run_with<E, F>(&mut self, backend_init: F) -> Result<(), E> where
F: FnOnce() -> Result<Box<dyn Backend>, E>,
pub fn try_run_with<E, F>(&mut self, backend_init: F) -> Result<(), E> where
F: FnOnce() -> Result<Box<dyn Backend>, E>,
Initialize the backend and runs the event loop.
Returns an error if initializing the backend fails.
sourcepub fn dump(&mut self) -> Dump
pub fn dump(&mut self) -> Dump
Dump the current state of the Cursive root.
It will clear out this Cursive
instance and save everything, including:
- The view tree
- Callbacks
- Menubar
- User data
- Callback sink
After calling this, the cursive object will be as if newly created.
sourcepub fn restore(&mut self, dump: Dump)
pub fn restore(&mut self, dump: Dump)
Restores the state from a previous dump.
This will discard everything from this Cursive
instance.
In particular:
- All current views will be dropped, replaced by the dump.
- All callbacks will be replaced.
- Menubar will be replaced.
- User Data will be replaced.
- The callback channel will be replaced - any previous call to
cb_sink
on this instance will be disconnected.
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for Cursive
impl !Send for Cursive
impl !Sync for Cursive
impl Unpin for Cursive
impl !UnwindSafe for Cursive
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more