aurore::View

Draws the view (its background, content and highlight) scaled around its centre, without laying anything out again: a pressed or focused view grown or shrunk a little. Touch hit-testing keeps the unscaled frame. XML: scale="1.05".

How the view's background is drawn: none, the sidebar's, the backdrop, a plain colour or a gradient.

Sets a linear gradient background for the view, from start to end: top to bottom (VERTICAL_LINEAR) or left to right (HORIZONTAL_LINEAR).

Shakes the focus highlight towards direction: there is nothing to go to there.

The view's position and size on the screen, after layout (getX(), getY(), getWidth(), getHeight()).

The position on the screen, in layout units: the parents' positions and translations added.

The position and size in the parent, as laid out by Yoga.

The size as laid out by Yoga; the height without the collapse when includeCollapse is false.

Triggers a layout of the whole view tree. Must be called after a yoga node property is changed.

Only methods that change yoga nodes properties should call this method.

Called when a layout pass ends on that view.

Returns the view with the corresponding id in the view or its children, or nullptr if it hasn't been found.

Research is done recursively by traversing the tree starting from this view. This view's parents are not traversed.

Sets the preferred width of the view. Use aurore::View::AUTO to have the layout automatically resize the view.

If set to anything else than AUTO, the view is guaranteed to never shrink below the given width.

Sets the preferred height of the view. Use aurore::View::AUTO to have the layout automatically resize the view.

If set to anything else than AUTO, the view is guaranteed to never shrink below the given height.

Sets the preferred width and height of the view. Use aurore::View::AUTO to have the layout automatically resize the view.

If set to anything else than AUTO, the view is guaranteed to never shrink below the given height.

Shortcut to setWidth + setHeight.

Only does one layout pass instead of two when using the two methods separately.

Sets the preferred width of the view in percentage of the parent view width. Between 0.0f and 100.0f.

Sets the preferred height of the view in percentage of the parent view height. Between 0.0f and 100.0f.

Sets the minimum width of the view, in pixels.

This constraint is stronger than the grow factor: the view is guaranteed to never be less than the given min width.

Use View::AUTO to disable the min width constraint.

Sets the minimum height of the view, in pixels.

This constraint is stronger than the grow factor: the view is guaranteed to never be less than the given max height.

Use View::AUTO to disable the min height constraint.

Sets the minimum width of the view, in parent width percentage.

This constraint is stronger than the grow factor: the view is guaranteed to never be less than the given max width.

Use View::AUTO to disable the min width constraint.

Sets the minimum height of the view, in parent height percentage.

This constraint is stronger than the grow factor: the view is guaranteed to never be less than the given max height.

Use View::AUTO to disable the min height constraint.

Sets the maximum width of the view, in pixels.

This constraint is stronger than the grow factor: the view is guaranteed to never be larger than the given max width.

Use View::AUTO to disable the max width constraint.

Sets the maximum height of the view, in pixels.

This constraint is stronger than the grow factor: the view is guaranteed to never be larger than the given max height.

Use View::AUTO to disable the max height constraint.

Sets the maximum width of the view, in parent width percentage.

This constraint is stronger than the grow factor: the view is guaranteed to never be larger than the given max width.

Use View::AUTO to disable the max width constraint.

Sets the maximum height of the view, in parent height percentage.

This constraint is stronger than the grow factor: the view is guaranteed to never be larger than the given max height.

Use View::AUTO to disable the max height constraint.

Sets the grow factor of the view, aka the percentage of remaining space to give this view, in the containing box axis. Opposite of shrink. Default is 0.0f;

Sets the shrink factor of the view, aka the percentage of space the view is allowed to shrink for if there is not enough space for everyone in the contaning box axis. Opposite of grow. Default is 1.0f;

Sets the margin of the view, aka the space that separates this view and the surrounding ones in all 4 directions.

Use aurore::View::AUTO to have the layout automatically select the margin.

Only works with views that have parents - top level views that are pushed on the stack don't have parents.

