|
| 1 | +--- |
| 2 | +title: "Component" |
| 3 | +order: 2 |
| 4 | +--- |
| 5 | + |
| 6 | +# Component |
| 7 | + |
| 8 | +In `tessera`, a component (Component) is the basic building block of the user interface. It allows developers to create complex UIs by composing these components. |
| 9 | + |
| 10 | +`tessera` expresses components as functions, usually by marking functions with the `#[tessera]` macro. Below we also refer to components as "tessera". |
| 11 | + |
| 12 | +## Defining components |
| 13 | + |
| 14 | +Defining a component is very simple: just create a function and mark it with the `#[tessera]` macro — it becomes a `tessera` component. |
| 15 | + |
| 16 | +```rust |
| 17 | +use tessera_ui::tessera; |
| 18 | + |
| 19 | +#[tessera] |
| 20 | +fn component() { |
| 21 | + |
| 22 | +} |
| 23 | +``` |
| 24 | + |
| 25 | +Component functions can accept parameters with no special restrictions. As mentioned above, a component function is fundamentally an ordinary Rust function. |
| 26 | + |
| 27 | +```rust |
| 28 | +use tessera_ui::tessera; |
| 29 | +use tessera_ui_basic_components::text::text; |
| 30 | + |
| 31 | +#[tessera] |
| 32 | +fn component(name: String, age: u32) { |
| 33 | + text(format!("Hello, {}! You are {} years old.", name, age)); |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +## Composition |
| 38 | + |
| 39 | +To compose components, simply call one component function from another component function. |
| 40 | + |
| 41 | +```rust |
| 42 | +use tessera_ui::tessera; |
| 43 | + |
| 44 | +#[tessera] |
| 45 | +fn parent_component() { |
| 46 | + child_component(); |
| 47 | +} |
| 48 | + |
| 49 | +#[tessera] |
| 50 | +fn child_component() { |
| 51 | + // child component content |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +By default, this renders the child component at the top-left corner of the parent. For more advanced layouts see the "measure-place" layout system below. |
| 56 | + |
| 57 | +## Container |
| 58 | + |
| 59 | +Often we don't know what the child component will be and cannot call it directly. In such cases we can pass the child as a closure. |
| 60 | + |
| 61 | +```rust |
| 62 | +use tessera_ui::tessera; |
| 63 | + |
| 64 | +#[tessera] |
| 65 | +fn parent_component(child: impl FnOnce()) { |
| 66 | + child(); |
| 67 | +} |
| 68 | + |
| 69 | +#[tessera] |
| 70 | +fn child_component() { |
| 71 | + // child component content |
| 72 | +} |
| 73 | + |
| 74 | +fn app() { |
| 75 | + parent_component(|| { |
| 76 | + child_component(); |
| 77 | + }); |
| 78 | +} |
| 79 | +``` |
| 80 | + |
| 81 | +Such components are called containers. |
| 82 | + |
| 83 | +## Measure - Place |
| 84 | + |
| 85 | +For more complex layouts you need to dive into tessera's measure-place layout system. |
| 86 | + |
| 87 | +Tessera's layout system is split into two phases: measure and place. The measure phase determines the component's size, while the place phase determines the component's position on the screen. |
| 88 | + |
| 89 | +### Custom layout |
| 90 | + |
| 91 | +To override the default measurement behavior, call the `measure` function inside the component and provide a closure: |
| 92 | + |
| 93 | +```rust |
| 94 | +use tessera_ui::tessera; |
| 95 | + |
| 96 | +#[tessera] |
| 97 | +fn component() { |
| 98 | + measure(Box::new(|input| { |
| 99 | + // measurement logic here |
| 100 | + })) |
| 101 | +} |
| 102 | +``` |
| 103 | + |
| 104 | +The `measure` function accepts a closure that receives a `MeasureInput` and returns a `Size`. Its type is defined as: |
| 105 | + |
| 106 | +```rust |
| 107 | +pub type MeasureFn = |
| 108 | + dyn Fn(&MeasureInput<'_>) -> Result<ComputedData, MeasurementError> + Send + Sync; |
| 109 | +``` |
| 110 | + |
| 111 | +`MeasureInput` contains layout information such as child component ids and parent constraints, while the returned `ComputedData` is the component's size — the measurement result. |
| 112 | + |
| 113 | +Note that `measure` does not need to be imported; it is injected into the function component's context by the `#[tessera]` macro and can be considered part of the component API. |
| 114 | + |
| 115 | +For detailed information about `MeasureInput` and `ComputedData`, see the documentation on docs.rs. Here is a simple measurement example: it measures the first child's size, places the child at the top-left (relative coordinate `(0, 0)`), and returns its own size as the child's size plus 10 pixels. |
| 116 | + |
| 117 | +```rust |
| 118 | +#[tessera] |
| 119 | +fn component(child: impl FnOnce()) { |
| 120 | + child(); // compose child component |
| 121 | + measure(Box::new(|input| { |
| 122 | + let child_node_id = input.children_ids[0]; |
| 123 | + let child_size = input.measure_child(child_node_id, input.parent_constraint)?; |
| 124 | + input.place_child(child_node_id, PxPosition::new(Px(0), Px(0))); |
| 125 | + Ok( |
| 126 | + ComputedData { |
| 127 | + width: child_size.width + Px(10), |
| 128 | + height: child_size.height + Px(10), |
| 129 | + } |
| 130 | + ) |
| 131 | + })) |
| 132 | +} |
| 133 | +``` |
| 134 | + |
| 135 | +This simple example demonstrates what a component must do to perform layout: |
| 136 | + |
| 137 | +1. Execute child component functions |
| 138 | +2. Measure child sizes |
| 139 | +3. Place child components |
| 140 | +4. Return its own size |
| 141 | + |
| 142 | +::: warning |
| 143 | +If you place children without measuring them, or measure children but do not place them, the renderer will panic at runtime. |
| 144 | +::: |
| 145 | + |
| 146 | +You may notice earlier examples did not include any explicit layout. That's because tessera provides a default layout behavior for components without a custom layout: it measures child components and places them at the top-left. This default behavior is adequate in many cases. |
| 147 | + |
| 148 | +### Input handling |
| 149 | + |
| 150 | +Similar to `measure`, the `#[tessera]` macro injects an `input_handler` function into the component for handling external input events. |
| 151 | + |
| 152 | +The following example shows a component that prevents components below it from receiving mouse events: |
| 153 | + |
| 154 | +```rust |
| 155 | +#[tessera] |
| 156 | +fn component() { |
| 157 | + input_handler(Box::new(|mut input | { |
| 158 | + input.block_cursor(); |
| 159 | + })) |
| 160 | +} |
| 161 | +``` |
| 162 | + |
| 163 | +### Window callbacks |
| 164 | + |
| 165 | +The `#[tessera]` macro also injects functions to register window callbacks. Currently available callbacks include: |
| 166 | + |
| 167 | +- `on_minimize(Box<dyn Fn(bool) + Send + Sync>)` – window minimize callback |
| 168 | +- `on_close(Box<dyn Fn() + Send + Sync>)` – window close callback |
0 commit comments