ra8_app.h

Go to the documentation of this file.

 
#pragma once
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <stdint.h>
 
#include "ra8_err.h"
#include "ra8_widget.h"

typedef enum : int16_t {
  k_ra8_app_none = -1, 
} ra8_app_const_t;

typedef enum : uint8_t {
  k_ra8_app_state_unmounted  = 0U, 
  k_ra8_app_state_background = 1U, 
  k_ra8_app_state_foreground = 2U, 
} ra8_app_state_t;
 
struct ra8_app; /* fwd */

typedef struct {
  ra8_err_t (*init)(struct ra8_app* a);    
  void (*on_enter)(struct ra8_app* a);     
  void (*tick)(struct ra8_app* a);         
  void (*render)(const struct ra8_app* a); 
  bool (*on_input)(struct ra8_app*           a,
                   const ra8_widget_event_t* ev); 
  void (*on_leave)(struct ra8_app* a);            
  void (*deinit)(struct ra8_app* a);              
} ra8_app_vtable_t;

typedef struct ra8_app {
  const ra8_app_vtable_t* vt;          
  void*                   ctx;         
  uint16_t                id;          
  const char*             name;        
  bool                    removable;   
  bool                    initialized; 
} ra8_app_t;

typedef struct {
  ra8_app_t** apps;   
  uint16_t    cap;    
  uint16_t    count;  
  int16_t     active; 
} ra8_app_registry_t;
 
/* ===========================================================================
 * Registry lifecycle
 * ===========================================================================
 */

[[nodiscard]] ra8_err_t
ra8_app_registry_init(ra8_app_registry_t* reg, ra8_app_t** storage, uint16_t cap);

[[nodiscard]] ra8_err_t ra8_app_register(ra8_app_registry_t* reg, ra8_app_t* app);

[[nodiscard]] ra8_err_t ra8_app_find(const ra8_app_registry_t* reg, uint16_t id, int16_t* out_idx);
 
/* ===========================================================================
 * Focus + routing
 * ===========================================================================
 */

[[nodiscard]] ra8_err_t ra8_app_launch(ra8_app_registry_t* reg, uint16_t id);

[[nodiscard]] ra8_err_t ra8_app_active(const ra8_app_registry_t* reg, ra8_app_t** out_app);

[[nodiscard]] ra8_err_t
ra8_app_route_input(ra8_app_registry_t* reg, const ra8_widget_event_t* ev, bool* out_handled);

[[nodiscard]] ra8_err_t ra8_app_tick(ra8_app_registry_t* reg);

[[nodiscard]] ra8_err_t ra8_app_render(ra8_app_registry_t* reg);

[[nodiscard]] ra8_err_t ra8_app_count(const ra8_app_registry_t* reg, uint16_t* out_count);

[[nodiscard]] ra8_err_t
ra8_app_at(const ra8_app_registry_t* reg, uint16_t idx, ra8_app_t** out_app);
 
/* ===========================================================================
 * Install / uninstall + lifecycle state
 * ===========================================================================
 */

[[nodiscard]] ra8_err_t
ra8_app_state(const ra8_app_registry_t* reg, uint16_t id, ra8_app_state_t* out_state);

[[nodiscard]] ra8_err_t ra8_app_uninstall(ra8_app_registry_t* reg, uint16_t id);
 
/* ===========================================================================
 * Navigation back-stack (history of focused apps)
 * ===========================================================================
 */

typedef struct {
  ra8_app_registry_t* reg;   
  uint16_t*           stack; 
  uint16_t            cap;   
  uint16_t            depth; 
} ra8_app_nav_t;

[[nodiscard]] ra8_err_t
ra8_app_nav_init(ra8_app_nav_t* nav, ra8_app_registry_t* reg, uint16_t* storage, uint16_t cap);

[[nodiscard]] ra8_err_t ra8_app_nav_go(ra8_app_nav_t* nav, uint16_t id);

[[nodiscard]] ra8_err_t ra8_app_nav_go_index(ra8_app_nav_t* nav, uint16_t idx);

[[nodiscard]] ra8_err_t ra8_app_nav_back(ra8_app_nav_t* nav, bool* out_popped);

[[nodiscard]] ra8_err_t ra8_app_nav_depth(const ra8_app_nav_t* nav, uint16_t* out_depth);
 
#ifdef __cplusplus
}
#endif