Crate libccanvas
source ·Expand description
§libccanvas
libccanvas makes easy for creating ccanvas components. For more information, see the ccanvas main repository.
§Quickstart
Your component will be ran by the canvas when loaded, get started by creating a client with Client::new(ClientConfig::default())
.
Please name your Rust project in format of
ccanvas-XXXXX
for identification.
#[tokio::main]
async fn main() {
let mut client = Client::new(ClientConfig::default()).await;
client.hidecursor();
client.setchar(0, 0, 'H');
client.setchar(1, 0, 'e');
client.setchar(2, 0, 'l');
client.setchar(3, 0, 'l');
client.setchar(4, 0, 'o');
client.setchar(5, 0, '!');
// flush all changes
client.renderall().await;
// listen to all key presses
client.subscribe(Subscription::AllKeyPresses).await;
loop {
let event = client.recv().await;
// exit when 'q' is pressed
if let EventVariant::Key(key) = event.get() {
if key.code == KeyCode::Char('q') => {
client.exit().await;
break;
}
}
}
}
§Running the component
You will need ccanvas installed on your system.
- Install the component using cargo.
cargo install --path . # where `.` is your project directory
- Run ccanvas with the component loaded.
ccanvas hello ccanvas-hello # where `ccanvas-hello` is the command to run your component
You can find more examples of advance usage in /examples
.
§Implementation details
This is not just ccanvas bindings, here are things Client
does under the hood to simplify developer ergonomics.
§Confirm receiving events
When the server (from now on I will refer to the ccanvas server as just the server) pass an event to the client, it expects the client to confirm that it has received the event. And whether the event should be passed to other components.
- A confirmation is automatically sent when an
Event
goes out of scope. - You can manually trigger this behaviour using
Event.done(true)
as well.
§Handling responses
To preserve the order of requests, a client request will await until the server respond with a confirmation of the task being completed.
§Auto self destruct
When Client
goes out of scope, it will automatically call drop
of self - thus removing it from the ccanvas session, avoiding the situation of a “ghost component”.
§Contribution
Feel free to add implementation of your own API/bindings/functionalities to this crate under a non-default feature gate.
Modules§
- Binding structs.
- Main client.
- Feature gated content.