1 #ifndef DALI_KEY_GRAB_H
2 #define DALI_KEY_GRAB_H
5 * Copyright (c) 2020 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
22 #include <dali/public-api/common/dali-vector.h>
23 #include <dali/public-api/dali-adaptor-common.h>
26 #include <dali/public-api/adaptor-framework/key.h>
31 * @addtogroup dali_adaptor_framework
38 * @brief Key grab functions.
44 * @brief Grabs the key specified by @a key for @a window only when @a window is the topmost window.
46 * This function can be used for following example scenarios:
47 * - Mobile - Using volume up/down as zoom up/down in camera apps.
50 * @param[in] window The window to set
51 * @param[in] daliKey The key code to grab (defined in key.h)
52 * @return true if the grab succeeds
54 DALI_ADAPTOR_API bool GrabKeyTopmost(Window window, Dali::KEY daliKey);
57 * @brief Ungrabs the key specified by @a key for @a window.
60 * @param[in] window The window to set
61 * @param[in] daliKey The key code to ungrab (defined in key.h)
62 * @return true if the ungrab succeeds
63 * @note If this function is called between key down and up events of a grabbed key,
64 * an application doesn't receive the key up event.
66 DALI_ADAPTOR_API bool UngrabKeyTopmost(Window window, Dali::KEY daliKey);
69 * @brief Enumeration for key grab mode for platform-level APIs.
74 TOPMOST = 0, ///< Grab a key only when on the top of the grabbing-window stack mode. @SINCE_1_0.0
75 SHARED, ///< Grab a key together with the other client window(s) mode. @SINCE_1_0.0
76 OVERRIDE_EXCLUSIVE, ///< Grab a key exclusively regardless of the grabbing-window's position on the window stack with the possibility of overriding the grab by the other client window mode. @SINCE_1_0.0
77 EXCLUSIVE ///< Grab a key exclusively regardless of the grabbing-window's position on the window stack mode. @SINCE_1_0.0
82 * @brief Grabs the key specified by @a key for @a window in @a grabMode.
84 * @details This function can be used for following example scenarios:
85 * - TV - A user might want to change the volume or channel of the background TV contents while focusing on the foreground app.
86 * - Mobile - When a user presses Home key, the homescreen appears regardless of current foreground app.
87 * - Mobile - Using volume up/down as zoom up/down in camera apps.
92 * @param[in] window The window to set
93 * @param[in] daliKey The key code to grab (defined in key.h)
94 * @param[in] grabMode The grab mode for the key
95 * @return true if the grab succeeds
97 DALI_ADAPTOR_API bool GrabKey(Window window, Dali::KEY daliKey, KeyGrabMode grabMode);
101 * @brief Ungrabs the key specified by @a key for @a window.
104 * @PRIVLEVEL_PLATFORM
106 * @param[in] window The window to set
107 * @param[in] daliKey The key code to ungrab (defined in key.h)
108 * @return true if the ungrab succeeds
109 * @note If this function is called between key down and up events of a grabbed key,
110 * an application doesn't receive the key up event.
112 DALI_ADAPTOR_API bool UngrabKey(Window window, Dali::KEY daliKey);
116 * @brief Grabs the list of keys specified by Dali::Vector of keys for @a window in Dali::Vector of grabModes.
118 * @details This function can be used for following example scenarios:
119 * - TV - A user might want to change the volume or channel of the background TV contents while focusing on the foreground app.
120 * - Mobile - When a user presses Home key, the homescreen appears regardless of current foreground app.
121 * - Mobile - Using volume up/down as zoom up/down in camera apps.
124 * @PRIVLEVEL_PLATFORM
126 * @param[in] window The window to set
127 * @param[in] daliKeyVector The Dali::Vector of key codes to grab (defined in key.h)
128 * @param[in] grabModeVector The Dali::Vector of grab modes for the keys
129 * @param[in] returnVector The Dali::Vector of return boolean values for the results of multiple grab succeeds/fails
130 * @return bool false when error occurs
132 DALI_ADAPTOR_API bool GrabKeyList(Window window, const Dali::Vector<Dali::KEY>& daliKeyVector, const Dali::Vector<KeyGrabMode>& grabModeVector, Dali::Vector<bool>& returnVector);
136 * @brief Ungrabs the list of keys specified by Dali::Vector of keys for @a window.
139 * @PRIVLEVEL_PLATFORM
141 * @param[in] window The window to set
142 * @param[in] daliKeyVector The Dali::Vector of key codes to ungrab (defined in key.h)
143 * @param[in] returnVector The Dali::Vector of return boolean values for the results of multiple ungrab succeeds/fails
144 * @return bool false when error occurs
145 * @note If this function is called between key down and up events of a grabbed key,
146 * an application doesn't receive the key up event.
148 DALI_ADAPTOR_API bool UngrabKeyList(Window window, const Dali::Vector<Dali::KEY>& daliKeyVector, Dali::Vector<bool>& returnVector);
150 } // namespace KeyGrab
157 #endif // DALI_KEY_GRAB_H