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 = TIZEN_ERROR_EFL_UTIL | 0x01  /**< Window type not supported */
 171 } efl_util_error_e;
 172
 173 // TODO: are we going to have more states than on/off shouldn't we move it to a bool in the API's
 174 typedef enum _Efl_Util_Opaque_State
 175 {
 176         EFL_UTIL_OPAQUE_STATE_OFF = 0, /**< Transparent state */
 177         EFL_UTIL_OPAQUE_STATE_ON  = 1, /**< Opaque state */
 178 } Efl_Util_Opaque_State;
 179
 180 /**
 181  * @brief Enumeration of notification window's priority level.
 182  * @since_tizen 2.3
 183  */
 184 typedef enum
 185 {
 186         EFL_UTIL_NOTIFICATION_LEVEL_1, /**< Default notification level */
 187         EFL_UTIL_NOTIFICATION_LEVEL_2, /**< Higher notification level than default */
 188         EFL_UTIL_NOTIFICATION_LEVEL_3, /**< The highest notification level */
 189 } efl_util_notification_level_e;
 190
 191 typedef enum _Efl_Util_Effect_Type
 192 {
 193         EFL_UTIL_EFFECT_TYPE_MAP, /**< Effect for Window's Map Notify Event */
 194         EFL_UTIL_EFFECT_TYPE_UNMAP, /**< Effect for Window's UnMap Notify Event */
 195         EFL_UTIL_EFFECT_TYPE_RAISEABOVE, /**< Effect for Window's Configure Notify ( RaiseAbove case ) Event */
 196         EFL_UTIL_EFFECT_TYPE_ROTATION, /**< Effect for Window's Rotation Property Change Notify Event ( X Property: ECORE_X_ATOM_E_ILLUME_ROTATE_WINDOW_ANGLE ) */
 197         EFL_UTIL_EFFECT_TYPE_FOCUSIN, /**< Effect for Window's FocusIn Event ( E17's Event: E_EVENT_BORDER_FOCUS_IN ) */
 198         EFL_UTIL_EFFECT_TYPE_FOCUSOUT /**< Effect for Window's FocusOut Event ( E17's Event : E_EVENT_BORDER_FOCUS_OUT ) */
 199 } Efl_Util_Effect_Type;
 200
 201 typedef enum _Efl_Util_Effect_Style
 202 {
 203         EFL_UTIL_EFFECT_STYLE_DEFAULT, /**< Default Effect Style for Effect Type */
 204         EFL_UTIL_EFFECT_STYLE_NONE, /**< None of Effect Style for Effect Type */
 205         EFL_UTIL_EFFECT_STYLE_CUSTOM0, /**< Custom0 Effect Style for Effect Type */
 206         EFL_UTIL_EFFECT_STYLE_CUSTOM1, /**< Custom1 Effect Style for Effect Type */
 207         EFL_UTIL_EFFECT_STYLE_CUSTOM2, /**< Custom2 Effect Style for Effect Type */
 208         EFL_UTIL_EFFECT_STYLE_CUSTOM3, /**< Custom3 Effect Style for Effect Type */
 209         EFL_UTIL_EFFECT_STYLE_CUSTOM4, /**< Custom4 Effect Style for Effect Type */
 210         EFL_UTIL_EFFECT_STYLE_CUSTOM5, /**< Custom5 Effect Style for Effect Type */
 211         EFL_UTIL_EFFECT_STYLE_CUSTOM6, /**< Custom6 Effect Style for Effect Type */
 212         EFL_UTIL_EFFECT_STYLE_CUSTOM7, /**< Custom7 Effect Style for Effect Type */
 213         EFL_UTIL_EFFECT_STYLE_CUSTOM8, /**< Custom8 Effect Style for Effect Type */
 214         EFL_UTIL_EFFECT_STYLE_CUSTOM9 /**< Custom9 Effect Style for Effect Type */
 215 } Efl_Util_Effect_Style;
 216
 217 /**
 218  * @brief Sets the priority level for the specified notification window, asynchronously.
 219  * @since_tizen 2.3
 220  * @privlevel public
 221  * @privilege %http://tizen.org/privilege/window.priority.set
 222  * @remarks This API can be used for a notification type window only.
 223  * @param[in] window The EFL window
 224  * @param[in] level The notification window level
 225  * @return @c 0 on success,
 226  *         otherwise a negative error value
 227  * @retval #EFL_UTIL_ERROR_NONE Successful
 228  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 229  * @retval #EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE Window type not supported
 230  */
 231 int efl_util_set_notification_window_level (Evas_Object *window, efl_util_notification_level_e level);
 232
 233
 234 /**
 235  * @brief Gets the priority level for the specified notification window, asynchronously.
 236  * @since_tizen 2.3
 237  *
 238  * @remarks This API can be used for a notification type window only.
 239  * @param[in] window The EFL window
 240  * @param[out] level The notification window level
 241  * @return @c 0 on success,
 242  *         otherwise a negative error value
 243  * @retval #EFL_UTIL_ERROR_NONE Successful
 244  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 245  * @retval #EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE Window type not supported
 246  */
 247 int efl_util_get_notification_window_level (Evas_Object *window, efl_util_notification_level_e* level);
 248
 249
 250 /**
 251  * @brief Called when an error occurs for setting notification window level
 252  * @since_tizen 2.3
 253  * @param[in]   window  The EFL window
 254  * @param[in]   error_code      The error code (#EFL_UTIL_ERROR_PERMISSION_DENIED)
 255  * @param[in]   user_data       The user data passed from the callback registration function
 256  * @see efl_util_set_notification_window_level_error_cb()
 257  * @see efl_util_unset_notification_window_level_error_cb()
 258  */
 259 typedef void (*efl_util_notification_window_level_error_cb)(Evas_Object *window, int error_code, void *user_data);
 260
 261
 262 /**
 263  * @brief Registers a callback function to be invoked when an error which set the notification level occurs.
 264  * @since_tizen 2.3
 265  * @param[in] window    The EFL window
 266  * @param[in] callback  The callback function to register
 267  * @param[in] user_data The user data to be passed to the callback function
 268  * @return @c 0 on success,
 269  *                 otherwise a negative error value
 270  * @retval #EFL_UTIL_ERROR_NONE Successful
 271  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 272  * @retval #EFL_UTIL_ERROR_OUT_OF_MEMORY Out of memory
 273  * @post  efl_util_notification_window_level_error_cb() will be invoked.
 274  * @see efl_util_unset_notification_window_level_error_cb()
 275  * @see efl_util_notification_window_level_error_cb()
 276  */
 277 int efl_util_set_notification_window_level_error_cb(Evas_Object *window, efl_util_notification_window_level_error_cb callback, void *user_data);
 278
 279
 280 /**
 281  * @brief Unregisters the callback function.
 282  * @since_tizen 2.3
 283  * @param[in] window The EFL window
 284  * @return @c 0 on success,
 285  *                 otherwise a negative error value
 286  * @retval #EFL_UTIL_ERROR_NONE Successful
 287  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 288  * @see efl_util_set_notification_window_level_error_cb()
 289  */
 290 int efl_util_unset_notification_window_level_error_cb(Evas_Object *window);
 291
 292
 293 /**
 294  * @brief Grabs a key specfied by key_name for obj in grab_mode.
 295  *
 296  * @param obj The Evas_Object representing the window to set the key grab to.
 297  * @param key The key of interest.
 298  * @param grab_mode EXCLUSIVE_GRAB, TOP_POSITION_GRAB, SHARED_GRAB, EXCLUSIVE_GRAB
 299  *
 300  * @return 0 on Success, fail othrewise.
 301  * @see efl_util_ungrab_key()
 302  */
 303 int efl_util_grab_key (Evas_Object *obj, const char* key, int grab_mode);
 304
 305 /**
 306  * @brief Ungrabs a key specfied by key_name for win
 307  *
 308  * @param obj The Evas_Object representing the window to ungrab the key.
 309  * @param key The key of interest.
 310  *
 311  * @return 0 on Success, fail otherwise.
 312  * @see efl_util_grab_key()
 313  */
 314 int efl_util_ungrab_key (Evas_Object *obj, const char* key);
 315
 316 /**
 317  * @brief Sets the priority level for the specified notification window
 318  *
 319  * @param obj The Evas_Object representing the window to set the notification level.
 320  * @param level The notification level.
 321  *
 322  * @see Efl_Util_Notification_Level
 323  */
 324 void efl_util_set_system_notification_level (Evas_Object *obj, Efl_Util_Notification_Level level);
 325
 326 /**
 327  * @brief Gets the priority level for the specified notification window.
 328  *
 329  * @param obj The Evas_Object representing the window to get the system notification level
 330  * set to.
 331  *
 332  * @return current notication level (EFL_UTIL_NOTIFICATION_LEVEL_LOW,
 333  *         EFL_UTIL_NOTIFICATION_LEVEL_NORMAL, EFL_UTIL_NOTIFICATION_LEVEL_HIGH)
 334  */
 335 Efl_Util_Notification_Level efl_util_get_system_notification_level (Evas_Object *obj);
 336
 337 /**
 338  * @brief Set the functional type of window by sending _NET_WM_WINDOW_TYPE property to window.
 339  *
 340  * @param obj The Evas_Object representing the window to set the net_wm to.
 341  * @param type The type to be set.
 342  */
 343 void efl_util_netwm_window_type_set(Evas_Object *obj, Efl_Util_Window_Type type);
 344
 345 /**
 346  * @brief Sets a window's effect style with effect type.
 347  *
 348  * @param win The window to set the style to.
 349  * @param type type Specifies the window's effect type ( ex. EFL_UTIL_EFFECT_TYPE_MAP, EFL_UTIL_EFFECT_TYPE_UNMAP, etc )
 350  * @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 )
 351  */
 352 void efl_util_set_window_effect_style(Evas_Object *win, Efl_Util_Effect_Type type, Efl_Util_Effect_Style style);
 353
 354 /**
 355  * @brief Sets the window's opaque state
 356  *
 357  * @param win The window to set the opaque state to.
 358  * @param state The state (EFL_UTIL_OPAQUE_STATE_ON, EFL_UTIL_OPAQUE_STATE_OFF).
 359  *
 360  * @return 0 on failure
 361  */
 362 int efl_util_set_window_opaque_state (Evas_Object *win, Efl_Util_Opaque_State state);
 363
 364 /**
 365  * @}
 366  */
 367
 368 #ifdef __cplusplus
 369 }
 370 #endif
 371 #endif                          /* __TIZEN_UI_EFL_UTIL_H__ */