include/efl_util.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_UI_EFL_UTIL_H__
  19 #define __TIZEN_UI_EFL_UTIL_H__
  20
  21 #include <tizen.h>
  22 #include <Evas.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @file efl_util.h
  30  */
  31
  32 /**
  33  * @addtogroup CAPI_EFL_UTIL_MODULE
  34  * @{
  35  */
  36
  37 // Duplicated from utilX.h, should be moved to somewhere common in the future
  38
  39 #ifndef KEY_VOLUMEUP
  40 #define KEY_VOLUMEUP            "XF86AudioRaiseVolume"  /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Volume Up' key */
  41 #endif
  42
  43 #ifndef KEY_VOLUMEDOWN
  44 #define KEY_VOLUMEDOWN          "XF86AudioLowerVolume"  /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Volume Down' key */
  45 #endif
  46
  47 #ifndef KEY_CAMERA
  48 #define KEY_CAMERA              "XF86WebCam"    /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Half-Press of Camera' key */
  49 #endif
  50
  51 #ifndef KEY_CONFIG
  52 #define KEY_CONFIG              "XF86Pictures"  /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Full-Press of Camera' key */
  53 #endif
  54
  55 #ifndef KEY_POWER
  56 #define KEY_POWER               "XF86PowerOff"  /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Power' key */
  57 #endif
  58
  59 #ifndef KEY_PAUSE
  60 #define KEY_PAUSE               "XF86Standby"   /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Pause' key */
  61 #endif
  62
  63 #ifndef KEY_CANCEL
  64 #define KEY_CANCEL              "Cancel"        /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Cancel' key */
  65 #endif
  66
  67 // Earjack/BT Headset/Multimedia keys
  68 #ifndef KEY_PLAYCD
  69 #define KEY_PLAYCD              "XF86AudioPlay" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Play Audio' key */
  70 #endif
  71
  72 #ifndef KEY_STOPCD
  73 #define KEY_STOPCD              "XF86AudioStop" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Stop Audio' key */
  74 #endif
  75
  76 #ifndef KEY_PAUSECD
  77 #define KEY_PAUSECD             "XF86AudioPause"        /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Pause Audio' key */
  78 #endif
  79
  80 #ifndef KEY_NEXTSONG
  81 #define KEY_NEXTSONG            "XF86AudioNext" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Next Song' key */
  82 #endif
  83
  84 #ifndef KEY_PREVIOUSSONG
  85 #define KEY_PREVIOUSSONG        "XF86AudioPrev" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Previous Song' key */
  86 #endif
  87
  88 #ifndef KEY_REWIND
  89 #define KEY_REWIND              "XF86AudioRewind"       /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Rewind Song' key */
  90 #endif
  91
  92 #ifndef KEY_FASTFORWARD
  93 #define KEY_FASTFORWARD         "XF86AudioForward"      /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Forward Song' key */
  94 #endif
  95
  96 #ifndef KEY_MEDIA
  97 #define KEY_MEDIA               "XF86AudioMedia"        /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Media' key */
  98 #endif
  99
 100 // 3-Touch key
 101 #ifndef KEY_SEND
 102 #define KEY_SEND                "XF86Send"      /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Send' key */
 103 #endif
 104
 105 #ifndef KEY_SELECT
 106 #define KEY_SELECT              "XF86Phone"     /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Home' key */
 107 #endif
 108
 109 #ifndef KEY_END
 110 #define KEY_END                 "XF86Stop"      /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'End' key */
 111 #endif
 112
 113 // Renamed 3-Touch key
 114 #ifndef KEY_MENU
 115 #define KEY_MENU                "XF86Send"      /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Send' key */
 116 #endif
 117
 118 #ifndef KEY_HOME
 119 #define KEY_HOME                "XF86Phone"     /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Home' key */
 120 #endif
 121
 122 #ifndef KEY_BACK
 123 #define KEY_BACK                "XF86Stop"      /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'End' key */
 124 #endif
 125
 126 #ifndef OR_EXCLUSIVE_GRAB
 127 #define OR_EXCLUSIVE_GRAB       0xf00000        /**< this means that the client window will always get the grabbed-key exclusively regardless of the position on the window stack but the grab is overridable by the other client window */
 128 #endif
 129
 130 #ifndef EXCLUSIVE_GRAB
 131 #define EXCLUSIVE_GRAB          0x0f0000        /**< this means that the client window will always get the grabbed-key exclusively regardless of the position on the window stack */
 132 #endif
 133
 134 #ifndef TOP_POSITION_GRAB
 135 #define TOP_POSITION_GRAB       0x00f000        /**< this means that the client window will get the grabbed-key only when on the top of the grabbing-window stack */
 136 #endif
 137
 138 #ifndef SHARED_GRAB
 139 #define SHARED_GRAB             0x000f00        /**< this means that the client window will get the grabbed-key together with the other client window(s) */
 140 #endif
 141
 142 #ifndef GRAB_MODE_MASK
 143 #define GRAB_MODE_MASK  0xffff00        /**< this mask will be used for getting the key-grab mode of a client window */
 144 #endif
 145
 146 typedef enum _Efl_Util_Window_Type
 147 {
 148         EFL_UTIL_WINDOW_TYPE_NORMAL = 8, /**< ecore_x compatible, ECORE_X_WINDOW_TYPE_NORMAL */
 149         EFL_UTIL_WINDOW_TYPE_NOTIFICATION = 12, /**< ecore_x compatible, ECORE_X_WINDOW_TYPE_NOTIFICATION */
 150 } Efl_Util_Window_Type;
 151
 152 typedef enum _Efl_Util_Notification_Level
 153 {
 154         EFL_UTIL_NOTIFICATION_LEVEL_LOW, /**< low level notification */
 155         EFL_UTIL_NOTIFICATION_LEVEL_NORMAL, /**< normal level notification*/
 156         EFL_UTIL_NOTIFICATION_LEVEL_HIGH, /**< high level notification */
 157         EFL_UTIL_NOTIFICATION_LEVEL_UNKNOWN
 158 } Efl_Util_Notification_Level;
 159
 160 /**
 161  * @brief Enumeration for EFL UTIL ERROR.
 162  * @since_tizen 2.3
 163  */
 164 typedef enum
 165 {
 166         EFL_UTIL_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
 167         EFL_UTIL_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
 168         EFL_UTIL_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
 169         EFL_UTIL_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permisson denied */
 170         EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE = -0x02800000 | 0x01  /**< Window type not supported */
 171         //EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE = TIZEN_ERROR_EFL_UTIL | 0x01  /**< Window type not supported */
 172 } efl_util_error_e;
 173
 174 // TODO: are we going to have more states than on/off shouldn't we move it to a bool in the API's
 175 typedef enum _Efl_Util_Opaque_State
 176 {
 177         EFL_UTIL_OPAQUE_STATE_OFF = 0, /**< Transparent state */
 178         EFL_UTIL_OPAQUE_STATE_ON  = 1, /**< Opaque state */
 179 } Efl_Util_Opaque_State;
 180
 181 /**
 182  * @brief Enumeration of notification window's priority level.
 183  * @since_tizen 2.3
 184  */
 185 typedef enum
 186 {
 187         EFL_UTIL_NOTIFICATION_LEVEL_1, /**< Default notification level */
 188         EFL_UTIL_NOTIFICATION_LEVEL_2, /**< Higher notification level than default */
 189         EFL_UTIL_NOTIFICATION_LEVEL_3, /**< The highest notification level */
 190 } efl_util_notification_level_e;
 191
 192 typedef enum _Efl_Util_Effect_Type
 193 {
 194         EFL_UTIL_EFFECT_TYPE_MAP, /**< Effect for Window's Map Notify Event */
 195         EFL_UTIL_EFFECT_TYPE_UNMAP, /**< Effect for Window's UnMap Notify Event */
 196         EFL_UTIL_EFFECT_TYPE_RAISEABOVE, /**< Effect for Window's Configure Notify ( RaiseAbove case ) Event */
 197         EFL_UTIL_EFFECT_TYPE_ROTATION, /**< Effect for Window's Rotation Property Change Notify Event ( X Property: ECORE_X_ATOM_E_ILLUME_ROTATE_WINDOW_ANGLE ) */
 198         EFL_UTIL_EFFECT_TYPE_FOCUSIN, /**< Effect for Window's FocusIn Event ( E17's Event: E_EVENT_BORDER_FOCUS_IN ) */
 199         EFL_UTIL_EFFECT_TYPE_FOCUSOUT /**< Effect for Window's FocusOut Event ( E17's Event : E_EVENT_BORDER_FOCUS_OUT ) */
 200 } Efl_Util_Effect_Type;
 201
 202 typedef enum _Efl_Util_Effect_Style
 203 {
 204         EFL_UTIL_EFFECT_STYLE_DEFAULT, /**< Default Effect Style for Effect Type */
 205         EFL_UTIL_EFFECT_STYLE_NONE, /**< None of Effect Style for Effect Type */
 206         EFL_UTIL_EFFECT_STYLE_CUSTOM0, /**< Custom0 Effect Style for Effect Type */
 207         EFL_UTIL_EFFECT_STYLE_CUSTOM1, /**< Custom1 Effect Style for Effect Type */
 208         EFL_UTIL_EFFECT_STYLE_CUSTOM2, /**< Custom2 Effect Style for Effect Type */
 209         EFL_UTIL_EFFECT_STYLE_CUSTOM3, /**< Custom3 Effect Style for Effect Type */
 210         EFL_UTIL_EFFECT_STYLE_CUSTOM4, /**< Custom4 Effect Style for Effect Type */
 211         EFL_UTIL_EFFECT_STYLE_CUSTOM5, /**< Custom5 Effect Style for Effect Type */
 212         EFL_UTIL_EFFECT_STYLE_CUSTOM6, /**< Custom6 Effect Style for Effect Type */
 213         EFL_UTIL_EFFECT_STYLE_CUSTOM7, /**< Custom7 Effect Style for Effect Type */
 214         EFL_UTIL_EFFECT_STYLE_CUSTOM8, /**< Custom8 Effect Style for Effect Type */
 215         EFL_UTIL_EFFECT_STYLE_CUSTOM9 /**< Custom9 Effect Style for Effect Type */
 216 } Efl_Util_Effect_Style;
 217
 218 /**
 219  * @brief Sets the priority level for the specified notification window, asynchronously.
 220  * @since_tizen 2.3
 221  * @privlevel public
 222  * @privilege %http://tizen.org/privilege/window.priority.set
 223  * @remarks This API can be used for a notification type window only.
 224  * @param[in] window The EFL window
 225  * @param[in] level The notification window level
 226  * @return @c 0 on success,
 227  *         otherwise a negative error value
 228  * @retval #EFL_UTIL_ERROR_NONE Successful
 229  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 230  * @retval #EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE Window type not supported
 231  */
 232 int efl_util_set_notification_window_level (Evas_Object *window, efl_util_notification_level_e level);
 233
 234
 235 /**
 236  * @brief Gets the priority level for the specified notification window, asynchronously.
 237  * @since_tizen 2.3
 238  *
 239  * @remarks This API can be used for a notification type window only.
 240  * @param[in] window The EFL window
 241  * @param[out] level The notification window level
 242  * @return @c 0 on success,
 243  *         otherwise a negative error value
 244  * @retval #EFL_UTIL_ERROR_NONE Successful
 245  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 246  * @retval #EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE Window type not supported
 247  */
 248 int efl_util_get_notification_window_level (Evas_Object *window, efl_util_notification_level_e* level);
 249
 250
 251 /**
 252  * @brief Called when an error occurs for setting notification window level
 253  * @since_tizen 2.3
 254  * @param[in]   window  The EFL window
 255  * @param[in]   error_code      The error code (#EFL_UTIL_ERROR_PERMISSION_DENIED)
 256  * @param[in]   user_data       The user data passed from the callback registration function
 257  * @see efl_util_set_notification_window_level_error_cb()
 258  * @see efl_util_unset_notification_window_level_error_cb()
 259  */
 260 typedef void (*efl_util_notification_window_level_error_cb)(Evas_Object *window, int error_code, void *user_data);
 261
 262
 263 /**
 264  * @brief Registers a callback function to be invoked when an error which set the notification level occurs.
 265  * @since_tizen 2.3
 266  * @param[in] window    The EFL window
 267  * @param[in] callback  The callback function to register
 268  * @param[in] user_data The user data to be passed to the callback function
 269  * @return @c 0 on success,
 270  *                 otherwise a negative error value
 271  * @retval #EFL_UTIL_ERROR_NONE Successful
 272  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 273  * @retval #EFL_UTIL_ERROR_OUT_OF_MEMORY Out of memory
 274  * @post  efl_util_notification_window_level_error_cb() will be invoked.
 275  * @see efl_util_unset_notification_window_level_error_cb()
 276  * @see efl_util_notification_window_level_error_cb()
 277  */
 278 int efl_util_set_notification_window_level_error_cb(Evas_Object *window, efl_util_notification_window_level_error_cb callback, void *user_data);
 279
 280
 281 /**
 282  * @brief Unregisters the callback function.
 283  * @since_tizen 2.3
 284  * @param[in] window The EFL window
 285  * @return @c 0 on success,
 286  *                 otherwise a negative error value
 287  * @retval #EFL_UTIL_ERROR_NONE Successful
 288  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 289  * @see efl_util_set_notification_window_level_error_cb()
 290  */
 291 int efl_util_unset_notification_window_level_error_cb(Evas_Object *window);
 292
 293
 294 /**
 295  * @brief Grabs a key specfied by key_name for obj in grab_mode.
 296  *
 297  * @param obj The Evas_Object representing the window to set the key grab to.
 298  * @param key The key of interest.
 299  * @param grab_mode EXCLUSIVE_GRAB, TOP_POSITION_GRAB, SHARED_GRAB, EXCLUSIVE_GRAB
 300  *
 301  * @return 0 on Success, fail othrewise.
 302  * @see efl_util_ungrab_key()
 303  */
 304 int efl_util_grab_key (Evas_Object *obj, const char* key, int grab_mode);
 305
 306 /**
 307  * @brief Ungrabs a key specfied by key_name for win
 308  *
 309  * @param obj The Evas_Object representing the window to ungrab the key.
 310  * @param key The key of interest.
 311  *
 312  * @return 0 on Success, fail otherwise.
 313  * @see efl_util_grab_key()
 314  */
 315 int efl_util_ungrab_key (Evas_Object *obj, const char* key);
 316
 317 /**
 318  * @brief Sets the priority level for the specified notification window
 319  *
 320  * @param obj The Evas_Object representing the window to set the notification level.
 321  * @param level The notification level.
 322  *
 323  * @see Efl_Util_Notification_Level
 324  */
 325 void efl_util_set_system_notification_level (Evas_Object *obj, Efl_Util_Notification_Level level);
 326
 327 /**
 328  * @brief Gets the priority level for the specified notification window.
 329  *
 330  * @param obj The Evas_Object representing the window to get the system notification level
 331  * set to.
 332  *
 333  * @return current notication level (EFL_UTIL_NOTIFICATION_LEVEL_LOW,
 334  *         EFL_UTIL_NOTIFICATION_LEVEL_NORMAL, EFL_UTIL_NOTIFICATION_LEVEL_HIGH)
 335  */
 336 Efl_Util_Notification_Level efl_util_get_system_notification_level (Evas_Object *obj);
 337
 338 /**
 339  * @brief Set the functional type of window by sending _NET_WM_WINDOW_TYPE property to window.
 340  *
 341  * @param obj The Evas_Object representing the window to set the net_wm to.
 342  * @param type The type to be set.
 343  */
 344 void efl_util_netwm_window_type_set(Evas_Object *obj, Efl_Util_Window_Type type);
 345
 346 /**
 347  * @brief Sets a window's effect style with effect type.
 348  *
 349  * @param win The window to set the style to.
 350  * @param type type Specifies the window's effect type ( ex. EFL_UTIL_EFFECT_TYPE_MAP, EFL_UTIL_EFFECT_TYPE_UNMAP, etc )
 351  * @param style Specifies  the window's effect style ( ex. EFL_UTIL_EFFECT_STYLE_DEFAULT, EFL_UTIL_EFFECT_STYLE_NONE, EFL_UTIL_EFFECT_STYLE_CUSTOM0, etc )
 352  */
 353 void efl_util_set_window_effect_style(Evas_Object *win, Efl_Util_Effect_Type type, Efl_Util_Effect_Style style);
 354
 355 /**
 356  * @brief Sets the window's opaque state
 357  *
 358  * @param win The window to set the opaque state to.
 359  * @param state The state (EFL_UTIL_OPAQUE_STATE_ON, EFL_UTIL_OPAQUE_STATE_OFF).
 360  *
 361  * @return 0 on failure
 362  */
 363 int efl_util_set_window_opaque_state (Evas_Object *win, Efl_Util_Opaque_State state);
 364
 365 /**
 366  * @}
 367  */
 368
 369 #ifdef __cplusplus
 370 }
 371 #endif
 372 #endif                          /* __TIZEN_UI_EFL_UTIL_H__ */