pub struct Program<M: Model> {
pub config: ProgramConfig,
/* private fields */
}Expand description
The main Program struct that coordinates the application.
The Program is responsible for setting up the terminal, managing the
event loop, executing commands, and rendering the model’s view.
Fields§
§config: ProgramConfigThe configuration for this Program instance.
Implementations§
Source§impl<M: Model> Program<M>
impl<M: Model> Program<M>
Sourcepub fn builder() -> ProgramBuilder<M>
pub fn builder() -> ProgramBuilder<M>
Creates a new ProgramBuilder for configuring and building a Program.
Sourcepub async fn run(self) -> Result<M, Error>
pub async fn run(self) -> Result<M, Error>
Runs the bubbletea-rs application.
This method initializes the terminal, starts the event loop, and manages
the application’s lifecycle. It will continue to run until a QuitMsg
is received or an unrecoverable error occurs.
§Returns
A Result containing the final Model state or an Error if the program
terminates abnormally.
Sourcepub fn sender(&self) -> EventSender
pub fn sender(&self) -> EventSender
Returns a sender that can be used to send messages to the Program’s event loop.
This is useful for sending messages from outside the Model’s update method,
for example, from asynchronous tasks or other threads.
§Returns
An EventSender that can be used to send messages.
Sourcepub fn send(&self, msg: Msg) -> Result<(), Error>
pub fn send(&self, msg: Msg) -> Result<(), Error>
Sends a message to the Program’s event loop.
This is a convenience method that wraps the sender() method.
The message will be processed by the model’s update method.
§Arguments
msg- TheMsgto send to the event loop.
§Returns
A Result indicating success or a channel-related error if the message could not be sent.
§Errors
Returns an Error if:
- The event channel is full (for bounded channels)
- The receiver has been dropped
§Example
let program = Program::<MyModel>::builder().build()?;
let key_msg = KeyMsg {
key: crossterm::event::KeyCode::Enter,
modifiers: crossterm::event::KeyModifiers::empty(),
};
program.send(Box::new(key_msg))?;Sourcepub fn quit(&self)
pub fn quit(&self)
Sends a QuitMsg to the Program’s event loop, initiating a graceful shutdown.
This causes the event loop to terminate gracefully after processing any remaining messages in the queue. The terminal state will be properly restored.
§Example
let program = Program::<MyModel>::builder().build()?;
program.quit(); // Gracefully shutdown the programSourcepub fn memory_monitor(&self) -> Option<&MemoryMonitor>
pub fn memory_monitor(&self) -> Option<&MemoryMonitor>
Get a reference to the memory monitor, if enabled.
Returns None if memory monitoring is disabled.
Sourcepub fn memory_health(&self) -> Option<MemoryHealth>
pub fn memory_health(&self) -> Option<MemoryHealth>
Get memory usage health information, if monitoring is enabled.
Returns None if memory monitoring is disabled.
Sourcepub fn kill(&self)
pub fn kill(&self)
Sends a KillMsg to the Program’s event loop, initiating an immediate termination.
Unlike quit(), which performs a graceful shutdown, kill() causes the event loop
to stop as soon as possible and returns Error::ProgramKilled.
Sourcepub async fn wait(&self)
pub async fn wait(&self)
Waits for the Program to finish execution.
This method blocks until the program’s event loop has exited.
§Note
This is currently a no-op since the Program is consumed by run().
In a real implementation, you’d need to track the program’s state separately,
similar to how Go’s context.Context works with goroutines.
§Future Implementation
A future version might track program state separately to enable proper
waiting functionality without consuming the Program instance.
Sourcepub async fn release_terminal(&mut self) -> Result<(), Error>
pub async fn release_terminal(&mut self) -> Result<(), Error>
Releases control of the terminal.
This method restores the terminal to its original state, disabling raw mode, exiting alternate screen, disabling mouse and focus reporting, and showing the cursor.
Sourcepub async fn restore_terminal(&mut self) -> Result<(), Error>
pub async fn restore_terminal(&mut self) -> Result<(), Error>
Restores control of the terminal.
This method re-initializes the terminal based on the ProgramConfig,
enabling raw mode, entering alternate screen, enabling mouse and focus reporting,
and hiding the cursor.
Sourcepub async fn println(&mut self, s: String) -> Result<(), Error>
pub async fn println(&mut self, s: String) -> Result<(), Error>
Prints a line to the terminal without going through the renderer.
This is useful for debugging or for outputting messages that shouldn’t be part of the managed UI. The output bypasses the normal rendering pipeline and goes directly to stdout.
§Arguments
s- The string to print, a newline will be automatically added.
§Returns
A Result indicating success or an IO error if printing fails.
§Errors
Returns an Error if stdout flushing fails.
§Warning
Using this method while the program is running may interfere with the normal UI rendering. It’s recommended to use this only for debugging purposes or when the renderer is disabled.
Sourcepub async fn printf(&mut self, s: String) -> Result<(), Error>
pub async fn printf(&mut self, s: String) -> Result<(), Error>
Prints formatted text to the terminal without going through the renderer.
This is useful for debugging or for outputting messages that shouldn’t be part of the managed UI. The output bypasses the normal rendering pipeline and goes directly to stdout without adding a newline.
§Arguments
s- The string to print without adding a newline.
§Returns
A Result indicating success or an IO error if printing fails.
§Errors
Returns an Error if stdout flushing fails.
§Warning
Using this method while the program is running may interfere with the normal UI rendering. It’s recommended to use this only for debugging purposes or when the renderer is disabled.