dali/public-api/adaptor-framework/key-grab.h

   1 #ifndef DALI_KEY_GRAB_H
   2 #define DALI_KEY_GRAB_H
   3
   4 /*
   5  * Copyright (c) 2019 Samsung Electronics Co., Ltd.
   6  *
   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
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  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.
  18  *
  19  */
  20
  21 // INTERNAL INCLUDES
  22 #include <dali/public-api/dali-adaptor-common.h>
  23 #include <dali/public-api/common/dali-vector.h>
  24
  25 // EXTERNAL INCLUDES
  26 #include <dali/public-api/adaptor-framework/key.h>
  27
  28 namespace Dali
  29 {
  30 /**
  31  * @addtogroup dali_adaptor_framework
  32  * @{
  33  */
  34
  35 class Window;
  36
  37 /**
  38  * @brief Key grab functions.
  39  * @SINCE_1_0.0
  40  */
  41 namespace KeyGrab
  42 {
  43
  44 /**
  45  * @brief Grabs the key specified by @a key for @a window only when @a window is the topmost window.
  46  *
  47  * This function can be used for following example scenarios:
  48  * - Mobile - Using volume up/down as zoom up/down in camera apps.
  49  *
  50  * @SINCE_1_0.0
  51  * @param[in] window The window to set
  52  * @param[in] daliKey The key code to grab (defined in key.h)
  53  * @return true if the grab succeeds
  54  */
  55 DALI_ADAPTOR_API bool GrabKeyTopmost( Window window, Dali::KEY daliKey );
  56
  57 /**
  58  * @brief Ungrabs the key specified by @a key for @a window.
  59  *
  60  * @SINCE_1_0.0
  61  * @param[in] window The window to set
  62  * @param[in] daliKey The key code to ungrab (defined in key.h)
  63  * @return true if the ungrab succeeds
  64  * @note If this function is called between key down and up events of a grabbed key,
  65  * an application doesn't receive the key up event.
  66  */
  67 DALI_ADAPTOR_API bool UngrabKeyTopmost( Window window, Dali::KEY daliKey );
  68
  69 /**
  70  * @brief Enumeration for key grab mode for platform-level APIs.
  71  * @SINCE_1_0.0
  72  */
  73 enum KeyGrabMode
  74 {
  75   TOPMOST = 0,             ///< Grab a key only when on the top of the grabbing-window stack mode. @SINCE_1_0.0
  76   SHARED,                  ///< Grab a key together with the other client window(s) mode. @SINCE_1_0.0
  77   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
  78   EXCLUSIVE                ///< Grab a key exclusively regardless of the grabbing-window's position on the window stack mode. @SINCE_1_0.0
  79 };
  80
  81 /**
  82  * @PLATFORM
  83  * @brief Grabs the key specified by @a key for @a window in @a grabMode.
  84  *
  85  * @details This function can be used for following example scenarios:
  86  * - TV - A user might want to change the volume or channel of the background TV contents while focusing on the foreground app.
  87  * - Mobile - When a user presses Home key, the homescreen appears regardless of current foreground app.
  88  * - Mobile - Using volume up/down as zoom up/down in camera apps.
  89  *
  90  * @SINCE_1_0.0
  91  * @PRIVLEVEL_PLATFORM
  92  * @PRIVILEGE_KEYGRAB
  93  * @param[in] window The window to set
  94  * @param[in] daliKey The key code to grab (defined in key.h)
  95  * @param[in] grabMode The grab mode for the key
  96  * @return true if the grab succeeds
  97  */
  98 DALI_ADAPTOR_API bool GrabKey( Window window, Dali::KEY daliKey, KeyGrabMode grabMode );
  99
 100 /**
 101  * @PLATFORM
 102  * @brief Ungrabs the key specified by @a key for @a window.
 103  *
 104  * @SINCE_1_0.0
 105  * @PRIVLEVEL_PLATFORM
 106  * @PRIVILEGE_KEYGRAB
 107  * @param[in] window The window to set
 108  * @param[in] daliKey The key code to ungrab (defined in key.h)
 109  * @return true if the ungrab succeeds
 110  * @note If this function is called between key down and up events of a grabbed key,
 111  * an application doesn't receive the key up event.
 112  */
 113 DALI_ADAPTOR_API bool UngrabKey( Window window, Dali::KEY daliKey );
 114
 115
 116 /**
 117  * @PLATFORM
 118  * @brief Grabs the list of keys specified by Dali::Vector of keys for @a window in Dali::Vector of grabModes.
 119  *
 120  * @details This function can be used for following example scenarios:
 121  * - TV - A user might want to change the volume or channel of the background TV contents while focusing on the foreground app.
 122  * - Mobile - When a user presses Home key, the homescreen appears regardless of current foreground app.
 123  * - Mobile - Using volume up/down as zoom up/down in camera apps.
 124  *
 125  * @SINCE_1_2.0
 126  * @PRIVLEVEL_PLATFORM
 127  * @PRIVILEGE_KEYGRAB
 128  * @param[in] window The window to set
 129  * @param[in] daliKeyVector The Dali::Vector of key codes to grab (defined in key.h)
 130  * @param[in] grabModeVector The Dali::Vector of grab modes for the keys
 131  * @param[in] returnVector The Dali::Vector of return boolean values for the results of multiple grab succeeds/fails
 132  * @return bool false when error occurs
 133  */
 134 DALI_ADAPTOR_API bool GrabKeyList( Window window, const Dali::Vector<Dali::KEY>& daliKeyVector, const Dali::Vector<KeyGrabMode>& grabModeVector, Dali::Vector<bool>& returnVector);
 135
 136
 137 /**
 138  * @PLATFORM
 139  * @brief Ungrabs the list of keys specified by Dali::Vector of keys for @a window.
 140  *
 141  * @SINCE_1_2.0
 142  * @PRIVLEVEL_PLATFORM
 143  * @PRIVILEGE_KEYGRAB
 144  * @param[in] window The window to set
 145  * @param[in] daliKeyVector The Dali::Vector of key codes to ungrab (defined in key.h)
 146  * @param[in] returnVector The Dali::Vector of return boolean values for the results of multiple ungrab succeeds/fails
 147  * @return bool false when error occurs
 148  * @note If this function is called between key down and up events of a grabbed key,
 149  * an application doesn't receive the key up event.
 150  */
 151 DALI_ADAPTOR_API bool UngrabKeyList( Window window, const Dali::Vector<Dali::KEY>& daliKeyVector, Dali::Vector<bool>& returnVector);
 152
 153
 154 } // namespace KeyGrab
 155
 156 /**
 157  * @}
 158  */
 159 } // namespace Dali
 160
 161 #endif // DALI_KEY_GRAB_H