Import of the watch repository from Pebble

src/fw/applib/app_focus_service.h

@@ -0,0 +1,96 @@
+/*
+ * 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 <stdbool.h>
+
+//! @addtogroup Foundation
+//! @{
+//!   @addtogroup EventService
+//!   @{
+//!     @addtogroup AppFocusService
+//!
+//!
+//! \brief Handling app focus
+//! The AppFocusService allows developers to be notified when their apps become visible on the
+//! screen. Common reasons your app may be running but  not be on screen are: it's still in the
+//! middle of launching and being revealed by a system animation, or it is being covered by a system
+//! window such as a notification. This service is useful for apps that require a high degree of
+//! user interactivity, like a game where you'll want to pause when a notification covers your app
+//! window. It can be also used for apps that want to sync up an intro animation to the end of the
+//! system animation that occurs before your app is visible.
+//!
+//! @{
+
+//! Callback type for focus events
+//! @param in_focus True if the app is gaining focus, false otherwise.
+typedef void (*AppFocusHandler)(bool in_focus);
+
+//! There are two different focus events which take place when transitioning to and from an app
+//! being in focus. Below is an example of when these events will occur:
+//! 1) The app is launched. Once the system animation to the app has completed and the app is
+//! completely in focus, the did_focus handler is called with in_focus set to true.
+//! 2) A notification comes in and the animation to show the notification starts. The will_focus
+//! handler is called with in_focus set to false.
+//! 3) The animation completes and the notification is in focus, with the app being completely
+//! covered. The did_focus hander is called with in_focus set to false.
+//! 4) The notification is dismissed and the animation to return to the app starts. The will_focus
+//! handler is called with in_focus set to true.
+//! 5) The animation completes and the app is in focus. The did_focus handler is called with
+//! in_focus set to true.
+typedef struct {
+  //! Handler which will be called right before an app will lose or gain focus.
+  //! @note This will be called with in_focus set to true when a window which is covering the app is
+  //! about to close and return focus to the app.
+  //! @note This will be called with in_focus set to false when a window which will cover the app is
+  //! about to open, causing the app to lose focus.
+  AppFocusHandler will_focus;
+  //! Handler which will be called when an animation finished which has put the app into focus or
+  //! taken the app out of focus.
+  //! @note This will be called with in_focus set to true when a window which was covering the app
+  //! has closed and the app has gained focus.
+  //! @note This will be called with in_focus set to false when a window has opened which is now
+  //! covering the app, causing the app to lose focus.
+  AppFocusHandler did_focus;
+} AppFocusHandlers;
+
+//! Subscribe to the focus event service. Once subscribed, the handlers get called every time the
+//! app gains or loses focus.
+//! @param handler Handlers which will be called on will-focus and did-focus events.
+//! @see AppFocusHandlers
+void app_focus_service_subscribe_handlers(AppFocusHandlers handlers);
+
+//! Subscribe to the focus event service. Once subscribed, the handler
+//! gets called every time the app focus changes.
+//! @note Calling this function is equivalent to
+//! \code{.c}
+//! app_focus_service_subscribe_handlers((AppFocusHandlers){
+//!   .will_focus = handler,
+//! });
+//! \endcode
+//! @note Out focus events are triggered when a modal window is about to open and cover the app.
+//! @note In focus events are triggered when a modal window which is covering the app is about to
+//! close.
+//! @param handler A callback to be called on will-focus events.
+void app_focus_service_subscribe(AppFocusHandler handler);
+
+//! Unsubscribe from the focus event service. Once unsubscribed, the previously
+//! registered handlers will no longer be called.
+void app_focus_service_unsubscribe(void);
+
+//!     @} // end addtogroup AppFocusService
+//!   @} // end addtogroup EventService
+//! @} // end addtogroup Foundation