Only does one layout pass instead of four when using the four methods separately.

Sets the top margin of the view, aka the space that separates this view and the surrounding ones.

Only works with views that have parents - top level views that are pushed on the stack don't have parents.

Use aurore::View::AUTO to have the layout automatically select the margin.

Sets the right margin of the view, aka the space that separates this view and the surrounding ones.

Only works with views that have parents - top level views that are pushed on the stack don't have parents.

Use aurore::View::AUTO to have the layout automatically select the margin.

Sets the bottom margin of the view, aka the space that separates this view and the surrounding ones.

Only works with views that have parents - top level views that are pushed on the stack don't have parents.

Use aurore::View::AUTO to have the layout automatically select the margin.

Sets the right margin of the view, aka the space that separates this view and the surrounding ones.

Only works with views that have parents - top level views that are pushed on the stack don't have parents.

Use aurore::View::AUTO to have the layout automatically select the margin.

Sets the visibility of the view.

Gets the visibility of the view.

Sets the top position of the view, in pixels.

The behavior of this attribute changes depending on the position type of the view.

If relative, it will simply offset the view by the given amount.

If absolute, it will behave like the "display: absolute;" CSS property and move the view freely in its parent. Use 0 to snap to the parent top edge. Absolute positioning ignores padding.

Use View::AUTO to disable (not the same as 0).

Sets the right position of the view, in pixels.

The behavior of this attribute changes depending on the position type of the view.

If relative, it will simply offset the view by the given amount.

If absolute, it will behave like the "display: absolute;" CSS property and move the view freely in its parent. Use 0 to snap to the parent right edge. Absolute positioning ignores padding.

Use View::AUTO to disable (not the same as 0).

Sets the bottom position of the view, in pixels.

The behavior of this attribute changes depending on the position type of the view.

If relative, it will simply offset the view by the given amount.

If absolute, it will behave like the "display: absolute;" CSS property and move the view freely in its parent. Use 0 to snap to the parent bottom edge. Absolute positioning ignores padding.

Use View::AUTO to disable (not the same as 0).

Sets the left position of the view, in pixels.

The behavior of this attribute changes depending on the position type of the view.

If relative, it will simply offset the view by the given amount.

If absolute, it will behave like the "display: absolute;" CSS property and move the view freely in its parent. Use 0 to snap to the parent left edge. Absolute positioning ignores padding.

Use View::AUTO to disable (not the same as 0).

Sets the top position of the view, in percents.

The behavior of this attribute changes depending on the position type of the view.

Sets the right position of the view, in percents.

The behavior of this attribute changes depending on the position type of the view.

Sets the bottom position of the view, in percentage.

The behavior of this attribute changes depending on the position type of the view.

Sets the left position of the view, in percents.

The behavior of this attribute changes depending on the position type of the view.

Sets the "position type" of the view, aka the behavior of the 4 position attributes.

Default is RELATIVE.

Sets the id of the view.

The view's id (setId, or the XML's id attribute), "" for none.

Overrides align items of the parent box.

Default is AUTO.

Sets what the width and height of the view measure.

Default is BORDER_BOX.

Sets the line color for the view. To be used with setLineTop(), setLineRight()...

The "line" is separate from the shape "border".

Sets the top line thickness. Use setLineColor() to change the line color.

The "line" is separate from the shape "border".

Sets the right line thickness. Use setLineColor() to change the line color.

The "line" is separate from the shape "border".

Sets the bottom line thickness. Use setLineColor() to change the line color.

The "line" is separate from the shape "border".

Sets the left line thickness. Use setLineColor() to change the line color.

The "line" is separate from the shape "border".

Sets the view shape background color.

Sets the view shape border color.

Sets the view shape border thickness.

Sets the view shape corner radius (uniform). 0 means no rounded corners.

Sets the view shape corner radii individually. Order: top-left, top-right, bottom-right, bottom-left.

