Import of the watch repository from Pebble

src/fw/applib/ui/action_menu_window.h

@@ -0,0 +1,137 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include "applib/ui/window.h"
+#include "applib/ui/window_stack.h"
+#include "services/normal/timeline/item.h"
+
+//! @file action_menu_window.h
+//! @addtogroup UI
+//! @{
+//!   @addtogroup ActionMenu
+//!
+//! \brief Configurable menu that displays a hierarchy of selectable choices to the user
+//!
+//!   @{
+
+
+typedef enum {
+  ActionMenuAlignTop = 0,
+  ActionMenuAlignCenter
+} ActionMenuAlign;
+
+struct ActionMenuItem;
+//! An ActionMenuItem is an entry in the ActionMenu
+//! You can think of it as a node in the action tree.
+//! ActionMenuItems are either actions (i.e. leaf nodes) or levels.
+typedef struct ActionMenuItem ActionMenuItem;
+
+struct ActionMenuLevel;
+typedef struct ActionMenuLevel ActionMenuLevel;
+
+struct ActionMenu;
+typedef struct ActionMenu ActionMenu;
+
+//! Callback executed after the ActionMenu has closed, so memory may be freed.
+//! @param root_level the root level passed to the ActionMenu
+//! @param performed_action the ActionMenuItem for the action that was performed,
+//! NULL if the ActionMenu is closing without an action being selected by the user
+//! @param context the context passed to the ActionMenu
+typedef void (*ActionMenuDidCloseCb)(ActionMenu *menu,
+                                     const ActionMenuItem *performed_action,
+                                     void *context);
+
+//! Callback executed immediately before the ActionMenu closes.
+//! @param root_level the root ActionMenuLevel passed to the ActionMenu
+//! @param performed_action the ActionMenuItem for the action that was performed,
+//! NULL if the ActionMenu is closing without an action being selected by the user
+//! @param context the context passed to the ActionMenu
+typedef void (*ActionMenuWillCloseCb)(ActionMenu *menu,
+                                      const ActionMenuItem *performed_action,
+                                      void *context);
+
+//! Configuration struct for the ActionMenu
+typedef struct {
+  const ActionMenuLevel *root_level; //!< the root level of the ActionMenu
+  void *context; //!< a context pointer which will be accessbile when actions are performed
+  struct {
+    GColor background; //!< the color of the left column of the ActionMenu
+    GColor foreground; //!< the color of the individual "crumbs" that indicate menu depth
+  } colors;
+  ActionMenuDidCloseCb will_close; //!< Called immediately before the ActionMenu closes
+  ActionMenuDidCloseCb did_close; //!< a callback used to cleanup memory after the menu has closed
+  ActionMenuAlign align;
+} ActionMenuConfig;
+
+//! Get the context pointer this ActionMenu was created with
+//! @param action_menu A pointer to an ActionMenu
+//! @return the context pointer initially provided in the \ref ActionMenuConfig.
+//! NULL if none exists.
+void *action_menu_get_context(ActionMenu *action_menu);
+
+//! Get the root level of an ActionMenu
+//! @param action_menu the ActionMenu you want to know about
+//! @return a pointer to the root ActionMenuLevel for the given ActionMenu, NULL if invalid
+ActionMenuLevel *action_menu_get_root_level(ActionMenu *action_menu);
+
+//! @internal
+//! Open a new ActionMenu.
+//! The ActionMenu acts much like a window. It fills the whole screen and handles clicks.
+//! @param window_stack The \ref WindowStack to push the ActionMenu to
+//! @param config the configuration info for this new ActionMenu
+//! @return the new ActionMenu
+ActionMenu *action_menu_open(WindowStack *window_stack, ActionMenuConfig *config);
+
+//! Open a new ActionMenu.
+//! The ActionMenu acts much like a window. It fills the whole screen and handles clicks.
+//! @param config the configuration info for this new ActionMenu
+//! @return the new ActionMenu
+ActionMenu *app_action_menu_open(ActionMenuConfig *config);
+
+//! Freeze the ActionMenu. The ActionMenu will no longer respond to user input.
+//! @note this API should be used when waiting for asynchronous operation.
+//! @param action_menu the ActionMenu
+void action_menu_freeze(ActionMenu *action_menu);
+
+//! Unfreeze the ActionMenu previously frozen with \ref action_menu_freeze
+//! @param action_menu the ActionMenu to unfreeze
+void action_menu_unfreeze(ActionMenu *action_menu);
+
+//! Check if an ActionMenu is frozen.
+bool action_menu_is_frozen(ActionMenu *action_menu);
+
+//! Set the result window for an ActionMenu. The result window will be
+//! shown when the ActionMenu closes
+//! @param action_menu the ActionMenu
+//! @param result_window the window to insert, pass NULL to remove the current result window
+//! @note repeated call will result in only the last call to be applied, i.e. only
+//! one result window is ever set
+void action_menu_set_result_window(ActionMenu *action_menu, Window *result_window);
+
+//! @internal
+void action_menu_set_align(ActionMenuConfig *config, ActionMenuAlign align);
+
+//! Close the ActionMenu, whether it is frozen or not.
+//! @note this API can be used on a frozen ActionMenu once the data required to
+//! build the result window has been received and the result window has been set
+//! @param action_menu the ActionMenu to close
+//! @param animated whether or not show a close animation
+void action_menu_close(ActionMenu *action_menu, bool animated);
+
+//!   @} // end addtogroup ActionMenu
+//! @} // end addtogroup UI