Skip to content
HuxerUIHuxerUIHuxerUI

Semantics API

Declared by <huxerui/semantics.h>.

Declarative semantics

Section titled “Declarative semantics”

SemanticNodeId is std::uint64_t. SemanticRole values are Generic, Text, Heading, Image, Button, Link, Checkbox, RadioButton, Switch, Slider, ProgressIndicator, TextField, SearchField, Tab, TabList, Menu, MenuItem, Dialog, Navigation, List, ListItem, Grid, GridCell, and ScrollView.

  • SemanticCheckedState: Unchecked, Checked, or Mixed.
  • SemanticLiveRegion: None, Polite, or Assertive.
  • SemanticDescendantPolicy: Preserve or Exclude.
  • Value structures: SemanticRange, SemanticCollection, and SemanticCollectionItem.

Semantics is a modifier with optional role, label, value, placeholder, hint, state description, error, identifier, checked/selected/expanded/busy/read-only/required/invalid state, heading level, range, text selection, scroll metrics, collection/item metadata, live region, descendant policy, and hidden flag.

Actions

Section titled “Actions”

SemanticActionKind values are Activate, Focus, SetText, SetSelection, SetValue, Increment, Decrement, Scroll, ShowOnScreen, Expand, Collapse, Dismiss, and Custom. SemanticActionMask maps a kind to its bit. SemanticAction carries a kind and typed variant payload.

Platform frame

Section titled “Platform frame”

SemanticNode is the fully resolved adapter record: identity/parent/children, optional platform-view identity, strings, state, range/editing/scroll/collection data, enabled/focused/multiline/secure/offscreen flags, action mask, custom actions, and world bounds. SemanticFrame contains revision, root ID, and nodes.

SemanticBuilder

Section titled “SemanticBuilder”

Extension-facing builder methods are SetOwner, AddChild(local_id, local_bounds, semantics), AddAction, and AddCustomAction. Runtime transforms local extension nodes into the final frame.

Application and adapter boundary

Section titled “Application and adapter boundary”

Application code supplies a Semantics{...} value through .With(...) when visual structure alone cannot express a label, role, state, or relationship. Built-in controls already provide their normal roles, values, state, and actions. Do not duplicate a visible child label unless the platform accessibility name genuinely needs a different value.

SemanticBuilder is for a custom NodeExtension; SemanticNode and SemanticFrame are resolved platform-adapter records. Actions return to Runtime on the UI thread through PerformSemanticAction. Platform exposure depends on the backend; the shared semantic tree existing does not by itself prove that a platform accessibility bridge is implemented.