# tuirealm_derive
~ Automatically implements MockComponent ~
Get started
ยท
tui-realm
ยท
Documentation
Developed by @veeso
Current version: 2.0.0 (12/10/2024)
---
- [tuirealm\_derive](#tuirealm_derive)
- [About tuirealm\_derive ๐](#about-tuirealm_derive-)
- [Get started ๐](#get-started-)
- [Support the developer โ](#support-the-developer-)
- [Changelog โณ](#changelog-)
- [License ๐](#license-)
## About tuirealm_derive ๐
tuirealm_derive is a crate which implements the procedural macro `MockComponent` which can be used to automatically implement
the `MockComponent` trait for a tui-realm `Component`.
Indeed, as you already know if you're a tui-realm user, you've got two kind of component entities:
- MockComponent: generic graphic component which is not bridged to the application and is "reusable"
- Component: which uses a MockComponent as "backend" and is bridged to the application using the **Event -> Msg** system.
The Component wraps the MockComponent along with additional states. Such as:
```rust
pub struct IpAddressInput {
component: Input,
}
impl MockComponent for IpAddressInput {
...
fn state(&self) -> State {
self.component.state()
}
...
}
impl Component for IpAddressInput {
fn on(&mut self, ev: Event) -> Option {
let cmd: Cmd = match ev {
...
};
match self.perform(cmd) {
...
}
}
}
```
Since `Component` **MUST** implement `MockComponent`, we need to implement the mock component trait too, which in most of the case it will just call the MockComponet methods on the inner `component` field. This is obviously kinda annoying to do for each component. That's why I implemented this procedural macro, which will automatically implement this logic on your component.
So basically instead of implementing `MockComponent` for your components, you can just do as follows:
```rust
#[derive(MockComponent)]
pub struct IpAddressInput {
component: Input,
}
impl Component for IpAddressInput {
...
}
```
With the directive `#[derive(MockComponent)]` we **don't have to** implement the mock component trait.
> โ In order to work, the procedural macro requires you to name the "inner" mock component as `component` as I did in the example.
If we give a deeper look at the macro, we'll see that what it does is:
```rust
impl MockComponent for IpAddressInput {
fn view(&mut self, frame: &mut Frame, area: Rect) {
self.component.view(frame, area);
}
fn query(&self, attr: Attribute) -> Option {
self.component.query(attr)
}
fn attr(&mut self, query: Attribute, attr: AttrValue) {
self.component.attr(query, attr)
}
fn state(&self) -> State {
self.component.state()
}
fn perform(&mut self, cmd: Cmd) -> CmdResult {
self.component.perform(cmd)
}
}
```
---
## Get started ๐
In order to get started with **tuirealm_derive** all you need to do is to add [tui-realm](https://github.com/veeso/tui-realm) to your dependencies and enable the `derive` feature if needed.
If you're using the default features:
```toml
[dependencies]
tuirealm = "^2"
```
If you're not using the default features, be sure to enable the **derive** feature:
```toml
[dependencies]
tuirealm = { version = "^2", default-features = false, features = ["derive", "crossterm"] }
```
>โ ๏ธ tuirealm_derive requires tui-realm >= 2.0.0; the old API is not supported
Then you need to include tuirealm in your project using the `macro use` directive:
> src/lib.rs
```rust
#[macro_use]
extern crate tuirealm;
```
and finally derive `MockComponent` on your components:
```rust
#[derive(MockComponent)]
pub struct MyComponent {
component: MyMockComponentImpl,
}
```
> โ In order to work, the procedural macro requires you to name the "inner" mock component as `component` as I did in the example.
And ta-dah, you're ready to go ๐
---
## Support the developer โ
If you like tui-realm and you're grateful for the work I've done, please consider a little donation ๐ฅณ
You can make a donation with one of these platforms:
[](https://ko-fi.com/veeso)
[](https://www.paypal.me/chrisintin)
---
## Changelog โณ
View tuirealm_derive's changelog [HERE](CHANGELOG.md)
---
## License ๐
**tuirealm_derive** is licensed under the MIT license.
You can read the entire license [HERE](LICENSE)