aurore::Application

The keyboard keys that press a controller button, on top of Enter (A), Escape (B) and the arrows. By default X, Y, L, R, Shift+L (ZL), Shift+R (ZR), P or + (Plus), M or - (Minus) and Backspace (B); keys are named after their place on a US keyboard (docs/input.md). A key a view registers an action for keeps that action only, and none applies while a text is being typed.

The keyboard keys that press a controller button, on top of Enter (A), Escape (B) and the arrows. By default X, Y, L, R, Shift+L (ZL), Shift+R (ZR), P or + (Plus), M or - (Minus) and Backspace (B); keys are named after their place on a US keyboard (docs/input.md). A key a view registers an action for keeps that action only, and none applies while a text is being typed.

The keyboard keys that press a controller button, on top of Enter (A), Escape (B) and the arrows. By default X, Y, L, R, Shift+L (ZL), Shift+R (ZR), P or + (Plus), M or - (Minus) and Backspace (B); keys are named after their place on a US keyboard (docs/input.md). A key a view registers an action for keeps that action only, and none applies while a text is being typed.

The keyboard keys that press a controller button, on top of Enter (A), Escape (B) and the arrows. By default X, Y, L, R, Shift+L (ZL), Shift+R (ZR), P or + (Plus), M or - (Minus) and Backspace (B); keys are named after their place on a US keyboard (docs/input.md). A key a view registers an action for keeps that action only, and none applies while a text is being typed.

Inits the Aurore application. Returns true if it succeeded, false otherwise.

Sets the application ID reported to the windowing system (Wayland app_id / X11 WM_CLASS). Desktop environments use it to associate the window with its .desktop entry, which is required for showing the correct icon in the taskbar. Must be called before createWindow().

The application ID given to setAppId(), "" by default.

Aurore draws every app in Cadran's look (docs/cadran.md): init() and createWindow() start it. false, before init(), keeps Aurore's own look instead.

Whether the app is drawn in Cadran's look (see setCadran()).

Creates the application window with the given title. Must be called after calling init().

Application main loop iteration. Must be called in an infinite loop until it returns false.

The platform the app runs on (window, inputs, video, audio, fonts), made by init().

The platform's sound player.

The Yoga configuration every view's node is created with (web defaults, yoga's messages in the log).

The nanovg context every view draws with.

Called by the video context when the content window is resized

Do not call this function, use it internally. Called when the video context is ready (to setup the initial content scaling).

Called by the video context when the content window is Repositioned

Do not call this function, use it internally. Called when the video context is ready (to setup the initial window position).

A copy of the stack of activities, the first pushed first.

Pushes a view on this applications's view stack.

The view will automatically be resized to take the whole screen.

The view will gain focus if applicable.

The first activity to be pushed cannot be popped.