The area of the theme's decorations this view is (docs/themes.md, Decorations): HEADER, SIDEBAR or DIALOG. Its picture (backdrop.header, .sidebar, .dialog) is drawn over the view's background, under its content, in its corners. A DIALOG in a translucent colour over a theme's background image has that image drawn under it first, dimmed by aurore/backdrop, so that it does not show the screen behind it. A HEADER is drawn across the whole width of its parent (an AppletFrame), when that parent is a screen's (not in a dialog). NONE by default; the core's header, sidebar, dialogs and dropdowns are set.

Sets the view shape shadow type. Default is NONE.

Sets the shadow visibility.

If set to true, the highlight background will be hidden for this view (the white rectangle that goes behind the view, replacing the usual background shape).

If set to true, the highlight border will be hidden for this view.

If set to true, the highlight will be hidden for this view.

No click animation when the view is clicked.

Sets the highlight padding of the view, aka the space between the highlight rectangle and the view. The highlight rect is enlarged, the view is untouched.

Sets the highlight rectangle corner radius.

Returns the "nearest" view with the corresponding id, or nullptr if none has been found. "Nearest" means the closest in the vicinity of this view. The siblings are searched as well as its children.

Research is done by traversing the tree upwards, starting from this view. The current algorithm is very inefficient.

Handles a child XML element.

You can redefine this method to handle child XML like as you want in your own views.

If left unimplemented, will throw an exception because raw views cannot handle child XML elements (Boxes can).

Applies the attributes of the given XML element to the view.

You can add your own attributes to by calling registerXMLAttribute() in the view constructor.

Applies the given attribute to the view.

You can add your own attributes to by calling registerXMLAttribute() in the view constructor.

Register a new XML attribute with the given name and handler method. You can have multiple attributes registered with the same name but different types / handlers, except if the type is string.

The method will be called if the attribute has the value "auto".

Register a new XML attribute with the given name and handler method. You can have multiple attributes registered with the same name but different types / handlers, except if the type is string.

The method will be called if the attribute has a percentage value (an integer with "%" suffix). The given float value is guaranteed to be between 0.0f and 1.0f.

Register a new XML attribute with the given name and handler method. You can have multiple attributes registered with the same name but different types / handlers, except if the type is string.

The method will be called if the attribute has an integer, float, @style or "px" value.

Register a new XML attribute with the given name and handler method. You can have multiple attributes registered with the same name but different types / handlers, except if the type is string.

The method will be called if the attribute has a string or @i18n value.

If you use string as a type, you can only have one handler for the attribute.

Register a new XML attribute with the given name and handler method. You can have multiple attributes registered with the same name but different types / handlers, except if the type is string.

The method will be called if the attribute has a color value ("#XXXXXX" or "#XXXXXXXX") or a @theme value.

Register a new XML attribute with the given name and handler method. You can have multiple attributes registered with the same name but different types / handlers, except if the type is string.

The method will be called if the attribute has a boolean value ("true" or "false").

Register a new XML attribute with the given name and handler method. You can have multiple attributes registered with the same name but different types / handlers, except if the type is string.

The method will be called if the attribute has a file path value ("@res/" or raw path).

Returns if the given XML attribute name is valid for that view.

Sets the maximum number of allowed children XML elements when using a view of that class in an XML file.

If set to true, will force the view to be translucent.

Sets the view to be focusable.

Required to be able to use actions that need focus on that view (such as an A press).

Whether the view takes the focus: focusable, and visible.

Removes view from it's parent

Sets the sound to play when this view gets focused.

Sets the detached flag to true. This action is irreversible.

A detached view will, as the name suggests, not be attached to their parent Yoga node. That means that invalidation and layout need to be taken care of manually by the parent.

detach() must be called before adding the view to the parent.

See detach().

Sets the position of the view, if detached.

Sets the position X of the view, if detached.

Sets the position Y of the view, if detached.

Gets detached position of the view.

