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<F>(backend_init: F) -> Selfwhere
F: FnOnce() -> Box<dyn Backend>,
pub fn new<F>(backend_init: F) -> Selfwhere
F: FnOnce() -> Box<dyn Backend>,
Creates a new Cursive root, and initialize the back-end.
sourcepub fn dummy() -> Self
pub fn dummy() -> Self
Creates a new Cursive root using a dummy backend.
Nothing will be output. This is mostly here for tests.
sourcepub fn cb_sink(&self) -> &Sender<Box<dyn CbFunc>>
pub fn cb_sink(&self) -> &Sender<Box<dyn CbFunc>>
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.
Note that you currently need to call set_fps
to force cursive to
regularly check for messages.
Examples
let mut siv = Cursive::dummy();
siv.set_fps(10);
// quit() will be called during the next event cycle
siv.cb_sink().send(Box::new(|s: &mut Cursive| 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::dummy();
siv.menubar()
.add_subtree("File",
MenuTree::new()
.leaf("New", |s| s.add_layer(Dialog::info("New file!")))
.subtree("Recent", MenuTree::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",
MenuTree::new()
.subtree("Help",
MenuTree::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 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.
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.
sourcepub fn set_fps(&mut self, fps: u32)
pub fn set_fps(&mut self, fps: u32)
Sets the refresh rate, in frames per second.
Regularly redraws everything, even when no input is given.
You currently need this to regularly check
for events sent using cb_sink
.
Between 0 and 1000. Call with fps = 0
to disable (default value).
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 + Any,
F: FnOnce(&mut V) -> R,
pub fn call_on<V, F, R>(&mut self, sel: &Selector<'_>, callback: F) -> Option<R>where
V: View + Any,
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
fn main() {
let mut siv = Cursive::dummy();
siv.add_layer(views::TextView::new("Text #1").with_id("text"));
siv.add_global_callback('p', |s| {
s.call_on(
&view::Selector::Id("text"),
|view: &mut views::TextView| {
view.set_content("Text #2");
},
);
});
}
sourcepub fn call_on_id<V, F, R>(&mut self, id: &str, callback: F) -> Option<R>where
V: View + Any,
F: FnOnce(&mut V) -> R,
pub fn call_on_id<V, F, R>(&mut self, id: &str, callback: F) -> Option<R>where
V: View + Any,
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::dummy();
siv.add_layer(views::TextView::new("Text #1")
.with_id("text"));
siv.add_global_callback('p', |s| {
s.call_on_id("text", |view: &mut views::TextView| {
view.set_content("Text #2");
});
});
sourcepub fn find_id<V>(&mut self, id: &str) -> Option<ViewRef<V>>where
V: View + Any,
pub fn find_id<V>(&mut self, id: &str) -> Option<ViewRef<V>>where
V: View + Any,
Convenient method to find a view wrapped in IdView
.
This looks for a IdView<V>
with the given ID, 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::traits::Identifiable;
siv.add_layer(TextView::new("foo").with_id("id"));
// Could be called in a callback
let mut view: ViewRef<TextView> = siv.find_id("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::traits::Identifiable;
let select = SelectView::new().item("zero", 0u32).item("one", 1u32);
siv.add_layer(select.with_id("select"));
// Specifying a wrong type will not return anything.
assert!(siv.find_id::<SelectView<String>>("select").is_none());
// Omitting the type will use the default type, in this case `String`.
assert!(siv.find_id::<SelectView>("select").is_none());
// But with the correct type, it works fine.
assert!(siv.find_id::<SelectView<u32>>("select").is_some());
sourcepub fn focus_id(&mut self, id: &str) -> Result<(), ()>
pub fn focus_id(&mut self, id: &str) -> Result<(), ()>
Moves the focus to the view identified by id
.
Convenient method to call focus
with a view::Selector::Id
.
sourcepub fn focus(&mut self, sel: &Selector<'_>) -> Result<(), ()>
pub fn focus(&mut self, sel: &Selector<'_>) -> Result<(), ()>
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::dummy();
siv.add_global_callback('q', |s| s.quit());
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
let mut siv = Cursive::dummy();
siv.add_global_callback('q', |s| s.quit());
siv.clear_global_callbacks('q');
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
let mut siv = Cursive::dummy();
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 screen_size(&self) -> Vec2
pub fn screen_size(&self) -> Vec2
Returns the size of the screen, in characters.
sourcepub fn is_running(&self) -> bool
pub fn is_running(&self) -> bool
Returns true
until quit(&mut self)
is called.
sourcepub fn run(&mut self)
pub fn run(&mut self)
Runs the event loop.
It will wait for user input (key presses) and trigger callbacks accordingly.
Calls step(&mut self)
until quit(&mut self)
is called.
After this function returns, you can call it again and it will start a new loop.
sourcepub fn step(&mut self)
pub fn step(&mut self)
Performs a single step from the event loop.
Useful if you need tighter control on the event loop.
Otherwise, run(&mut self)
might be more convenient.