Pushes the activity in place of the one on top, in one transition: the one replaced is not shown again on the way, nor given the focus back later, and is deleted once the new one is shown (a wizard's next step, a sign-in screen giving way to the home screen). With an empty stack it is a push.

Pops the last pushed activity from the stack and gives focus back where it was before.

return false if no actifity to pop.

Gives the focus to the given view or clears the focus if given nullptr.

Drops every reference the focus system holds to a view that is being destroyed.

When on, the focus highlight fades out after a moment without any button pressed (0.8 s, then 0.4 s), and comes back at the next one: for a screen watched more than browsed (a player, a slideshow). Off by default.

Called with the focused view's description (View:: getAccessibilityDescription: "Save, button") each time the focus moves: where a screen reader, a text-to-speech engine or a log plugs in. Nothing by default; an empty function removes it.

Gives text to the focus announcer, outside of a focus move: a value changed in place (View::announceAccessibilityValue), a toast (notify says its text). Nothing for an empty text. getLastAnnouncement() is the last text given, announcer or not (for tests).

Reduced motion: the movements that are only there for show are skipped (the transition= of views, the highlight's glide, the scrolling of lists and of texts cut short, the toasts' and dropdowns' slide, the switch cells' bounce; Cadran's entrances, glides and breathing glow). Off by default. getReduceMotion(), which transitions read, is also true while Cadran's effects leave movement out (Preferences › Visual effects "reduced", the lighter effects in hand, AURORE_STILL_FOCUS); the highlight's glide follows the app's setting only.

The app's own setting alone, without Cadran's.

When the last input came (a button, a key, a touch, the mouse), on the clock of getCPUTimeUsec(): what the theme's particles stop after.

Every Label drawn scale times its size (Label::setFontScale), and the screens laid out again for it at once (every view told through View::onTextScaleChanged). 1 by default; Cadran's text size setting goes through here.

The density of the lengths (aurore::setDensity): DENSITY_COMFORTABLE by default, DENSITY_COMPACT, DENSITY_DENSE for a small screen. The text keeps its size (setTextScale). Read when the views are made: set it before the first screen; AURORE_DENSITY gives it on the desktop.

The class of the screen's width now (widthClassOf(contentWidth)). XML reads it when a view is made; a view that lays itself out in code reads it there too, and the window size changed event says when it may have changed. ORIGINAL_WINDOW_WIDTH sets it for a small screen (480 on a 320-pixel one); AURORE_DESIGN_SIZE=480x360 tries it on the desktop.

Lays every screen out for preset (PRESET_SMALL_SCREEN on a small screen): its design size, density and text scale. Before init(); a platform may give one (Platform::getLayoutPreset), the app's wins, and AURORE_PRESET (small or standard) wins over both on the desktop.

The text scale of the preset in use (1 without one): what Cadran's text size setting multiplies.

The data models XML bindings read (View::bind, bind="text: name.key"), by name, for every screen. An Activity's own (Activity::registerModel) come first. The model must outlive its registration.

The view under the mouse pointer that has a hover: style (desktop), or nullptr.

The metrics in use (aurore::getStyle()).

The colours of the variant in use (light or dark), with the theme file's over them.

The variant in use, as the platform reports it.

Fired when the theme changed: another variant (Platform::setThemeVariant), a theme file (Theme::loadFile, Theme::reset) or a colour changed (Theme::addColor). Checked once a frame, before it is drawn; by then every view of the screens took the change (View::onThemeChanged). For what keeps colours of its own.

Whether the theme in use draws a picture behind the screens in the variant in use (its background_image, loaded).

Draws what is behind the screens over x, y, width, height: the clear colour, the theme's background image and its veil. For a panel drawn over other views in a translucent surface colour (a drawer over a page), so that it hides them and still shows the picture. Nothing without a background image.

The same in a shape with round corners of radius, and the strips of the theme's decorations (decor.top, decor.bottom) over it: under a translucent dialog or sheet (View::setThemeArea).

The platform's text input (the keyboard shown for an EditTextDialog).

Loads a font from a given file and stores it in the font stash. A AURORE_ASSET() path ("@res/...") is read from the resources built into the program when they are (USE_LIBROMFS). Returns true if the operation succeeded.

Loads a font from a given memory buffer and stores it in the font stash. Returns true if the operation succeeded.

The same, with the face at faceIndex of a font collection (.ttc).

Returns the nanovg handle to the given font name, or FONT_INVALID if no such font is currently loaded.

Glyphs missing from the font loaded as font are looked up in the one loaded as fallback. False when either is not loaded.

The font a new Label draws with: the regular font (the Chinese one on the Switch).

Shows a toast with text, and leading (an icon) before it when given; the focus announcer says the text.

Handles a controller button as the main loop does: the focused view's actions first, then the focus moves. For the platforms and the test harness.

Handles a key as the main loop does (the actions registered on keys).

"Crashes" the app (displays a fullscreen CrashFrame) Shows text in a dialog that cannot be dismissed, with one button that quits the app: for an error the app cannot go on after. Can be called from any thread.

Asks the main loop to stop: the next mainLoop() returns false, after the exit events.

Deletes every activity on the stack and clears the focus.

Blocks any and all user inputs

Unblocks inputs after a call to blockInputs()

Whether blockInputs() is in force.

The controller's buttons and sticks as read this frame.

A text the app keeps for its footers (the library does not draw it).

Caps how large the UI is allowed to grow relative to the design size. Set to 0 to disable the cap.

Sets whether BUTTON_START will globally be used to close the application.

Whether getFPS() is counted (60 when off).

The frames per second over the last second.

Set the FPS limit

Set the swap interval Must be called after createWindow. On some platforms, it is impossible to set it back to 0 after setting it to a non-zero values, so you can use VideoContext::swapInterval = 0; (#include "aurore/core/video.hpp") before creating the window.

Test results:

Platforms that always vsync (interval: 1):

iOS18/GLES3/SDL PS4/GLES2/SDL

Platforms that only support enable and disable vsync (interval: 0,1):

Android9/GLES2/SDL macOS13.0+/GL3.2/GLFW (will fixed to 120fps with vsync enabled, https://github.com/glfw/glfw/pull/2277) Windows11/GL3.2/GLFW Linux Wayland/GL3.2/GLFW

Platforms that not support disable vsync (interval: 1,2,3,4):

Windows11/D3D11/GLFW Switch/DEKO3D

Platforms that support arbitrary values (interval: 0,1,2,3,4):

PsVita/GXM PsVita/GLES2/SDL macOS13.0+/GL3.2/SDL Linux X11/GL3.2/GLFW Linux X11/GL3.2/SDL Linux Wayland/GL3.2/SDL Switch/GL4.3/GLFW Switch/GL4.3/SDL

If the value is set to true, the program will limit FPS to Application::DeactivatedFPS after Application::DeactivatedTime milliseconds of inactivity.

default is false;

See setAutomaticDeactivation().

Whether the app is active: an input lately, an animation under way, or no automatic deactivation. Always true on the Switch.

Marks the app active now (and asks for a redraw), or no longer.

After this long without an input, the app is drawn at the deactivated FPS.

The frame rate once deactivated (5 by default).

A frame's time once deactivated, in seconds.

Redraw on demand: a frame is drawn only when something may have changed on screen (an input, a running animation, a sync or delayed task that ran, a view's layout invalidated, a window resized, or requestRedraw()), and at least once a second. On the other frames the inputs are still read, but nothing is drawn or presented, which saves most of the CPU and GPU time of an idle screen.

A view that changes how it looks without any of these (a colour set from a timer of its own...) calls requestRedraw().

default is false: every frame is drawn.

See setRedrawOnDemand().

Asks for the next frames to be drawn, with redraw on demand.

Number of frames drawn since the start (frames skipped by redraw on demand are not counted).

Debugging redraw on demand: each frame it skips is drawn all the same, without being presented, and compared with the last frame presented. A difference is something that changed on screen without asking for a redraw (a missing invalidate() or requestRedraw()): it is logged as a warning, with the area and the views drawn there (once per area). Reads every frame back: slow, and OpenGL drivers only. Off by default; AURORE_REDRAW_DEBUG=1 in the environment turns it on (desktop).

See setRedrawDebug().

With setRedrawDebug(): the number of skipped frames found different from the last frame presented, and the last such area, in the views' coordinates.

Fired with the new focus each time the focus moves.

Fired when the footer's hints must be read again (the focus moved, keys swapped).

Fired when the input type changes (a touch after the buttons, or the reverse).

Fired once per main loop iteration, after the frame and the sync tasks.

Fired after each frame presented.

Fired when the app starts to exit, before the activities are deleted.

Fired once the activities and the views left are deleted.

Fired when the window's size changed.

Fired at the end of createWindow().

Fired when the window is closed or quit() was asked, before the exit.

Fired with true or false when the window gains or loses the system's focus.

The view that has the focus, or nullptr.

The window's title, as given to createWindow().

Registers a view to be created from XML. You must give the name of the XML node as well as a function that creates the view.

If you need attributes, register them with the given functions in the view class constructor directly. They will be called one by one after the view is instantiated.

You should not add any children in the function, it is already taken care of.

Whether an XML tag is registered (registerXMLView()).

The XML tags registered (registerXMLView).

The function registered for an XML tag.

Returns the current system locale.

Deletes view at the end of the current main loop iteration (once no ptrLock() holds it). View::freeView() calls it.

Returns the current input type.

The built-in inspector (docs/inspector.md): F12 on a keyboard, or both sticks pressed in together (L3 + R3) on a controller, opens it over the screen with the view tree, the focus chain, the yoga box and the theme values of a view, and the frame's timings. Off by default; the AURORE_INSPECTOR CMake option, or AURORE_INSPECTOR=1 in the environment on a desktop, turns it on at init(). Closed, it only watches for its toggle.

See setInspectorEnabled().

Hot reload, on a desktop (docs/hot_reload.md): the XML files the activity on top was built from, and the files read by Theme::loadFile(), are watched, and the activity is built again when one of them changes (the focus is put back where it was when it can be). resourcesDir, when given, is a resources folder (the app's sources' resources/) the XML files are read from in place of the ones built in (libromfs) or copied next to the app. Off by default; AURORE_HOT_RELOAD=1, or AURORE_HOT_RELOAD=<resources folder>, in the environment turns it on at init(). Does nothing on the consoles.

See setHotReload().

Builds the content of the activity on top again from its createContentView(), as hot reload does. False when it cannot (an activity given its view in its constructor) or the new content throws while being made (its XML, onContentAvailable(), or a tab shown, made when it takes the focus): the old one then stays, with the focus, and the error is shown in a notification.

Draws the debug layer (DebugLayer) over the app.

Swaps A and B (and X and Y) for the app's actions, as on a Japanese console.

Draws the mouse pointer with nanovg (for platforms with no system pointer).

See setHintsLiteMode().

Set hints lite mode, which will only show hints for A button and B button.

Stops the touch gestures view is tracking, before it is removed.

Reads key each frame from now on (counted: one removeWatchedKeys() per add).

See addToWatchedKeys().

The design width, in layout units.

The design height.

See setAppId().

The size of the UI in layout units: ORIGINAL_WINDOW_WIDTH wide, as high as the window's ratio gives.

usePreset() called by the app

The window's size in pixels.

The window's position on the screen (desktop).

Pixels per layout unit (windowWidth / ORIGINAL_WINDOW_WIDTH, capped by setMaximumUIScale()).

See setMaximumUIScale().