mirror of
https://github.com/google/pebble.git
synced 2025-05-02 08:11:39 -04:00
96 lines
4.6 KiB
C
96 lines
4.6 KiB
C
/*
|
|
* 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
|