# Scale (/examples/widgets/scale)



Linear or circular axis with tick marks and labels, used as a standalone ruler or as a base for gauges.

Scale section bind min/max [#scale-section-bind-minmax]

<LvglExampleBrief>
  Drive a scale section's range live from two subjects.
</LvglExampleBrief>

The scale has a single styled section whose `bind_min_value`/`bind_max_value`
are wired to `subject_value2` and `subject_value` respectively. Two sliders
edit those subjects, so dragging them moves the start and end of the
highlighted band on the scale — useful for "safe range" indicators on gauges.

<LvglExample name="lv_example_scale_bind_section" path="widgets/scale/lv_example_scale_bind_section" />

Rotating compass with cardinal labels [#rotating-compass-with-cardinal-labels]

<LvglExampleBrief>
  Round scale rotates under a fixed arrow as its heading sweeps 0 to 360.
</LvglExampleBrief>

A 200 by 200 scale uses `LV_SCALE_MODE_ROUND_INNER` over 0 to 360
with a 360 degree sweep, 61 ticks, and custom labels alternating
`N`, `30`, `60`, `E`, and so on. A red `LV_SYMBOL_UP` label pins
the forward bearing at the top, and a centre label formats the
heading as `<deg>` plus the cardinal string from
`heading_to_cardinal`. An `LV_EVENT_DRAW_TASK_ADDED` callback paints
the `N` label and its tick red. An infinite 5000 ms forward and
reverse animation drives `lv_scale_set_rotation`, turning the dial
beneath the arrow.

<LvglExample name="lv_example_scale_compass" path="widgets/scale/lv_example_scale_compass" />

Heart-rate zone gauge with animated needle [#heart-rate-zone-gauge-with-animated-needle]

<LvglExampleBrief>
  Round inner scale coloured by five heart-rate zones with a bpm readout.
</LvglExampleBrief>

A 200 by 200 scale uses `LV_SCALE_MODE_ROUND_INNER` over the range
98 to 195 bpm with a 280 degree sweep rotated to 130 degrees and
15 ticks (major every third). Five sections colour the arc grey,
blue, green, orange, and red for zones 1 through 5, and a black
`lv_line` needle is placed with `lv_scale_set_line_needle_value`. A
centred circular overlay holds a flex-column container with a
Montserrat 40 bpm value and a Montserrat 18 `bpm` label. An 80 ms
`lv_timer` sweeps the displayed heart rate between 98 and 195,
updating the needle, the value, and the zone-matching text colour.

<LvglExample name="lv_example_scale_heart_rate" path="widgets/scale/lv_example_scale_heart_rate" />

Rainbow major-tick labels via draw task [#rainbow-major-tick-labels-via-draw-task]

<LvglExampleBrief>
  Recolour and reformat scale labels during 

  `LV_EVENT_DRAW_TASK_ADDED`

  .
</LvglExampleBrief>

A horizontal-bottom scale (80% width, 100 px tall, 31 ticks, range
10 to 40) enables `LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS` and subscribes
to `LV_EVENT_DRAW_TASK_ADDED`. The callback inspects each draw
task targeting `LV_PART_INDICATOR`, rewrites the label text to a
one-decimal value formatted from `id2`, picks one of seven palette
colours by tick index, and expands the draw area to fit the new
text width.

<LvglExample name="lv_example_scale_label_recolor" path="widgets/scale/lv_example_scale_label_recolor" />

Scale linear modes [#scale-linear-modes]

<LvglExampleBrief>
  Horizontal and vertical scales, ticks on either side of the rail.
</LvglExampleBrief>

Linear scales come in four flavours: `horizontal_top` / `horizontal_bottom`
lay the rail across and put ticks above or below it; `vertical_left` /
`vertical_right` rotate the same idea 90°. The four scales below share the
same tick count and value range so the only visible difference is layout.

<LvglExample name="lv_example_scale_modes" path="widgets/scale/lv_example_scale_modes" />

Round scales with animated needles [#round-scales-with-animated-needles]

<LvglExampleBrief>
  Two round inner scales driven by looping line and image needles.
</LvglExampleBrief>

Two 150 by 150 scales use `LV_SCALE_MODE_ROUND_INNER` with a 270
degree range rotated to 135 degrees, 31 ticks, and the range 10 to
40\. The left scale attaches an `lv_line` needle driven by
`lv_scale_set_line_needle_value`; the right one attaches an
`lv_image` needle (`img_hand`) driven by
`lv_scale_set_image_needle_value`. Both needles animate between 10
and 40 on an infinite 1000 ms forward and 1000 ms reverse loop.

<LvglExample name="lv_example_scale_needles" path="widgets/scale/lv_example_scale_needles" />

Scale value range [#scale-value-range]

<LvglExampleBrief>
  `min_value`

   / 

  `max_value`

   control the numeric domain the scale spans.
</LvglExampleBrief>

The two scales below share the same physical width and tick count but cover
different numeric ranges. The major tick labels are computed from
`min_value`/`max_value` divided across `total_tick_count`. Setting an
inverted range (min > max) flips the label direction without changing the
layout.

<LvglExample name="lv_example_scale_range" path="widgets/scale/lv_example_scale_range" />

Scale styling [#scale-styling]

<LvglExampleBrief>
  Style the main rail, minor ticks, and major ticks (with labels) independently.
</LvglExampleBrief>

A scale has three drawable parts: `MAIN` (the rail line/arc), `ITEMS`
(every minor tick) and `INDICATOR` (every major tick *plus* its label).
Each is targeted by `selector="main"`, `selector="items"`, and
`selector="indicator"`. Line-family properties (`line_color`/`line_width`/
`line_opa`) drive ticks and rail; text properties on `INDICATOR` style the
numeric labels. Keep the indicator line thicker than items to make
major/minor visually distinguishable.

The major-tick labels can also be rotated by the indicator's
`transform_rotation` style — `style_transform_rotation-indicator="300"`
(units of 0.1°, so 300 = 30°) tilts every label by 30°. Use this when
dense labels would otherwise overlap.

<LvglExample name="lv_example_scale_styling" path="widgets/scale/lv_example_scale_styling" />

24-hour day and night dial [#24-hour-day-and-night-dial]

<LvglExampleBrief>
  Round outer scale split into coloured day and night arcs with sunrise and sunset text.
</LvglExampleBrief>

A 210 by 210 dark grey container hosts a 150 by 150
`LV_SCALE_MODE_ROUND_OUTER` scale over the range 0 to 24 with a
full 360 degree sweep rotated to 105 degrees and 25 hourly ticks in
`lv_font_montserrat_12`. Labels `01` through `24` rotate to follow
the ticks while staying upright, and an `LV_EVENT_DRAW_TASK_ADDED`
callback whitens the `06`, `12`, `18`, and `24` labels while
greying the rest. Two sections colour the arc blue for 17 to 5
(night) and dark yellow for 5 to 17 (day). Inside the container,
a top `TODAY` heading sits above `SUNRISE 6:43` on the left and
`SUNSET 17:37` on the right, using `lv_font_montserrat_14` through `_20`.

<LvglExample name="lv_example_scale_sunset_sunrise" path="widgets/scale/lv_example_scale_sunset_sunrise" />

Scale tick configuration [#scale-tick-configuration]

<LvglExampleBrief>
  Tune tick density and which ticks count as "major" (drawn longer with labels).
</LvglExampleBrief>

`total_tick_count` is the *total* number of ticks rendered — both minor and
major. `major_tick_every` picks every Nth tick to be drawn longer and
(when `label_show="true"`) carry a numeric label. The three scales below
share the same physical width but vary their tick density.

<LvglExample name="lv_example_scale_ticks" path="widgets/scale/lv_example_scale_ticks" />