From 8e0f7cfb725b874baede31e8d7e28cffe04cba13 Mon Sep 17 00:00:00 2001 From: "Aaron Tulino (Aaronjamt)" Date: Tue, 23 Sep 2025 10:15:55 -0700 Subject: [PATCH] Add usage example app --- .../example_date_time_input/ReadMe.md | 13 +++ .../example_date_time_input/application.fam | 9 +++ .../example_date_time_input.c | 79 ++++++++++++++++++ .../example_date_time_input.h | 36 +++++++++ .../scenes/example_date_time_input_scene.c | 31 +++++++ .../scenes/example_date_time_input_scene.h | 29 +++++++ .../example_date_time_input_scene_config.h | 2 + ...le_date_time_input_scene_input_date_time.c | 47 +++++++++++ ...ple_date_time_input_scene_show_date_time.c | 81 +++++++++++++++++++ .../services/gui/modules/date_time_input.c | 9 --- .../services/gui/modules/date_time_input.h | 7 -- targets/f7/api_symbols.csv | 3 +- 12 files changed, 328 insertions(+), 18 deletions(-) create mode 100644 applications/examples/example_date_time_input/ReadMe.md create mode 100644 applications/examples/example_date_time_input/application.fam create mode 100644 applications/examples/example_date_time_input/example_date_time_input.c create mode 100644 applications/examples/example_date_time_input/example_date_time_input.h create mode 100644 applications/examples/example_date_time_input/scenes/example_date_time_input_scene.c create mode 100644 applications/examples/example_date_time_input/scenes/example_date_time_input_scene.h create mode 100644 applications/examples/example_date_time_input/scenes/example_date_time_input_scene_config.h create mode 100644 applications/examples/example_date_time_input/scenes/example_date_time_input_scene_input_date_time.c create mode 100644 applications/examples/example_date_time_input/scenes/example_date_time_input_scene_show_date_time.c diff --git a/applications/examples/example_date_time_input/ReadMe.md b/applications/examples/example_date_time_input/ReadMe.md new file mode 100644 index 000000000..b153965cc --- /dev/null +++ b/applications/examples/example_date_time_input/ReadMe.md @@ -0,0 +1,13 @@ +# Date/Time Input {#example_date_time_input} + +Simple view that allows the user to adjust a date and/or time. + +## Source code + +Source code for this example can be found [here](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/examples/example_date_time_input). + +## General principle + +Callbacks can be defined for every time a value is edited (useful for application-specific bounds checking or validation) and for when the user is done editing (back button is pressed). The provided DateTime object is used both as the initial value and as the place where the result is stored. + +The fields which the user is allowed to edit can be defined using `date_time_input_set_editable_fields()`. Disabled fields are shown but aren't able to be selected and don't have an outer box. If all fields are disabled, the view is read-only and no cursor will be shown. diff --git a/applications/examples/example_date_time_input/application.fam b/applications/examples/example_date_time_input/application.fam new file mode 100644 index 000000000..7f6435840 --- /dev/null +++ b/applications/examples/example_date_time_input/application.fam @@ -0,0 +1,9 @@ +App( + appid="example_date_time_input", + name="Example: Date/Time Input", + apptype=FlipperAppType.EXTERNAL, + entry_point="example_date_time_input", + requires=["gui"], + stack_size=1 * 1024, + fap_category="Examples", +) diff --git a/applications/examples/example_date_time_input/example_date_time_input.c b/applications/examples/example_date_time_input/example_date_time_input.c new file mode 100644 index 000000000..7510f5c52 --- /dev/null +++ b/applications/examples/example_date_time_input/example_date_time_input.c @@ -0,0 +1,79 @@ +#include "example_date_time_input.h" + +bool example_date_time_input_custom_event_callback(void* context, uint32_t event) { + furi_assert(context); + ExampleDateTimeInput* app = context; + return scene_manager_handle_custom_event(app->scene_manager, event); +} + +static bool example_date_time_input_back_event_callback(void* context) { + furi_assert(context); + ExampleDateTimeInput* app = context; + return scene_manager_handle_back_event(app->scene_manager); +} + +static ExampleDateTimeInput* example_date_time_input_alloc() { + ExampleDateTimeInput* app = malloc(sizeof(ExampleDateTimeInput)); + app->gui = furi_record_open(RECORD_GUI); + + app->view_dispatcher = view_dispatcher_alloc(); + + app->scene_manager = scene_manager_alloc(&example_date_time_input_scene_handlers, app); + view_dispatcher_set_event_callback_context(app->view_dispatcher, app); + view_dispatcher_set_custom_event_callback( + app->view_dispatcher, example_date_time_input_custom_event_callback); + view_dispatcher_set_navigation_event_callback( + app->view_dispatcher, example_date_time_input_back_event_callback); + + app->date_time_input = date_time_input_alloc(); + view_dispatcher_add_view( + app->view_dispatcher, + ExampleDateTimeInputViewIdDateTimeInput, + date_time_input_get_view(app->date_time_input)); + + app->dialog_ex = dialog_ex_alloc(); + view_dispatcher_add_view( + app->view_dispatcher, + ExampleDateTimeInputViewIdShowDateTime, + dialog_ex_get_view(app->dialog_ex)); + + // Fill in current date & time + furi_hal_rtc_get_datetime(&app->date_time); + app->edit_date = false; + app->edit_time = false; + + return app; +} + +static void example_date_time_input_free(ExampleDateTimeInput* app) { + furi_assert(app); + + view_dispatcher_remove_view(app->view_dispatcher, ExampleDateTimeInputViewIdShowDateTime); + dialog_ex_free(app->dialog_ex); + + view_dispatcher_remove_view(app->view_dispatcher, ExampleDateTimeInputViewIdDateTimeInput); + date_time_input_free(app->date_time_input); + + scene_manager_free(app->scene_manager); + view_dispatcher_free(app->view_dispatcher); + + furi_record_close(RECORD_GUI); + app->gui = NULL; + + free(app); +} + +int32_t example_date_time_input(void* p) { + UNUSED(p); + ExampleDateTimeInput* app = example_date_time_input_alloc(); + + view_dispatcher_attach_to_gui(app->view_dispatcher, app->gui, ViewDispatcherTypeFullscreen); + + scene_manager_next_scene(app->scene_manager, ExampleDateTimeInputSceneShowDateTime); + + view_dispatcher_run(app->view_dispatcher); + + example_date_time_input_free(app); + + return 0; +} diff --git a/applications/examples/example_date_time_input/example_date_time_input.h b/applications/examples/example_date_time_input/example_date_time_input.h new file mode 100644 index 000000000..6363535f9 --- /dev/null +++ b/applications/examples/example_date_time_input/example_date_time_input.h @@ -0,0 +1,36 @@ +#pragma once + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include + +#include "scenes/example_date_time_input_scene.h" + +typedef struct ExampleDateTimeInputShowDateTime ExampleDateTimeInputShowDateTime; + +typedef enum { + ExampleDateTimeInputViewIdShowDateTime, + ExampleDateTimeInputViewIdDateTimeInput, +} ExampleDateTimeInputViewId; + +typedef struct { + Gui* gui; + SceneManager* scene_manager; + ViewDispatcher* view_dispatcher; + + DateTimeInput* date_time_input; + DialogEx* dialog_ex; + + DateTime date_time; + + bool edit_date; + bool edit_time; +} ExampleDateTimeInput; diff --git a/applications/examples/example_date_time_input/scenes/example_date_time_input_scene.c b/applications/examples/example_date_time_input/scenes/example_date_time_input_scene.c new file mode 100644 index 000000000..ed3f538f2 --- /dev/null +++ b/applications/examples/example_date_time_input/scenes/example_date_time_input_scene.c @@ -0,0 +1,31 @@ +#include "example_date_time_input_scene.h" + +// Generate scene on_enter handlers array +#define ADD_SCENE(prefix, name, id) prefix##_scene_##name##_on_enter, +void (*const example_date_time_input_on_enter_handlers[])(void*) = { +#include "example_date_time_input_scene_config.h" +}; +#undef ADD_SCENE + +// Generate scene on_event handlers array +#define ADD_SCENE(prefix, name, id) prefix##_scene_##name##_on_event, +bool (*const example_date_time_input_on_event_handlers[])(void* context, SceneManagerEvent event) = + { +#include "example_date_time_input_scene_config.h" +}; +#undef ADD_SCENE + +// Generate scene on_exit handlers array +#define ADD_SCENE(prefix, name, id) prefix##_scene_##name##_on_exit, +void (*const example_date_time_input_on_exit_handlers[])(void* context) = { +#include "example_date_time_input_scene_config.h" +}; +#undef ADD_SCENE + +// Initialize scene handlers configuration structure +const SceneManagerHandlers example_date_time_input_scene_handlers = { + .on_enter_handlers = example_date_time_input_on_enter_handlers, + .on_event_handlers = example_date_time_input_on_event_handlers, + .on_exit_handlers = example_date_time_input_on_exit_handlers, + .scene_num = ExampleDateTimeInputSceneNum, +}; diff --git a/applications/examples/example_date_time_input/scenes/example_date_time_input_scene.h b/applications/examples/example_date_time_input/scenes/example_date_time_input_scene.h new file mode 100644 index 000000000..5664bad3d --- /dev/null +++ b/applications/examples/example_date_time_input/scenes/example_date_time_input_scene.h @@ -0,0 +1,29 @@ +#pragma once + +#include + +// Generate scene id and total number +#define ADD_SCENE(prefix, name, id) ExampleDateTimeInputScene##id, +typedef enum { +#include "example_date_time_input_scene_config.h" + ExampleDateTimeInputSceneNum, +} ExampleDateTimeInputScene; +#undef ADD_SCENE + +extern const SceneManagerHandlers example_date_time_input_scene_handlers; + +// Generate scene on_enter handlers declaration +#define ADD_SCENE(prefix, name, id) void prefix##_scene_##name##_on_enter(void*); +#include "example_date_time_input_scene_config.h" +#undef ADD_SCENE + +// Generate scene on_event handlers declaration +#define ADD_SCENE(prefix, name, id) \ + bool prefix##_scene_##name##_on_event(void* context, SceneManagerEvent event); +#include "example_date_time_input_scene_config.h" +#undef ADD_SCENE + +// Generate scene on_exit handlers declaration +#define ADD_SCENE(prefix, name, id) void prefix##_scene_##name##_on_exit(void* context); +#include "example_date_time_input_scene_config.h" +#undef ADD_SCENE diff --git a/applications/examples/example_date_time_input/scenes/example_date_time_input_scene_config.h b/applications/examples/example_date_time_input/scenes/example_date_time_input_scene_config.h new file mode 100644 index 000000000..db3b128da --- /dev/null +++ b/applications/examples/example_date_time_input/scenes/example_date_time_input_scene_config.h @@ -0,0 +1,2 @@ +ADD_SCENE(example_date_time_input, input_date_time, InputDateTime) +ADD_SCENE(example_date_time_input, show_date_time, ShowDateTime) diff --git a/applications/examples/example_date_time_input/scenes/example_date_time_input_scene_input_date_time.c b/applications/examples/example_date_time_input/scenes/example_date_time_input_scene_input_date_time.c new file mode 100644 index 000000000..8a1288c38 --- /dev/null +++ b/applications/examples/example_date_time_input/scenes/example_date_time_input_scene_input_date_time.c @@ -0,0 +1,47 @@ +#include "../example_date_time_input.h" + +void example_date_time_input_scene_input_date_time_callback(void* context) { + ExampleDateTimeInput* app = context; + view_dispatcher_send_custom_event(app->view_dispatcher, 0); +} + +void example_date_time_input_scene_input_date_time_on_enter(void* context) { + furi_assert(context); + ExampleDateTimeInput* app = context; + DateTimeInput* date_time_input = app->date_time_input; + + date_time_input_set_result_callback( + date_time_input, + NULL, + example_date_time_input_scene_input_date_time_callback, + context, + &app->date_time); + + date_time_input_set_editable_fields( + date_time_input, + + app->edit_date, + app->edit_date, + app->edit_date, + + app->edit_time, + app->edit_time, + app->edit_time); + + view_dispatcher_switch_to_view(app->view_dispatcher, ExampleDateTimeInputViewIdDateTimeInput); +} + +bool example_date_time_input_scene_input_date_time_on_event(void* context, SceneManagerEvent event) { + ExampleDateTimeInput* app = context; + bool consumed = false; + + if(event.type == SceneManagerEventTypeCustom) { //Back button pressed + scene_manager_previous_scene(app->scene_manager); + return true; + } + return consumed; +} + +void example_date_time_input_scene_input_date_time_on_exit(void* context) { + UNUSED(context); +} diff --git a/applications/examples/example_date_time_input/scenes/example_date_time_input_scene_show_date_time.c b/applications/examples/example_date_time_input/scenes/example_date_time_input_scene_show_date_time.c new file mode 100644 index 000000000..666db14a6 --- /dev/null +++ b/applications/examples/example_date_time_input/scenes/example_date_time_input_scene_show_date_time.c @@ -0,0 +1,81 @@ +#include "../example_date_time_input.h" + +static void + example_date_time_input_scene_confirm_dialog_callback(DialogExResult result, void* context) { + ExampleDateTimeInput* app = context; + + view_dispatcher_send_custom_event(app->view_dispatcher, result); +} + +static void example_date_time_input_scene_update_view(void* context) { + ExampleDateTimeInput* app = context; + DialogEx* dialog_ex = app->dialog_ex; + + dialog_ex_set_header(dialog_ex, "The date and time are", 64, 0, AlignCenter, AlignTop); + + char buffer[26] = {}; + snprintf( + buffer, + sizeof(buffer), + "%04d-%02d-%02d\n%02d:%02d:%02d", + app->date_time.year, + app->date_time.month, + app->date_time.day, + app->date_time.hour, + app->date_time.minute, + app->date_time.second); + dialog_ex_set_text(dialog_ex, buffer, 64, 29, AlignCenter, AlignCenter); + + dialog_ex_set_left_button_text(dialog_ex, "Date"); + dialog_ex_set_right_button_text(dialog_ex, "Time"); + dialog_ex_set_center_button_text(dialog_ex, "Both"); + + dialog_ex_set_result_callback( + dialog_ex, example_date_time_input_scene_confirm_dialog_callback); + dialog_ex_set_context(dialog_ex, app); +} + +void example_date_time_input_scene_show_date_time_on_enter(void* context) { + furi_assert(context); + ExampleDateTimeInput* app = context; + + example_date_time_input_scene_update_view(app); + + view_dispatcher_switch_to_view(app->view_dispatcher, ExampleDateTimeInputViewIdShowDateTime); +} + +bool example_date_time_input_scene_show_date_time_on_event(void* context, SceneManagerEvent event) { + ExampleDateTimeInput* app = context; + bool consumed = false; + + if(event.type == SceneManagerEventTypeCustom) { + switch(event.event) { + case DialogExResultCenter: + app->edit_date = true; + app->edit_time = true; + scene_manager_next_scene(app->scene_manager, ExampleDateTimeInputSceneInputDateTime); + consumed = true; + break; + case DialogExResultLeft: + app->edit_date = true; + app->edit_time = false; + scene_manager_next_scene(app->scene_manager, ExampleDateTimeInputSceneInputDateTime); + consumed = true; + break; + case DialogExResultRight: + app->edit_date = false; + app->edit_time = true; + scene_manager_next_scene(app->scene_manager, ExampleDateTimeInputSceneInputDateTime); + consumed = true; + break; + default: + break; + } + } + + return consumed; +} + +void example_date_time_input_scene_show_date_time_on_exit(void* context) { + UNUSED(context); +} diff --git a/applications/services/gui/modules/date_time_input.c b/applications/services/gui/modules/date_time_input.c index abcb16887..eb703cda2 100644 --- a/applications/services/gui/modules/date_time_input.c +++ b/applications/services/gui/modules/date_time_input.c @@ -21,7 +21,6 @@ struct DateTimeInput { }; typedef struct { - const char* header; DateTime* datetime; uint8_t row; @@ -335,7 +334,6 @@ DateTimeInput* date_time_input_alloc(void) { date_time_input->view, DateTimeInputModel * model, { - model->header = ""; model->changed_callback = NULL; model->callback_context = NULL; date_time_input_reset_model_input_data(model); @@ -377,13 +375,6 @@ void date_time_input_set_result_callback( true); } -void date_time_input_set_header_text(DateTimeInput* date_time_input, const char* text) { - furi_check(date_time_input); - - with_view_model( - date_time_input->view, DateTimeInputModel * model, { model->header = text; }, true); -} - void date_time_input_set_editable_fields( DateTimeInput* date_time_input, bool year, diff --git a/applications/services/gui/modules/date_time_input.h b/applications/services/gui/modules/date_time_input.h index 2969994fd..1c8cdd779 100644 --- a/applications/services/gui/modules/date_time_input.h +++ b/applications/services/gui/modules/date_time_input.h @@ -58,13 +58,6 @@ void date_time_input_set_result_callback( void* callback_context, DateTime* datetime); -/** Set date/time input header text - * - * @param date_time_input date/time input instance - * @param text text to be shown - */ -void date_time_input_set_header_text(DateTimeInput* date_time_input, const char* text); - /** Set date/time fields which can be edited * * @param date_time_input date/time input instance diff --git a/targets/f7/api_symbols.csv b/targets/f7/api_symbols.csv index fcf8388f1..77f6f7e6f 100644 --- a/targets/f7/api_symbols.csv +++ b/targets/f7/api_symbols.csv @@ -1,5 +1,5 @@ entry,status,name,type,params -Version,+,86.0,, +Version,+,87.0,, Header,+,applications/drivers/subghz/cc1101_ext/cc1101_ext_interconnect.h,, Header,+,applications/services/bt/bt_service/bt.h,, Header,+,applications/services/bt/bt_service/bt_keys_storage.h,, @@ -930,7 +930,6 @@ Function,+,date_time_input_alloc,DateTimeInput*, Function,+,date_time_input_free,void,DateTimeInput* Function,+,date_time_input_get_view,View*,DateTimeInput* Function,+,date_time_input_set_editable_fields,void,"DateTimeInput*, _Bool, _Bool, _Bool, _Bool, _Bool, _Bool" -Function,+,date_time_input_set_header_text,void,"DateTimeInput*, const char*" Function,+,date_time_input_set_result_callback,void,"DateTimeInput*, DateTimeChangedCallback, DateTimeDoneCallback, void*, DateTime*" Function,+,datetime_datetime_to_timestamp,uint32_t,DateTime* Function,+,datetime_get_days_per_month,uint8_t,"_Bool, uint8_t"