docs/bevy/release-content/migration-guides/val_em_and_rem.md 2.2 K · 59 lines · raw · history

1 ---
2 title: "Val::Em and Val::Rem"
3 pull_requests: [25231]
4 ---
5
6 `Val` has two new variants, `Val::Em` and `Val::Rem`, which size a length relative to a font size.
7 `Val::Em` resolves against the font size of the node it is set on, `Val::Rem` against the
8 `RemSize` resource. The `em` and `rem` helper functions construct them, alongside the existing `px`,
9 `percent`, `vw` and `vh`.
10
11 Resolving a `Val` now needs both of those font sizes, so the following methods take two additional
12 arguments, `em_size: EmSize` and `rem_size: RemSize`:
13
14 - `Val::resolve`
15 - `Val2::resolve`
16 - `UiPosition::resolve`
17 - `CornerRadius::resolve`
18 - `RadialGradientShape::resolve`
19 - `UiTransform::compute_affine`
20 - `BorderRadius::resolve`
21
22 ```rust
23 // 0.19
24 let physical = val.resolve(scale_factor, physical_base_value, physical_target_size)?;
25
26 // 0.20
27 let physical = val.resolve(
28 scale_factor,
29 physical_base_value,
30 physical_target_size,
31 em_size,
32 rem_size,
33 )?;
34 ```
35
36 `ComputedNode` has new `em_size` and `rem_size` fields holding the values that were used to lay the
37 node out, so when resolving a `Val` against an existing node you can take them from there (`box_shadow`
38 for example).
39
40 `Node` now requires `EmSize` (from `bevy_text`, re-exported in `bevy_ui::prelude`), the per-node
41 font size that `Val::Em` resolves against. If the node has a `TextFont`, `EmSize` is recomputed when `TextFont`,
42 `RemSize`, or render-target info changes; values you set persist until then. If the node does not
43 have a `TextFont` component then the value is yours to set and is left alone; it defaults to
44 `DEFAULT_REM_SIZE_PX`, which matches the default `RemSize` but does not track changes to it. Propagating
45 `EmSize` is the responsibility of an app, not `bevy_ui`.
46
47 Use `GridTrack::em`, `GridTrack::rem`, `RepeatedGridTrack::em` and `RepeatedGridTrack::rem` to construct
48 grid tracks sized in these units using new `MinTrackSizingFunction::Em`, `MinTrackSizingFunction::Rem`,
49 `MaxTrackSizingFunction::Em` and `MaxTrackSizingFunction::Rem` variants.
50
51 `FontSize::eval` now takes a `RemSize` rather than an `f32`:
52
53 ```rust
54 // 0.19
55 let size = font_size.eval(logical_viewport_size, rem_size_px);
56
57 // 0.20
58 let size = font_size.eval(logical_viewport_size, RemSize(rem_size_px));
59 ```