1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

#![allow(clippy::module_inception)]

//! # libccanvas
//!
//! libccanvas makes easy for creating ccanvas components. For more information, see the [ccanvas](https://github.com/ccanvas/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.
//!
//! ```rust
//! #[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](https://github.com/ccanvas/ccanvas) installed on your system.
//!
//! 1. Install the component using cargo.
//! ```sh
//! cargo install --path . # where `.` is your project directory
//! ```
//! 2. Run ccanvas with the component loaded.
//! ```sh
//! ccanvas hello ccanvas-hello # where `ccanvas-hello` is the command to run your component
//! ```
//!
//! You can find more examples of advance usage in [`/examples`](https://github.com/ccanvas/libccanvas/tree/master/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.

/// Binding structs.
pub mod bindings;
/// Main client.
pub mod client;

/// Feature gated content.
pub mod features;