unleashed-firmware/applications/services/gui/view_dispatcher.h
Georgii Surkov f4122a924a
[FL-3841] FuriEventLoop Pt.2 (#3703)
* Abstract primitive type from main logic in FuriEventLoop
* Remove message_queue_i.h
* Add stream buffer support for event loop
* Add semaphore support for event loop
* Add temporary unit test workaround
* Make the linter happy
* Add mutex support for event loop
* Implement event subscription and unsubscription while the event loop is running
* Implement edge events
* Fix leftover logical errors
* Add event loop timer example application
* Implement flag-based edge trigger and one-shot mode
* Add event loop mutex example application
* Only notify the event loop if stream buffer is at or above its trigger level
* Reformat comments
* Add event loop stream buffer example application
* Add event loop multiple elements example application
* Improve event loop flag names
* Remove redundant signal handler as it is already handled by the event loop
* Refactor Power service, improve ViewHolder
* Use ViewHolder instead of ViewDispatcher in About app
* Enable ViewDispatcher queue on construction, deprecate view_dispatcher_enable_queue()
* Remove all invocations of view_dispatcher_enable_queue()
* Remove app-scened-template
* Remove missing library from target.json
* Port Accessor app to ViewHolder
* Make the linter happy
* Add example_view_holder application, update ViewHolder docs
* Add example_view_dispatcher application, update ViewDispatcher docs
* Replace FuriSemaphore with FuriApiLock, remove workaround delay
* Fix logical error
* Fix another logical error
* Use the sources directive to speed up compilation
* Use constant define macro
* Improve FuriEventLoop documentation
* Improve FuriEventLoop documentation once more
* Bump API Version
* Gui: remove redundant checks from ViewDispatcher
* Gui: remove dead ifs from ViewDispatcher

Co-authored-by: Silent <CookiePLMonster@users.noreply.github.com>
Co-authored-by: hedger <hedger@users.noreply.github.com>
Co-authored-by: あく <alleteam@gmail.com>
2024-08-07 12:49:41 +09:00

195 lines
6.3 KiB
C

/**
* @file view_dispatcher.h
* @brief GUI: ViewDispatcher API
*
* ViewDispatcher is used to connect several Views to a Gui instance, switch between them and handle various events.
* This is useful in applications featuring an advanced graphical user interface.
*
* Internally, ViewDispatcher employs a FuriEventLoop instance together with two separate
* message queues for input and custom event handling. See FuriEventLoop for more information.
*
* If no multi-view or complex event handling capabilities are required, consider using ViewHolder instead.
*
* @warning Views added to a ViewDispatcher MUST NOT be in a ViewStack at the same time.
*/
#pragma once
#include "view.h"
#include "gui.h"
#include "scene_manager.h"
#ifdef __cplusplus
extern "C" {
#endif
/** ViewDispatcher view_port placement */
typedef enum {
ViewDispatcherTypeDesktop, /**< Desktop layer: fullscreen with status bar on top of it. For internal usage. */
ViewDispatcherTypeWindow, /**< Window layer: with status bar */
ViewDispatcherTypeFullscreen /**< Fullscreen layer: without status bar */
} ViewDispatcherType;
typedef struct ViewDispatcher ViewDispatcher;
/** Prototype for custom event callback */
typedef bool (*ViewDispatcherCustomEventCallback)(void* context, uint32_t event);
/** Prototype for navigation event callback */
typedef bool (*ViewDispatcherNavigationEventCallback)(void* context);
/** Prototype for tick event callback */
typedef void (*ViewDispatcherTickEventCallback)(void* context);
/** Allocate ViewDispatcher instance
*
* @return pointer to ViewDispatcher instance
*/
ViewDispatcher* view_dispatcher_alloc(void);
/** Free ViewDispatcher instance
*
* @warning All added views MUST be removed using view_dispatcher_remove_view()
* before calling this function.
*
* @param view_dispatcher pointer to ViewDispatcher
*/
void view_dispatcher_free(ViewDispatcher* view_dispatcher);
/** Enable queue support
*
* @deprecated Do NOT use in new code and remove all calls to it from existing code.
* The queue support is now always enabled during construction. If no queue support
* is required, consider using ViewHolder instead.
*
* @param view_dispatcher ViewDispatcher instance
*/
FURI_DEPRECATED void view_dispatcher_enable_queue(ViewDispatcher* view_dispatcher);
/** Send custom event
*
* @param view_dispatcher ViewDispatcher instance
* @param[in] event The event
*/
void view_dispatcher_send_custom_event(ViewDispatcher* view_dispatcher, uint32_t event);
/** Set custom event handler
*
* Called on Custom Event, if it is not consumed by view
*
* @param view_dispatcher ViewDispatcher instance
* @param callback ViewDispatcherCustomEventCallback instance
*/
void view_dispatcher_set_custom_event_callback(
ViewDispatcher* view_dispatcher,
ViewDispatcherCustomEventCallback callback);
/** Set navigation event handler
*
* Called on Input Short Back Event, if it is not consumed by view
*
* @param view_dispatcher ViewDispatcher instance
* @param callback ViewDispatcherNavigationEventCallback instance
*/
void view_dispatcher_set_navigation_event_callback(
ViewDispatcher* view_dispatcher,
ViewDispatcherNavigationEventCallback callback);
/** Set tick event handler
*
* @param view_dispatcher ViewDispatcher instance
* @param callback ViewDispatcherTickEventCallback
* @param tick_period callback call period
*/
void view_dispatcher_set_tick_event_callback(
ViewDispatcher* view_dispatcher,
ViewDispatcherTickEventCallback callback,
uint32_t tick_period);
/** Set event callback context
*
* @param view_dispatcher ViewDispatcher instance
* @param context pointer to context
*/
void view_dispatcher_set_event_callback_context(ViewDispatcher* view_dispatcher, void* context);
/** Get event_loop instance
*
* Use the return value to connect additional supported primitives (message queues, timers, etc)
* to this ViewDispatcher instance's event loop.
*
* @warning Do NOT call furi_event_loop_run() on the returned instance, it is done internally
* in the view_dispatcher_run() call.
*
* @param view_dispatcher ViewDispatcher instance
*
* @return The event_loop instance.
*/
FuriEventLoop* view_dispatcher_get_event_loop(ViewDispatcher* view_dispatcher);
/** Run ViewDispatcher
*
* This function will start the event loop and block until view_dispatcher_stop() is called
* or the current thread receives a FuriSignalExit signal.
*
* @param view_dispatcher ViewDispatcher instance
*/
void view_dispatcher_run(ViewDispatcher* view_dispatcher);
/** Stop ViewDispatcher
*
* @param view_dispatcher ViewDispatcher instance
*/
void view_dispatcher_stop(ViewDispatcher* view_dispatcher);
/** Add view to ViewDispatcher
*
* @param view_dispatcher ViewDispatcher instance
* @param view_id View id to register
* @param view View instance
*/
void view_dispatcher_add_view(ViewDispatcher* view_dispatcher, uint32_t view_id, View* view);
/** Remove view from ViewDispatcher
*
* @param view_dispatcher ViewDispatcher instance
* @param view_id View id to remove
*/
void view_dispatcher_remove_view(ViewDispatcher* view_dispatcher, uint32_t view_id);
/** Switch to View
*
* @param view_dispatcher ViewDispatcher instance
* @param view_id View id to register
* @warning switching may be delayed till input events complementarity
* reached
*/
void view_dispatcher_switch_to_view(ViewDispatcher* view_dispatcher, uint32_t view_id);
/** Send ViewPort of this ViewDispatcher instance to front
*
* @param view_dispatcher ViewDispatcher instance
*/
void view_dispatcher_send_to_front(ViewDispatcher* view_dispatcher);
/** Send ViewPort of this ViewDispatcher instance to back
*
* @param view_dispatcher ViewDispatcher instance
*/
void view_dispatcher_send_to_back(ViewDispatcher* view_dispatcher);
/** Attach ViewDispatcher to GUI
*
* @param view_dispatcher ViewDispatcher instance
* @param gui GUI instance to attach to
* @param[in] type The type
*/
void view_dispatcher_attach_to_gui(
ViewDispatcher* view_dispatcher,
Gui* gui,
ViewDispatcherType type);
#ifdef __cplusplus
}
#endif