The box this view is in (Box::addView sets it; parentUserdata is the box's own).

The action registered under identifier, or getActions().end().

Registers an action with the given parameters. The listener will be fired when the user presses the key when the view is focused.

The listener should return true if the action was consumed, false otherwise. The sound will only be played if the listener returned true.

A hidden action will not show up in the bottom-right hints.

Returns the identifier for the action, so it can be unregistered later on. Returns ACTION_NONE if the action was not registered.

The same, on a controller button.

An action on a keyboard key (a combination with modifiers): no hint, no sound.

Unregisters an action with the given identifier.

Shortcut to register a generic "A OK" click action.

Changes the hint of the action on button.

Turns the action on button on or off (an action off runs nothing and shows no hint).

The same for every action of the view.

Shows or hides the hint of the action on button (the action still works), as registerAction's hidden but while the view lives.

Plays the click animation (the flash over the view).

The view's class name ("Label", "Box"…).

The class name and the id, for logs: Label (id="title").

The view's Yoga node.

The actions registered on the view.

Get the vector of all gesture recognizers attached to that view.

Interrupt every recognizer on this view. If onlyIfUnsureState == true, only recognizers with current state UNSURE will be interupted

Add new gesture recognizer on this view.

Removes a recognizer added with addGestureRecognizer and deletes it (false if the view did not have it). Not from one of its own callbacks: the gesture being handled still uses it.

Called each frame when touch is registered.

Returns

sound to play invoked by touch recognizers.

Called each frame Do not override it to draw your view, override draw() instead

Called each frame

Called by frame() to draw the view onscreen. Views should not draw outside of their bounds (they may be clipped if they do so).

Called when the view will appear on screen, before or after layout().

Can be called if the view has already appeared, so be careful.

Called when the view will disappear from the screen.

Can be called if the view has already disappeared, so be careful.

Called when the show() animation (fade in) ends

Shows the view with a fade in animation.

Shows the view with a fade in animation, or no animation at all.

Returns the duration of the view show / hide animation.

Hides the view in a collapse animation

Whether collapse() hid the view.

The view's opacity, 0 to 1 (a transition when its style has one).

Shows the view in a expand animation (opposite of collapse)

Hides the view with a fade out animation.

Hides the view with a fade out animation, or no animation at all.

Whether hide() hid the view.

Is this view translucent?

If you override it please return

|| View::isTranslucent() to keep the fadeIn transition

Whether the view has the focus.

Returns the default view to focus when focusing this view Typically the view itself or one of its children.

Returning nullptr means that the view is not focusable (and neither are its children)

By default, a view is focusable if the flag is set to true with setFocusable() and if the view is visible.

When pressing a key, the flow is :

1. starting from the currently focused view's parent, traverse the tree upwards and repeatedly call getNextFocus() on every view until we find a next view to focus or meet the end of the tree
2. if a view is found, getNextFocus() will internally call getDefaultFocus() for the selected child
3. give focus to the result, if it exists

Returns the view to focus with the corresponding screen coordinates in the view or its children, or nullptr if it hasn't been found.

Research is done recursively by traversing the tree starting from this view. This view's parents are not traversed.

Returns the next view to focus given the requested direction and the currently focused view (as parent user data)

Returning nullptr means that there is no next view to focus in that direction - getNextFocus will then be called on our parent if any

Sets a custom navigation route from this view to the target one.

Sets a custom navigation route from this view to the target one, by ID. The final target view will be the "nearest" with the given ID.

Resolution of the ID to View is made when the navigation event occurs, not when the route is registered.

Fired when focus is gained.

Fired when focus is lost.

Fired when focus is gained on this view's parent, or the parent of the parent...

Fired when focus is lost on one of this view's parents. Works similarly to onParentFocusGained().

Fired when the window size changes, after updating layout.

Fired with the view when it gains the focus.

Fired with the view when it loses the focus.

The opacity drawn: the view's alpha times its parents'.

Forces this view and its children to use the specified theme.

Enables / disable culling for that view.

To disable culling for all child views of a Box use setCullingEnabled on the box.

The width over the height, kept by the layout (values <= 0 are ignored).

Sets the background corner radii of the view. Only for vertical linear style.

Sets the Y translation of this view.

Translation is applied after the layout phase. Use relative position and setPosition methods if possible instead.

Sets the X translation of this view.

Translation is applied after the layout phase. Use relative position and setPosition methods if possible instead.

Wireframe mode allows you to see the view size and margins (and padding if applicable) directly in your app.

Useful to diagnose views misplacements or display bugs.

Whether the children are clipped to the view's frame when drawn.

The AppletFrame the view is in, or nullptr.

Pushes view as the content of the view's AppletFrame (a page inside the frame).

Pops the AppletFrame's content back to the one before, then runs cb.

A token that expires when this view is deleted. A task that comes back to the view from another thread captures it by value and checks it on the UI thread, before it touches the view:

aurore::async([this, alive = aliveToken()] { auto result = work(); // not this: the view may be gone aurore::sync([this, alive, result] { if (alive.expired()) return; ... }); });

Checked on another thread it only says the view was alive then.

Keeps the view from being deleted by the deletion pool while a pointer to it is in use (counted: one ptrUnlock() per ptrLock()).

Whether a ptrLock() holds the view.

Deletes the view at the end of the frame (Application::addToFreeQueue).

The activity the view is in, through its parents; nullptr when none.

While state is on, the style property property takes value (as XML writes it: "#rrggbb", "rgba(…)", "@theme/…", "4", "@style/…"), and goes back to what it was when no state styles it any more. XML: focus:backgroundColor="@theme/aurore/accent", pressed:scale="0.96", disabled:alpha="0.4", hover:borderColor="#ffffff". A "@theme/" value is read when the state comes on, so it follows the theme. Returns false for a property the view does not have.

Turns a style state on or off. FOCUS, PRESSED and HOVER follow the focus, the click animation and the mouse by themselves; DISABLED is the app's (a Button sets it from its ButtonState).

Animates the changes of style properties instead of applying them at once, the state styles' as well as the setters' (setBackgroundColor…): "backgroundColor 150ms ease-out, scale 120ms" or "all 200ms". The easing is linear, ease, ease-in, ease-out, ease-in-out, or one of tweeny's (quadraticOut, backOut…). Skipped while the app asks for reduced motion (Application::getReduceMotion). An empty spec removes them. XML: transition="…". Returns false (and changes nothing) for a spec it cannot read.

The style properties the states and transitions work on, by name: backgroundColor, borderColor, lineColor (colours), borderThickness, cornerRadius, alpha, scale (numbers); a Label adds textColor, a Rectangle color, a Button textColor. Only properties that are drawn, never laid out. A subclass adds its own by overriding both and calling the base for the others.

Keeps subscription (an Observable's) as long as the view lives: what binds a view to an Observable ends with the view.

Binds a property of the view to an observable of the data models (Application::registerModel, Activity::registerModel): "text: profile.name, visible: profile.online". Properties: text (a string, int or float observable; views that have a text: Label, Button, cells), visible (bool: VISIBLE or GONE), and every style property (float or NVGcolor). Returns false for a spec it cannot read; a model not registered yet is looked up again when the view joins an activity. XML: bind="…".

Sets the view's text, for bind="text: …"; false when it has none.

What the view is and what it says, for the focus announcer (Application::setFocusAnnouncer). By default a Label says its text, a Button and the cells their title, a focusable Box the texts shown in it. XML: accessibilityRole="button", accessibilityLabel="@i18n/…".

See setAccessibilityRole().

What the view is set to, said after its role: a cell's detail, "on" or "off" for a BooleanCell, "40%" for a slider. XML: accessibilityValue="…".

The chosen one of its kind (a picker's current row, a checked radio cell): "selected" is said after its value.

Where the view is among the rows it belongs to, from 1, said as "3 of 10": a recycler's cell its row in its section, a cell, a button or a tab among the focusable views of its parent. False when that says nothing (a view alone, a label).

What is announced when the view takes the focus: its label, then its role, its value and state in the app's language and its place ("Wi-Fi, switch, on, 2 of 5"; "Save, button, disabled").

The texts shown in the view, for a label made of them: its own label for a view with no children, else the labels of the views under it (a focusable one left out: it speaks for itself), joined by ", ". Nothing for a hidden view.

Says the view's value and state again (Application::announce) when it has the focus and the user pressed or touched something in the last 2 s (not a value changing on its own): called by the views whose value changes in place (a toggle flipped, a slider moved, a detail changed).

Resolves the bindings left pending in this view and its children against activity's models (its own activity's when nullptr), then the application's. Called when a tree joins an activity.

Called on every view of the screens when the text scale changes (Application::setTextScale): a view that measures text marks itself dirty here.

Draws the style property property (backgroundColor, textColor…, see getStyleProperty) in the theme colour key ("aurore/text"), now and again each time the theme changes (a theme file, the light or dark variant). XML does it for every "@theme/…" colour. A colour the app sets on the property afterwards (setTextColor…) replaces the key. An empty key only forgets the property's key (the colour stays). Returns false for a property the view does not have or an unknown key.

The key setThemeColor gave property, "" when it has none.

Called on every view of the screens when the theme changes (Application::getThemeChangedEvent): the colours given by key (setThemeColor) take their new values, the state styles read their "@theme/" values again. A view that keeps other colours of its own looks them up again here, then calls the base. A Box goes on to its children.

Whether the highlight's border glides from the view that had the focus to the next one (140 ms), rather than jumping. On by default.

Creates a view from the given XML file content.

The method handleXMLElement() is executed for each child node in the XML.

Uses the internal lookup table to instantiate the views. Use registerXMLView() to add your own views to the table so that you can use them in your own XML files.

Creates a view from the given XML element (node and attributes).

Elements nest at most 64 levels deep, the files aurore:View includes counted (a file including itself is an error, not a stack overflow).

The method handleXMLElement() is executed for each child node in the XML.

Uses the internal lookup table to instantiate the views. Use registerXMLView() to add your own views to the table so that you can use them in your own XML files.

Creates a view from the given XML file path.

The method handleXMLElement() is executed for each child node in the XML.

Uses the internal lookup table to instantiate the views. Use registerXMLView() to add your own views to the table so that you can use them in your own XML files.

Creates a view from the given XML resource file name.

The method handleXMLElement() is executed for each child node in the XML.

Uses the internal lookup table to instantiate the views. Use registerXMLView() to add your own views to the table so that you can use them in your own XML files.

Get the XML document for the XML file, creating a new one if none is cached.

Drops the cached document of an XML file, which is then read again (hot reload). The document stays in memory: views made from it may still point into it.

Describes the document's parse error for a fatal message: where it comes from (the path, or the resource being loaded), the line and tinyxml2's own text.

Where an element is: "file:line" (the path or the resource it was loaded from), "line N" for an XML string.

fatal() for an XML error, the message prefixed with where the element being read is ("file:line: <tag>: ").

The known name closest to name (a typo's), or "" when none is close.

An enumeration's values, sorted, for an error message.

Resolves the value of the given XML attribute string. Applies i18n if the value is an "@i18n/" string, returns the string as it is otherwise.

Resolves the value of the given XML attribute file path. Returns the full path of the resource if it starts with "@res/", returns the path as it is otherwise. A resource path with ".." is refused: "".

A size or position left to the layout (auto in XML).

A folder whose xml/ files replace the built-in ones of the same name in createFromXMLResource(); one that cannot be read is logged, and the built-in one used.

The XML resource being loaded, named in the parse errors of a document given as a string.

Helper functions to apply this view's alpha to a color.

Should the hint alpha be animated when pushing the view?

The view's own role and label when the app gave none.

Called by a style property's setter before it changes the value: true when a transition takes the change over (the setter then returns without changing anything). Cheap for a view with no transition.