adaptors/tizen/key-grab.h

   1 #ifndef __DALI_KEY_GRAB_H__
   2 #define __DALI_KEY_GRAB_H__
   3
   4 /*
   5  * Copyright (c) 2016 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/common/dali-common.h>
  23 #include "key.h"
  24
  25 namespace Dali
  26 {
  27 /**
  28  * @addtogroup dali_adaptor_framework
  29  * @{
  30  */
  31
  32 class Window;
  33
  34 /**
  35  * @brief Key grab functions.
  36  * @SINCE_1_0.0
  37  */
  38 namespace KeyGrab
  39 {
  40
  41 /**
  42  * @brief Grabs the key specified by @a key for @a window only when @a window is the topmost window.
  43  *
  44  * This function can be used for following example scenarios:
  45  * - Mobile - Using volume up/down as zoom up/down in camera apps.
  46  *
  47  * @SINCE_1_0.0
  48  * @param[in] window The window to set
  49  * @param[in] daliKey The key code to grab (defined in key.h)
  50  * @return true if the grab succeeds
  51  */
  52 DALI_IMPORT_API bool GrabKeyTopmost( Window window, Dali::KEY daliKey );
  53
  54 /**
  55  * @brief Ungrabs the key specified by @a key for @a window.
  56  *
  57  * @SINCE_1_0.0
  58  * @param[in] window The window to set
  59  * @param[in] daliKey The key code to ungrab (defined in key.h)
  60  * @return true if the ungrab succeeds
  61  * @note If this function is called between key down and up events of a grabbed key,
  62  * an application doesn't receive the key up event.
  63  */
  64 DALI_IMPORT_API bool UngrabKeyTopmost( Window window, Dali::KEY daliKey );
  65
  66 /**
  67  * @brief Enumeration for key grab mode for platform-level APIs.
  68  * @SINCE_1_0.0
  69  */
  70 enum KeyGrabMode
  71 {
  72   TOPMOST = 0,             ///< Grab a key only when on the top of the grabbing-window stack mode. @SINCE_1_0.0
  73   SHARED,                  ///< Grab a key together with the other client window(s) mode. @SINCE_1_0.0
  74   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
  75   EXCLUSIVE                ///< Grab a key exclusively regardless of the grabbing-window's position on the window stack mode. @SINCE_1_0.0
  76 };
  77
  78 /**
  79  * @PLATFORM
  80  * @brief Grabs the key specified by @a key for @a window in @a grabMode.
  81  *
  82  * @details This function can be used for following example scenarios:
  83  * - TV - A user might want to change the volume or channel of the background TV contents while focusing on the foregrund app.
  84  * - Mobile - When a user presses Home key, the homescreen appears regardless of current foreground app.
  85  * - Mobile - Using volume up/down as zoom up/down in camera apps.
  86  *
  87  * @SINCE_1_0.0
  88  * @PRIVLEVEL_PLATFORM
  89  * @PRIVILEGE_KEYGRAB
  90  * @param[in] window The window to set
  91  * @param[in] daliKey The key code to grab (defined in key.h)
  92  * @param[in] grabMode The grab mode for the key
  93  * @return true if the grab succeeds
  94  */
  95 DALI_IMPORT_API bool GrabKey( Window window, Dali::KEY daliKey, KeyGrabMode grabMode );
  96
  97 /**
  98  * @PLATFORM
  99  * @brief Ungrabs the key specified by @a key for @a window.
 100  *
 101  * @SINCE_1_0.0
 102  * @PRIVLEVEL_PLATFORM
 103  * @PRIVILEGE_KEYGRAB
 104  * @param[in] window The window to set
 105  * @param[in] daliKey The key code to ungrab (defined in key.h)
 106  * @return true if the ungrab succeeds
 107  * @note If this function is called between key down and up events of a grabbed key,
 108  * an application doesn't receive the key up event.
 109  */
 110 DALI_IMPORT_API bool UngrabKey( Window window, Dali::KEY daliKey );
 111
 112 } // namespace KeyGrab
 113
 114 /**
 115  * @}
 116  */
 117 } // namespace Dali
 118
 119 #endif // __DALI_KEY_GRAB_H__