General API reference¶

class Manager¶

grvl manager class.

This class is used as an entry point for all operations invoked on the library.

Public Functions¶

uint32_t GetWidth() const¶

Returns:¶: Width of the display in pixels.

uint32_t GetHeight() const¶

Returns:¶: Height of the display in pixels.

Manager &SetTransparency(float value, uint32_t milliseconds)¶

Sets transparency. TODO - Adjust the description

Remark

Calling this method will invoke registered callback called ‘set_layer_transparency’ with provided argument. It does not change internal state of a library.

Parameters:¶

float value¶: Transparency value.

Manager &SetActiveScreen(const char *activeScreenId, int8_t direction)¶

Changes currently displayed screen with optional animation.

Parameters:¶

const char *activeScreenId¶: Identifier of a screen to display.
int8_t direction¶: Direction of animation (-1 = to the left, 1 = to the right, 0 = no animation)

Manager &SetLoadingImage(const Image &image)¶

Sets an image that is displayed while the application is loading its resources.

Remark

In order to switch from loading to normal state, application should call InitializationFinished method.

Parameters:¶

const Image &image¶: Reference to image object that should be displayed when loading.

Manager &SetCollectionImage(const Image &image)¶

Sets image that is displayed as screen collection indicator.

Parameters:¶

const Image &image¶: Reference to the image to display.

Manager &SetBackgroundColor(uint32_t color)¶

Sets background color for underlying layer.

Remark

Calling this method will invoke registered callback called ‘set_background_color’ with provided argument. It does not change internal state of a library.

Parameters:¶

uint32_t color¶: Background color in format acceptable by the provided callback.

void ProcessTouchPoint(bool touched, uint32_t touchX, uint32_t touchY)¶

Handles touch event.

Parameters:¶

bool touched¶: Indicates if the display is touched.
uint32_t touchX¶: Position in axis X where the touch event was detected.
uint32_t touchY¶: Position in axis Y where the touch event was detected.

Manager &SetOverlayInfo(const std::string &info)¶

Sets application-specific information displayed in the performance overlay.

The value is copied by the manager and displayed on a separate line.

Parameters:¶

const std::string &info¶: Application information, e.g. application name and version.

void ShowPopup(const char *Style)¶

Displays pop-up window.

Parameters:¶

const char *Style¶: Name of the style defined in XML document.

void ShowKeyboard()¶: Displays keyboard pop-up window if defined.

void SetActiveInput(TextInput *destinationInput)¶: Sets the curren active text input - triggers ShowKeyboard.

void RequestAutoFocus(const char *elementId)¶: Remembers the element that takes focus when a screen holding it is opened. Called by TextInput for autoFocus=”true”.

void SwitchKeyboardKeys()¶: Switches keyboard pop-up keys.

void ClosePopup()¶: Closes last pop-up window.

void InitializationFinished()¶

Switches library to normal state when screens are displayed.

Remark

Before calling this method loading image (if defined) is displayed.

bool NeedsFrames() const¶: Returns true if the next frames should be rendered even without any new input.

AbstractView *GetScreen(const char *id)¶

Gets screen based on its name.

Parameters:¶

const char *id¶: Name of the screen.

Returns:¶

Pointer to a screen or NULL if not found.

AbstractView *GetScreen(int id)¶

Gets screen based on its location.

Parameters:¶

int id¶: Numerical identifier of a screen (zero-based).

Returns:¶

Pointer to the screen or NULL if not found.

Manager &AddImageContentToContainer(std::string name, ImageContent *image)¶

Registers image content in content manager.

The image content will be accessible for other components by the provided name.

Remark

It is advised to use content manager when image content is shared by different components, as it will save memory.

Parameters:¶

std::string name¶: Image content’s identifier.
ImageContent *image¶: Image content object.

Manager &BindImageContentToImage(const std::string &contentName, Image *image)¶

Binds registered image content to an image object.

Parameters:¶

const std::string &contentName¶: Identifier of the content.
Image *image¶: Image object.

Manager &AddCallbackToContainer(const std::string &name, Event::CallbackPointer Callback)¶

Registers callback method for an event.

Remark

This method filters out empty callbacks (i.e., NULLs).

Parameters:¶

const std::string &name¶: Identifier of an event that should invoke the callback.
Event::CallbackPointer Callback¶: Callback that should be called on event.

Event GetOrCreateCallback(const std::string &callbackFunctionName, const Event::ArgVector &callbackArgs)¶

Tries to search if there is callback defined with C/C++ code (added by AddCallbackToContainer), if not then it creates new one that will call JavaScript code with provided constant args.

Parameters:¶

const std::string &callbackFunctionName¶: Identifier of a function invoked by the callback.
const Event::ArgVector &callbackArgs¶: Constant args that will be passed as callback function arguments

Manager &AddFontToFontContainer(const std::string &name, Font *font)¶

The font will be accessible for other components by the provided name.

Remark

It is advised to use content manager when font is used by multiple components, as it will save memory.

Parameters:¶

const std::string &name¶: Font’s identifier.
Font *font¶: Font object.

void AddKeyMappingToContainer(uint32_t code, const std::string &name, uint32_t repeat)¶: Adds or replaces a mapping by backend-native code (including full SDL symbols). repeat is the long-press repeat interval in milliseconds.

void AddDefaultKeyMappingToContainer(uint32_t code, const std::string &name, uint32_t repeat)¶: Installs a backend default without replacing an existing mapping.

int32_t BuildFromXML(const char *filename)¶

Loads screens from XML file.

Parameters:¶

const char *filename¶: Path to the file with screens definition.

Returns:¶

Result of parsing the file (0 = OK, -1 = there was an error)

void Draw()¶: Redraws content of a display based on current state of components.

void MainLoopIteration(bool shouldDraw = true)¶

Executes an iteration of processing loop.

This method handles pop-up windows, processes events and redraw screen if needed.

Manager &SetLoaderCallback(const ContentManager::LoaderCallback &callback)¶

Registers method that is called when request for external content is issued by the library.

Parameters:¶

const ContentManager::LoaderCallback &callback¶: Pointer to the method to call.

bool ShouldRedraw()¶: Check whether the screen should be redrawn this is based on multiple factors, including displayed animations, user inputs and manual requests.

void MarkUserActivity()¶: Mark that the user performed some action other than whats already handled (key, touch, text), additionally marks the screen for redraw

void ScheduleRedraw()¶: Manually mark the screen for redraw. Works like MarkUserActivity() but doesn’t affect the timestamp returned by GetLastInputTimestamp() call.

void SetIdleThrottle(bool throttle)¶: Set whether to limit FPS when there is no user input or animations present.

uint64_t GetLastInputTimestamp()¶: Get a timestamp, in milliseconds, of the last user input This includes any calls to MarkUserActivity(). This is unaffected by calls to ScheduleRedraw().

Public Members¶

Painter painter¶: Deprecated. Do not use painter directly, painter can only be used from specific contexts! Set a render hook with SetRenderCallback() to gain access to a Painter methods correctly. TODO make private

class KeyData¶

class ImageContent¶

Last update: 2026-11-05