utilX.h

   1 /*
   2  * libslp-utilx
   3  *
   4    Copyright (c) 2012 Samsung Electronics Co., Ltd All Rights Reserved
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17  *
  18  */
  19
  20 #ifndef __SAMSUNG_LINUX_UTIL_X11_H__
  21 #define __SAMSUNG_LINUX_UTIL_X11_H__
  22
  23 #ifdef __GNUC__
  24 #define DEPRECATED __attribute__((deprecated))
  25 #else
  26 #define DEPRECATED
  27 #endif
  28
  29 /**
  30  * @defgroup utilX X11 utilities
  31  * @ingroup lib
  32  * @brief Samsung Linux platform X11 utilties
  33  *
  34  * Common X11 utilities
  35  * You can use this API with #include <utilX.h>
  36  */
  37
  38 /**
  39  * @addtogroup utilX
  40  * @{
  41  */
  42
  43 #include <sys/types.h>
  44 #include <X11/X.h>
  45 #include <X11/Xlib.h>
  46
  47 #ifdef __cplusplus
  48 extern "C" {
  49 #endif
  50
  51
  52 #define KEY_VOLUMEUP            "XF86AudioRaiseVolume"  /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Volume Up' key */
  53 #define KEY_VOLUMEDOWN          "XF86AudioLowerVolume"  /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Volume Down' key */
  54
  55 #define KEY_CAMERA              "XF86WebCam"    /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Half-Press of Camera' key */
  56 #define KEY_CONFIG              "XF86Pictures"  /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Full-Press of Camera' key */
  57
  58 #define KEY_POWER               "XF86PowerOff"  /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Power' key */
  59 #define KEY_PAUSE               "XF86Standby"   /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Pause' key */
  60 #define KEY_CANCEL              "Cancel"        /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Cancel' key */
  61
  62 // Earjack/BT Headset/Multimedia keys
  63 #define KEY_PLAYCD              "XF86AudioPlay" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Play Audio' key */
  64 #define KEY_STOPCD              "XF86AudioStop" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Stop Audio' key */
  65 #define KEY_PAUSECD             "XF86AudioPause"        /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Pause Audio' key */
  66 #define KEY_NEXTSONG            "XF86AudioNext" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Next Song' key */
  67 #define KEY_PREVIOUSSONG        "XF86AudioPrev" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Previous Song' key */
  68 #define KEY_REWIND              "XF86AudioRewind"       /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Rewind Song' key */
  69 #define KEY_FASTFORWARD         "XF86AudioForward"      /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Forward Song' key */
  70 #define KEY_MEDIA               "XF86AudioMedia"        /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Media' key */
  71 #define KEY_PLAYPAUSE           "XF86AudioPlay" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'PlayPause' key */
  72 #define KEY_MUTE                        "XF86AudioMute" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Mute' key */
  73
  74 // 3-Touch key
  75 #define KEY_SEND                "XF86Send"      /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Send' key */
  76 #define KEY_SELECT              "XF86Phone"     /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Home' key */
  77 #define KEY_END                 "XF86Stop"      /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'End' key */
  78
  79 // Renamed 3-Touch key
  80 #define KEY_MENU                "XF86Send"      /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Send' key */
  81 #define KEY_HOME                "XF86Phone"     /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Home' key */
  82 #define KEY_BACK                "XF86Stop"      /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'End' key */
  83
  84 //Other functions keys
  85 #define KEY_HOMEPAGE            "XF86HomePage"  /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'HomePage' key */
  86 #define KEY_WEBPAGE             "XF86WWW"       /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'WWW' key */
  87 #define KEY_MAIL                        "XF86Mail"      /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Mail' key */
  88 #define KEY_SCREENSAVER "XF86ScreenSaver"       /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'ScreenSaver' key */
  89 #define KEY_BRIGHTNESSUP        "XF86MonBrightnessUp"   /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'BrightnessUp' key */
  90 #define KEY_BRIGHTNESSDOWN      "XF86MonBrightnessDown" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'BrightnessDown' key */
  91 #define KEY_SOFTKBD                     "XF86MenuKB"    /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Soft keyboard(toggle)' key */
  92 #define KEY_QUICKPANEL          "XF86Tools"     /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Quick panel(toggle)' key */
  93 #define KEY_TASKSWITCH          "XF86TaskPane"  /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Task switcher(toggle)' key */
  94 #define KEY_APPS                "XF86Launch0"   /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Apptray(toggle)' key */
  95 #define KEY_SEARCH              "XF86Search"            /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Search(toggle)' key */
  96 #define KEY_VOICE               "XF86Launch2"           /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Voice(toggle)' key */
  97 #define KEY_LANGUAGE            "Hangul"                /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Language(toggle)' key */
  98
  99 #define LEN_KEY_VOLUMEUP                20      /**< this macro is the length of string corresponds to 'Volume Up' key */
 100 #define LEN_KEY_VOLUMEDOWN      20      /**< this macro is the length of string corresponds to 'Volume Down' key */
 101
 102 #define LEN_KEY_CAMERA          10      /**< this macro is the length of string corresponds to 'Half-Press of Camera' key */
 103 #define LEN_KEY_CONFIG          12      /**< this macro is the length of string corresponds to 'Full-Press of Camera' key */
 104
 105 #define LEN_KEY_POWER           12      /**< this macro is the length of string corresponds to 'Power' key */
 106 #define LEN_KEY_PAUSE           11      /**< this macro is the length of string corresponds to 'Pause' key */
 107
 108 // Earjack/BT Headset/Multimedia keys
 109 #define LEN_KEY_PLAYCD          13/**< this macro is the length of string corresponds to 'Play Audio' key */
 110 #define LEN_KEY_STOPCD          13/**< this macro is the length of string corresponds to 'Stop Audio' key */
 111 #define LEN_KEY_PAUSECD         14/**< this macro is the length of string corresponds to 'Pause Audio' key */
 112 #define LEN_KEY_NEXTSONG        13/**< this macro is the length of string corresponds to 'Next Song' key */
 113 #define LEN_KEY_PREVIOUSSONG            13/**< this macro is the length of string corresponds to 'Previous Song' key */
 114 #define LEN_KEY_REWIND          15/**< this macro is the length of string corresponds to 'Rewind Song' key */
 115 #define LEN_KEY_FASTFORWARD             16/**< this macro is the length of string corresponds to 'Forwand Song' key */
 116 #define LEN_KEY_MEDIA           14/**< this macro is the length of string corresponds to 'Media' key */
 117 #define LEN_KEY_PLAYPAUSE       13      /**< this macro is the length of string corresponds to 'PlayPause' key */
 118 #define LEN_KEY_MUTE            13      /**< this macro is the length of string corresponds to 'Mute' key */
 119
 120 // 3-Touch key
 121 #define LEN_KEY_SEND            8       /**< this macro is the length of string corresponds to 'Send' key */
 122 #define LEN_KEY_SELECT          9       /**< this macro is the length of string corresponds to 'Home' key */
 123 #define LEN_KEY_END             8       /**< this macro is the length of string corresponds to 'End' key */
 124
 125 // Renamed 3-Touch key
 126 #define LEN_KEY_MENU            8       /**< this macro is the length of string corresponds to 'Send' key */
 127 #define LEN_KEY_HOME            9       /**< this macro is the length of string corresponds to 'Home' key */
 128 #define LEN_KEY_BACK            8       /**< this macro is the length of string corresponds to 'End' key */
 129
 130 //Other functions keys
 131 #define LEN_KEY_HOMEPAGE        12      /**< this macro is the length of string corresponds to 'HomePage' key */
 132 #define LEN_KEY_WEBPAGE 7       /**< this macro is the length of string corresponds to 'WWW' key */
 133 #define LEN_KEY_MAIL            8       /**< this macro is the length of string corresponds to 'Mail' key */
 134 #define LEN_KEY_SCREENSAVER     15      /**< this macro is the length of string corresponds to 'ScreenSaver' key */
 135 #define LEN_KEY_BRIGHTNESSUP    19      /**< this macro is the length of string corresponds to 'BrightnessUp' key */
 136 #define LEN_KEY_BRIGHTNESSDOWN  21      /**< this macro is the length of string corresponds to 'BrightnessDown' key */
 137
 138 #define LEN_KEY_SOFTKBD         10      /**< this macro is the length of string corresponds to 'Soft keyboard(toggle)' key */
 139 #define LEN_KEY_QUICKPANEL              9       /**< this macro is the length of string corresponds to 'Quick panel(toggle)' key */
 140 #define LEN_KEY_TASKSWITCH      12      /**< this macro is the length of string corresponds to 'Task switcher(toggle)' key */
 141 #define LEN_KEY_APPS                    11      /**< this macro is the length of string corresponds to 'Apptray(toggle)' key */
 142 #define LEN_KEY_SEARCH                  10      /**< this macro is the length of string corresponds to 'Search(toggle)' key */
 143 #define LEN_KEY_VOICE                   11      /**< this macro is the length of string corresponds to 'Voice(toggle)' key */
 144 #define LEN_KEY_LANGUAGE                6       /**< this macro is the length of string corresponds to 'Language(toggle)' key */
 145
 146 #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 */
 147 #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 */
 148 #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 */
 149 #define SHARED_GRAB             0x000f00        /**< this means that the client window will get the grabbed-key together with the other client window(s) */
 150 #define GRAB_MODE_MASK  0xffff00        /**< this mask will be used for getting the key-grab mode of a client window */
 151
 152 #define EXCLUSIVE_GRABBED_ALREADY       1       /**< this means that the client window is grabbing the key already in EXCLUSIVE mode */
 153
 154 #define STR_ATOM_GRAB_KEY       "_GRAB_KEY"     /**< this is an XATOM for getting/setting the property for grabbing a key for a window */
 155 #define STR_ATOM_GRAB_EXCL_WIN  "_GRAB_EXCL_WIN_KEYCODE"        /**< this means that the key was grabbed by a client window in EXCLUSIVE mod */
 156 #define STR_ATOM_GRAB_OR_EXCL_WIN       "_GRAB_OR_EXCL_WIN_KEYCODE"     /**< this means that the key was grabbed by a client window in OR_EXCLUSIVE mod */
 157
 158 #define STR_ATOM_SCRNCONF_STATUS "_SCRNCONF_STATUS" /**< this is an XATOM for getting the status of the screen configuration through the client message */
 159
 160 /**
 161  * @brief Enumeration of screen configuration status
 162  */
 163 typedef enum _Utilx_Scrnconf_Status
 164 {
 165         UTILX_SCRNCONF_STATUS_NULL,    /**< screen configuration status is null */
 166         UTILX_SCRNCONF_STATUS_CONNECT, /**< screen configuration status is connect */
 167         UTILX_SCRNCONF_STATUS_ACTIVE   /**< screen configuration status is active */
 168 } Utilx_Scrnconf_Status;
 169
 170 /**
 171  * @brief Enumeration of screen configuration display mode
 172  */
 173 typedef enum _Utilx_Scrnconf_Dispmode
 174 {
 175         UTILX_SCRNCONF_DISPMODE_NULL,    /**< display mode of screen configuration is null */
 176         UTILX_SCRNCONF_DISPMODE_CLONE,   /**< display mode of screen configuration is clone */
 177         UTILX_SCRNCONF_DISPMODE_EXTENDED /**< display mode of screen configuration is extended */
 178 } Utilx_Scrnconf_Dispmode;
 179
 180
 181 /**
 182  * @brief Enumeration of key status
 183  */
 184 typedef enum _Utilx_Key_Status
 185 {
 186         UTILX_KEY_STATUS_PRESSED, /**< key status is pressed */
 187         UTILX_KEY_STATUS_RELEASED, /**< key status is released */
 188         UTILX_KEY_STATUS_UNKNOWN /** < key status is unknown or error happened */
 189 } Utilx_Key_Status;
 190
 191 /**
 192  * @brief Enumeration of notification window's priority level
 193  */
 194 typedef enum _Utilx_Notification_Level
 195 {
 196         UTILX_NOTIFICATION_LEVEL_LOW, /**< low level notification */
 197         UTILX_NOTIFICATION_LEVEL_NORMAL, /**< normal level notification*/
 198         UTILX_NOTIFICATION_LEVEL_HIGH /**< high level notification */
 199 } Utilx_Notification_Level;
 200
 201 /**
 202  * @brief Enumeration of Compositing Window Manager's Effect Type
 203  */
 204 typedef enum _Utilx_Effect_Type
 205 {
 206         UTILX_EFFECT_TYPE_MAP, /**< Effect for Window's Map Notify Event */
 207         UTILX_EFFECT_TYPE_UNMAP, /**< Effect for Window's UnMap Notify Event */
 208         UTILX_EFFECT_TYPE_RAISEABOVE, /**< Effect for Window's Configure Notify ( RaiseAbove case ) Event */
 209         UTILX_EFFECT_TYPE_ROTATION, /**< Effect for Window's Rotation Property Change Notify Event ( X Property: ECORE_X_ATOM_E_ILLUME_ROTATE_WINDOW_ANGLE ) */
 210         UTILX_EFFECT_TYPE_FOCUSIN, /**< Effect for Window's FocusIn Event ( E17's Event: E_EVENT_BORDER_FOCUS_IN ) */
 211         UTILX_EFFECT_TYPE_FOCUSOUT /**< Effect for Window's FocusOut Event ( E17's Event : E_EVENT_BORDER_FOCUS_OUT ) */
 212 } Utilx_Effect_Type;
 213
 214 /**
 215  * @brief Enumeration of Compositing Window Manager's Effect Style
 216  */
 217 typedef enum _Utilx_Effect_Style
 218 {
 219         UTILX_EFFECT_STYLE_DEFAULT, /**< Default Effect Style for Effect Type */
 220         UTILX_EFFECT_STYLE_NONE, /**< None of Effect Style for Effect Type */
 221         UTILX_EFFECT_STYLE_CUSTOM0, /**< Custom0 Effect Style for Effect Type */
 222         UTILX_EFFECT_STYLE_CUSTOM1, /**< Custom1 Effect Style for Effect Type */
 223         UTILX_EFFECT_STYLE_CUSTOM2, /**< Custom2 Effect Style for Effect Type */
 224         UTILX_EFFECT_STYLE_CUSTOM3, /**< Custom3 Effect Style for Effect Type */
 225         UTILX_EFFECT_STYLE_CUSTOM4, /**< Custom4 Effect Style for Effect Type */
 226         UTILX_EFFECT_STYLE_CUSTOM5, /**< Custom5 Effect Style for Effect Type */
 227         UTILX_EFFECT_STYLE_CUSTOM6, /**< Custom6 Effect Style for Effect Type */
 228         UTILX_EFFECT_STYLE_CUSTOM7, /**< Custom7 Effect Style for Effect Type */
 229         UTILX_EFFECT_STYLE_CUSTOM8, /**< Custom8 Effect Style for Effect Type */
 230         UTILX_EFFECT_STYLE_CUSTOM9 /**< Custom9 Effect Style for Effect Type */
 231 } Utilx_Effect_Style;
 232
 233 /**
 234  * @brief Enumeration of opaque state
 235  */
 236 typedef enum _Utilx_Opaque_State
 237 {
 238         UTILX_OPAQUE_STATE_OFF = 0, /**< Transparent state */
 239         UTILX_OPAQUE_STATE_ON  = 1, /**< Opaque state */
 240 } Utilx_Opaque_State;
 241
 242 /**
 243  * @brief Enumeration of Fb's type
 244  */
 245 typedef enum _Utilx_Fb_Type
 246 {
 247         UTILX_FB_TYPE_NONE     = 0, /**< None type */
 248         UTILX_FB_TYPE_UI       = 1, /**< Framebuffer type is 'UI' */
 249         UTILX_FB_TYPE_OVERLAY  = 2, /**< Framebuffer type is 'Overlay' */
 250 } Utilx_Fb_Type;
 251
 252 /**
 253  * @brief Structure of screen configuration information
 254  */
 255 typedef struct _UtilxScrnConf
 256 {
 257         char *str_output;                 /**< string value for the connector type */
 258         Utilx_Scrnconf_Status status;     /**< status of screen configurtaion */
 259         char *str_resolution;             /**< string value for the resolution to be active status */
 260         Utilx_Scrnconf_Dispmode dispmode; /**< display mode of screen configuration to be active status */
 261 } UtilxScrnConf;
 262
 263 /**
 264  * @fn ScrnConf *utilx_scrnconf_allocate(void)
 265  * @brief allocate the UtilxScrnConf structure
 266  *
 267  * This function allocate the UtilxScrnConf structure.\n
 268  *
 269  * @remark This is used only application which want to know the screen configuration info.
 270  * @pre  This api does not require any pre-condition.
 271  * @post This api does not change any condition.
 272  * @see utilx_scrnconf_allocate
 273  * @par Example
 274   @code
 275   #include <utilX.h>
 276   ...
 277
 278   UtilxScrnConf *scrnconf = NULL;
 279
 280   // Allocate the UtilxScrnConf structure
 281   scrnconf = utilx_scrnconf_allocate();
 282    ...
 283   @endcode
 284  */
 285 UtilxScrnConf *utilx_scrnconf_allocate (void);
 286
 287 /**
 288  * @fn void utilx_scrnconf_free (UtilxScrnConf *scrnconf)
 289  * @brief free the UtilxScrnConf structure
 290  *
 291  * This function free the UtilxScrnConf structure.\n
 292  *
 293  * @param[in] scrnconf Specifies the UtilxScrnConf structure
 294  * @return instance of the UtilxScrnConf structure
 295  * @remark This is used only application which want to know the screen configuration info.
 296  * @pre  This api does not require any pre-condition.
 297  * @post This api does not change any condition.
 298  * @see utilx_scrnconf_free
 299  * @par Example
 300   @code
 301   #include <utilX.h>
 302   ...
 303
 304   UtilxScrnConf *scrnconf = NULL;
 305
 306   // Allocate the UtilxScrnConf structure
 307   scrnconf = utilx_scrnconf_allocate();
 308    ...
 309
 310   // Free the UtilxScrnConf structure
 311   utilx_scrnconf_free(scrnconf);
 312    ...
 313   @endcode
 314  */
 315 void utilx_scrnconf_free (UtilxScrnConf *scrnconf);
 316
 317 /**
 318  * @fn void utilx_scrnconf_get_info (Display *dpy, UtilxScrnConf *scrnconf)
 319  * @brief get the information of the screen configuration
 320  *
 321  * This function get the information of the screen configuration.\n
 322  *
 323  * This function is a asynchronous call.
 324  *
 325  * @param[in] dpy Specifies the connection to the X server
 326  * @param[in] scrnconf Specifies the information structure of the screen configuration
 327  * @remark This is used only application which want to know the screen configuration info.
 328  * @pre  This api does not require any pre-condition.
 329  * @post This api does not change any condition.
 330  * @see utilx_scrnconf_get_info
 331  * @par Example
 332   @code
 333   #include <X11/Xlib.h>
 334   #include <utilX.h>
 335   ...
 336
 337   Display* dpy;
 338   UtilxScrnConf *scrnconf = NULL;
 339   int ret = 0;
 340
 341   dpy = XOpenDisplay (NULL);
 342
 343   // Allocate the UtilxScrnConf structure
 344   scrnconf = utilx_scrnconf_allocate();
 345   ...
 346
 347   // Set the display mode for the screen configuration
 348   ret = utilx_scrnconf_get_info (dpy, scrnconf);
 349   ...
 350
 351   // Free the UtilxScrnConf structure
 352   utilx_scrnconf_free(scrnconf);
 353    ...
 354
 355   @endcode
 356  */
 357 int utilx_scrnconf_get_info (Display *dpy, UtilxScrnConf *scrnconf);
 358
 359
 360 /**
 361  * @fn void utilx_scrnconf_set_dispmode (Display *dpy, Utilx_Scrnconf_Dispmode dispmode)
 362  * @brief set the display mode for the screen configuration
 363  *
 364  * This function set the display mode for the screen configuration.\n
 365  *
 366  * This function is a asynchronous call.
 367  *
 368  * @param[in] dpy Specifies the connection to the X server
 369  * @param[in] dipmode Specifies the display mode of the screen configuration
 370  * @return 1 if setting the dispmode is succeeded, 0 if setting the dispmode is failed.
 371  * @remark This is used only application which want to set the display mode of the screen configuration.
 372  * @pre  This api does not require any pre-condition.
 373  * @post This api does not change any condition.
 374  * @see utilx_scrnconf_set_dispmode
 375  * @par Example
 376   @code
 377   #include <X11/Xlib.h>
 378   #include <utilX.h>
 379   ...
 380
 381   Display* dpy;
 382
 383   dpy = XOpenDisplay (NULL);
 384
 385   // Set the display mode for the screen configuration
 386   utilx_scrnconf_set_dispmode (dpy, UTILX_SCRNCONF_DISPMODE_CLONE);
 387    ...
 388   @endcode
 389  */
 390 int utilx_scrnconf_set_dispmode (Display *dpy, Utilx_Scrnconf_Dispmode dispmode);
 391
 392
 393 /**
 394  * @fn void utilx_set_system_notification_level (Display* dpy, Window win, Utilx_Notification_Level level)
 395  * @brief Sets the priority level for the specified notification window
 396  *
 397  * This function sets the priority level of the notification windows.\n
 398  * Every notification window has a base priority level by the notification window's priority value. (Default priority is UTILX_NOTIFICATION_LEVEL_LOW)
 399  *
 400  * The priority is used for ordering of notification windows.\n
 401  * The notification window which is set UTILX_NOTIFICATION_LEVEL_HIGH priority will be placed to the top of notification windows.\n
 402  * If there are notification windows that have same priorities, the latest created notification window is placed on the other window.
 403  *
 404  * This function is a asynchronous call.
 405  *
 406  * @param[in] dpy Specifies the connection to the X server
 407  * @param[in] win Specifies the window to be set
 408  * @param[in] level Specifies the level (UTILX_NOTIFICATION_LEVEL_LOW, UTILX_NOTIFICATION_LEVEL_NORMAL, UTILX_NOTIFICATION_LEVEL_HIGH)
 409  * @remark This is used only notification window.
 410  * @pre The win should be notification type window
 411  * @post None
 412  * @see utilx_get_system_notification_level
 413  * @par Example
 414   @code
 415   #include <utilX.h>
 416
 417   ...
 418
 419   Evas_Object *win;
 420   Ecore_X_Window xwin;
 421
 422   win = create_mwnd();
 423   xwin = elm_win_xwindow_get(win);
 424
 425   // Set Notification type
 426   ecore_x_netwm_window_type_set (xwin, ECORE_X_WINDOW_TYPE_NOTIFICATION);
 427
 428   // Set Notification's priority
 429   utilx_set_system_notification_level (ecore_x_display_get(), xwin, UTILX_NOTIFICATION_LEVEL_HIGH);
 430
 431   ...
 432   @endcode
 433  */
 434 void utilx_set_system_notification_level (Display* dpy, Window win, Utilx_Notification_Level level);
 435
 436 /**
 437  * @fn Utilx_Notification_Level utilx_get_system_notification_level (Display* dpy, Window win)
 438  * @brief Gets the priority level for the specified notification window
 439  *
 440  * This function returns the priority level of the notification windows.\n
 441  * If a user didn't set the notification's priority level, this function returns default value (UTILX_NOTIFICATION_LEVEL_LOW).
 442  *
 443  * This function is a synchronous call.
 444  *
 445  * @param[in] dpy Specifies the connection to the X server
 446  * @param[in] win Specifies the window to be get
 447  * @return current notication level (UTILX_NOTIFICATION_LEVEL_LOW, UTILX_NOTIFICATION_LEVEL_NORMAL, UTILX_NOTIFICATION_LEVEL_HIGH)
 448  * @remark This is used only notification window.
 449  * @pre The win should be notification type window
 450  * @post None
 451  * @see utilx_set_system_notification_level
 452  * @par Example
 453   @code
 454   #include <utilX.h>
 455
 456   ...
 457
 458   Evas_Object *win;
 459   Ecore_X_Window xwin;
 460   Utilx_Notification_Level level;
 461
 462   win = elm_win_add (NULL, "test", ELM_WIN_NOTIFICATION);
 463   xwin = elm_win_xwindow_get(win);
 464
 465   level = utilx_get_system_notification_level (ecore_x_display_get(), xwin);
 466
 467   ...
 468   @endcode
 469  */
 470 Utilx_Notification_Level utilx_get_system_notification_level (Display* dpy, Window win);
 471
 472 /**
 473  * @fn void utilx_enable_indicator (Display* dpy, Window win, int enable)
 474  * @brief Sets the window to show/hide the indicator
 475  *
 476  * This function enables or disables the indicator.
 477  *
 478  * If an application wants to show the window with the indicator, the application must call this function with 1 as the enable parameter.\n
 479  * Otherwise, the application must call this function with 0 as the enable parameter.
 480  *
 481  * This function is a asynchronous call.
 482  *
 483  * @param[in] dpy Specifies the connection to the X server
 484  * @param[in] win Specifies the window to use indicator
 485  * @param[in] enable Specifies whether the window use indicator or not
 486  * @remark None
 487  * @pre None
 488  * @post If the enable is 1, then the indicator window should be shown on the screen. Otherwise, the indicator window should be hidden from the screen.
 489  * @see elm_win_indicator_state_set, utilx_get_indicator_state
 490  * @par Example
 491   @code
 492   #include <X11/Xlib.h>
 493   #include <utilX.h>
 494
 495   ...
 496
 497   Display* dpy;
 498   Window root, win;
 499
 500   dpy = XOpenDisplay (NULL);
 501   root = XDefaultRootWindow (dpy);
 502
 503   win = XCreateSimpleWindow (dpy, root, 0, 0, 480, 800, 2, BlackPixel (dpy,0), WhitePixel(dpy,0));
 504   XMapWindow (dpy, win);
 505
 506   // If the win want to show indicator, enables indicator.
 507   utilx_enable_indicator (dpy, win, 1);
 508   XFlush (d);
 509
 510   // If the win want to hide indicator, disables indicator.
 511   utilx_enable_indicator (dpy, win, 0);
 512   XFlush (d);
 513
 514   ...
 515   @endcode
 516  */
 517 void utilx_enable_indicator (Display* dpy, Window win, int enable);
 518
 519 /**
 520  * @fn int utilx_get_indicator_state (Display* dpy, Window win)
 521  * @brief Gets the indicator's state of the specified window
 522  *
 523  * This function gets the indicator's state of the specified window.
 524  *
 525  * An application can set the indicator's state using utilx_enable_indicator or elm_win_indicator_state_set.
 526  * If an application sets enables the indicator, this returns 1.\n
 527  * If an application disables the indicator, this returns 0.\n
 528  * If an application doesn't set the indicator's state, in other words,
 529  * an application doesn't call utilx_enable_indicator or elm_win_indicator_state_set,
 530  * this returns -1.
 531  *
 532  * This function is a asynchronous call.
 533  *
 534  * @param[in] dpy Specifies the connection to the X server
 535  * @param[in] win Specifies the window to get the indicator's state
 536  * @return 1 if the indicator is enabled, 0 if the indicator is disabled, otherwise -1
 537  * @remark None
 538  * @pre None
 539  * @post None
 540  * @see elm_win_indicator_state_set, utilx_enable_indicator
 541  * @par Example
 542   @code
 543   #include <X11/Xlib.h>
 544   #include <utilX.h>
 545
 546   ...
 547
 548   Display* dpy;
 549   Window root, win;
 550   int state;
 551
 552   dpy = XOpenDisplay (NULL);
 553   root = XDefaultRootWindow (dpy);
 554
 555   win = XCreateSimpleWindow (dpy, root, 0, 0, 480, 800, 2, BlackPixel (dpy,0), WhitePixel(dpy,0));
 556   XMapWindow (dpy, win);
 557
 558   state = utilx_get_indicator_state (dpy, win)
 559   // state is -1 (unknown)
 560
 561   // If the win want to show indicator, enables indicator.
 562   utilx_enable_indicator (dpy, win, 1);
 563   XFlush (d);
 564
 565   state = utilx_get_indicator_state (dpy, win)
 566   // state is 1 (enabled)
 567
 568   // If the win want to hide indicator, disables indicator.
 569   utilx_enable_indicator (dpy, win, 0);
 570   XFlush (d);
 571
 572   state = utilx_get_indicator_state (dpy, win)
 573   // state is 0 (disabled)
 574
 575   ...
 576   @endcode
 577  */
 578 int utilx_get_indicator_state (Display* dpy, Window win);
 579
 580
 581 /**
 582  * @fn int utilx_grab_key (Display* dpy, Window win, const char* key_name, int grab_mode)
 583  * @brief Grabs a key specfied by key_name for win in grab_mode
 584  *
 585  * This function establishs a grab of the specified key for the specified window.\n
 586  * Once a key was grabbed, all events originated from the key will only be reported to the specfied window.\n
 587  * The grab of the key will be released by calling utilx_ungrab_key.
 588  *
 589  * This function is synchronous.
 590  *
 591  * @param[in] dpy Specifies the connection to the X server
 592  * @param[in] win Specifies the window to grab a key
 593  * @param[in] key_name Name of a key in string (ex> KEY_VOLUMEUP, KEY_VOLUMEDOWN, KEY_SEND and so on)
 594  * @param[in] grab_mode Grab mode (such as EXCLUSIVE_GRAB, TOP_POSITION_GRAB and SHARED_GRAB)
 595  * @return 0 on Success, otherwise Fail
 596  * @remark If utilx_grab_key() returns 0, the specified window will get the events of the specified key.\n
 597                   However, delivery of a key can always be changed by other applications grabbing the key with higher priority.\n
 598                   It can also be changed by the changes of window stacks.\n
 599                   Trial for choosing a proper grab mode will be needed.
 600  * @pre This API must be called after the window 'win' has been mapped
 601  * @post This API adds/changes the window property related to grabbed key
 602  * @see utilx_ungrab_key
 603  * @par Example (using X11 APIs)
 604   @code
 605
 606   // EXCLUSIVE_GRAB //
 607
 608   #include <X11/Xlib.h>
 609   #include <utilX.h>
 610
 611   int main()
 612   {
 613         Display *disp = XOpenDisplay(NULL);
 614         XEvent e;
 615         int grab_result;
 616         Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(d,0), WhitePixel(d,0));
 617         XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask);
 618         XMapWindow(disp, w);
 619
 620         while(1)
 621         {
 622               XNextEvent(disp, &e);
 623               switch(e.type)
 624               {
 625                      case MapNotify:
 626                       grab_result = utilx_grab_key(disp, w, KEY_POWER, EXCLUSIVE_GRAB);
 627                       if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
 628                             return -1;
 629                       break;
 630               }
 631               ...
 632         }
 633         ...
 634
 635         utilx_ungrab_key(disp, win, KEY_POWER);
 636         return 0;
 637   }
 638
 639   // TOP_POSITION_GRAB //
 640
 641   #include <X11/Xlib.h>
 642   #include <utilX.h>
 643
 644   int main()
 645   {
 646         Display *disp = XOpenDisplay(NULL);
 647         XEvent e;
 648         Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(d,0), WhitePixel(d,0));
 649         XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask);
 650         XMapWindow(disp, w);
 651
 652         while(1)
 653         {
 654               XNextEvent(disp, &e);
 655               switch(e.type)
 656               {
 657                      case MapNotify:
 658                       utilx_grab_key(disp, w, KEY_POWER, TOP_POSITION_GRAB);
 659                       break;
 660               }
 661               ...
 662         }
 663         ...
 664
 665         utilx_ungrab_key(disp, win, KEY_POWER);
 666         return 0;
 667   }
 668
 669   // SHARED_GRAB //
 670
 671   #include <X11/Xlib.h>
 672   #include <utilX.h>
 673
 674   int main()
 675   {
 676         Display *disp = XOpenDisplay(NULL);
 677         XEvent e;
 678         Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(d,0), WhitePixel(d,0));
 679         XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask);
 680         XMapWindow(disp, w);
 681
 682         while(1)
 683         {
 684               XNextEvent(disp, &e);
 685               switch(e.type)
 686               {
 687                      case MapNotify:
 688                       utilx_grab_key(disp, w, KEY_POWER, SHARED_GRAB);
 689                       break;
 690               }
 691               ...
 692         }
 693         ...
 694
 695         utilx_ungrab_key(disp, win, KEY_POWER);
 696         return 0;
 697   }
 698
 699   @endcode
 700    * @par Example (using EFL APIs)
 701   @code
 702
 703   // EXCLUSIVE_GRAB //
 704
 705   #include <utilX.h>
 706   #include <Ecore_Evas.h>
 707   #include <Ecore_X.h>
 708
 709   int main()
 710   {
 711         ...
 712
 713         Ecore_X_Display* disp = ecore_x_display_get();
 714         Ecore_X_Window win = ecore_evas_software_x11_window_get(ee);
 715
 716         int grab_result = utilx_grab_key(disp, win, KEY_POWER, EXCLUSIVE_GRAB);
 717         if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
 718                 return -1;
 719
 720         ...
 721
 722         utilx_ungrab_key(disp, win, KEY_POWER);//Ungrab whenever you want to ¡¦
 723         return 0;
 724   }
 725
 726   // TOP_POSITION_GRAB //
 727
 728   #include <utilX.h>
 729   #include <Ecore_Evas.h>
 730   #include <Ecore_X.h>
 731
 732   int main()
 733   {
 734         ...
 735
 736         Ecore_X_Display* disp = ecore_x_display_get();
 737         Ecore_X_Window win = ecore_evas_software_x11_window_get(ee);
 738
 739         utilx_grab_key(disp, win, KEY_POWER, TOP_POSITION_GRAB);
 740
 741         ...
 742
 743         utilx_ungrab_key(disp, win, KEY_POWER);//Ungrab whenever you want to ¡¦
 744         return 0;
 745   }
 746
 747   // SHARED_GRAB //
 748
 749   #include <utilX.h>
 750   #include <Ecore_Evas.h>
 751   #include <Ecore_X.h>
 752
 753   int main()
 754   {
 755         ...
 756
 757         Ecore_X_Display* disp = ecore_x_display_get();
 758         Ecore_X_Window win = ecore_evas_software_x11_window_get(ee);
 759
 760         utilx_grab_key(disp, win, KEY_POWER, SHARED_GRAB);
 761
 762         ...
 763
 764         utilx_ungrab_key(disp, win, KEY_POWER);//Ungrab whenever you want to ¡¦
 765         return 0;
 766   }
 767   @endcode
 768  */
 769 int utilx_grab_key (Display* dpy, Window win, const char* key_name, int grab_mode);
 770
 771 /**
 772  * @fn int utilx_ungrab_key (Display* dpy, Window win, const char* key_name)
 773  * @brief Ungrabs a key specfied by key_name for win
 774  *
 775  * This function releases the already established grab of the specfied key for the specified window.\n
 776  * Once the grab of the key was released, delivery of the key events for the specfied window is going to be stopped.
 777  *
 778  * This function is synchronous.
 779  *
 780  * @param[in] dpy Specifies the connection to the X server
 781  * @param[in] win Specifies the window to grab a key
 782  * @param[in] key_name Name of a key in string (ex> KEY_VOLUMEUP, KEY_VOLUMEDOWN, KEY_SEND and so on)
 783  * @return 0 on Success, otherwise Fail
 784  * @remark No additional information
 785  * @pre This API must be called after the window 'win' has been mapped
 786  * @post This API changes/removes the window property related to grabbed key
 787  * @see utilx_grab_key
 788  * @par Example (using X11 APIs)
 789   @code
 790
 791   // EXCLUSIVE_GRAB //
 792
 793   #include <X11/Xlib.h>
 794   #include <utilX.h>
 795
 796   int main()
 797   {
 798         Display *disp = XOpenDisplay(NULL);
 799         XEvent e;
 800         int grab_result;
 801         Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(d,0), WhitePixel(d,0));
 802         XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask);
 803         XMapWindow(disp, w);
 804
 805         while(1)
 806         {
 807               XNextEvent(disp, &e);
 808               switch(e.type)
 809               {
 810                      case MapNotify:
 811                       grab_result = utilx_grab_key(disp, w, KEY_POWER, EXCLUSIVE_GRAB);
 812                       if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
 813                             return -1;
 814                       break;
 815               }
 816               ...
 817         }
 818         ...
 819
 820         utilx_ungrab_key(disp, win, KEY_POWER);
 821         return 0;
 822   }
 823
 824   // TOP_POSITION_GRAB //
 825
 826   #include <X11/Xlib.h>
 827   #include <utilX.h>
 828
 829   int main()
 830   {
 831         Display *disp = XOpenDisplay(NULL);
 832         XEvent e;
 833         Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(d,0), WhitePixel(d,0));
 834         XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask);
 835         XMapWindow(disp, w);
 836
 837         while(1)
 838         {
 839               XNextEvent(disp, &e);
 840               switch(e.type)
 841               {
 842                      case MapNotify:
 843                       utilx_grab_key(disp, w, KEY_POWER, TOP_POSITION_GRAB);
 844                       break;
 845               }
 846               ...
 847         }
 848         ...
 849
 850         utilx_ungrab_key(disp, win, KEY_POWER);
 851         return 0;
 852   }
 853
 854   // SHARED_GRAB //
 855
 856   #include <X11/Xlib.h>
 857   #include <utilX.h>
 858
 859   int main()
 860   {
 861         Display *disp = XOpenDisplay(NULL);
 862         XEvent e;
 863         Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(d,0), WhitePixel(d,0));
 864         XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask);
 865         XMapWindow(disp, w);
 866
 867         while(1)
 868         {
 869               XNextEvent(disp, &e);
 870               switch(e.type)
 871               {
 872                      case MapNotify:
 873                       utilx_grab_key(disp, w, KEY_POWER, SHARED_GRAB);
 874                       break;
 875               }
 876               ...
 877         }
 878         ...
 879
 880         utilx_ungrab_key(disp, win, KEY_POWER);
 881         return 0;
 882   }
 883
 884   @endcode
 885    * @par Example (using EFL APIs)
 886   @code
 887
 888   // EXCLUSIVE_GRAB //
 889
 890   #include <utilX.h>
 891   #include <Ecore_Evas.h>
 892   #include <Ecore_X.h>
 893
 894   int main()
 895   {
 896         ...
 897
 898         Ecore_X_Display* disp = ecore_x_display_get();
 899         Ecore_X_Window win = ecore_evas_software_x11_window_get(ee);
 900
 901         int grab_result = utilx_grab_key(disp, win, KEY_POWER, EXCLUSIVE_GRAB);
 902         if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
 903                 return -1;
 904         ...
 905
 906         utilx_ungrab_key(disp, win, KEY_POWER);//Ungrab whenever you want to ¡¦
 907         return 0;
 908   }
 909
 910   // TOP_POSITION_GRAB //
 911
 912   #include <utilX.h>
 913   #include <Ecore_Evas.h>
 914   #include <Ecore_X.h>
 915
 916   int main()
 917   {
 918         ...
 919
 920         Ecore_X_Display* disp = ecore_x_display_get();
 921         Ecore_X_Window win = ecore_evas_software_x11_window_get(ee);
 922
 923         utilx_grab_key(disp, win, KEY_POWER, TOP_POSITION_GRAB);
 924
 925         ...
 926
 927         utilx_ungrab_key(disp, win, KEY_POWER);//Ungrab whenever you want to ¡¦
 928
 929         return 0;
 930   }
 931
 932   // SHARED_GRAB //
 933
 934   #include <utilX.h>
 935   #include <Ecore_Evas.h>
 936   #include <Ecore_X.h>
 937
 938   int main()
 939   {
 940         ...
 941
 942         Ecore_X_Display* disp = ecore_x_display_get();
 943         Ecore_X_Window win = ecore_evas_software_x11_window_get(ee);
 944
 945         utilx_grab_key(disp, win, KEY_POWER, SHARED_GRAB);
 946
 947         ...
 948
 949         utilx_ungrab_key(disp, win, KEY_POWER);//Ungrab whenever you want to ¡¦
 950         return 0;
 951   }
 952   @endcode
 953  */
 954 int utilx_ungrab_key (Display* dpy, Window win, const char* key_name);
 955
 956 /**
 957  * @fn int utilx_get_key_status(Display* dpy, char *key_name)
 958  * @brief Gets a status of a key specified by key_name
 959  *
 960  * This function gets a status of a key.\n
 961  * ex>UTILX_KEY_STATUS_PRESSED, UTILX_KEY_STATUS_RELEASED and UTILX_KEY_STATUS_UNKNOWN
 962  *
 963  * This function is synchronous.
 964  *
 965  * @param[in] dpy Specifies the connection to the X server
 966  * @param[in] key_name Name of a key in string (ex> KEY_VOLUMEUP, KEY_VOLUMEDOWN, KEY_SEND and so on)
 967  * @return 0 on Success, otherwise Fail
 968  * @remark No additional information
 969  * @pre This API must be called for H/W keys specified in this header file(utilX.h).
 970  * @par Example (using X11 APIs)
 971   @code
 972
 973   #include <X11/Xlib.h>
 974   #include <utilX.h>
 975
 976   int main()
 977   {
 978         Display *disp = XOpenDisplay(NULL);
 979         Utilx_Key_Status status;
 980
 981         status = utilx_get_key_status(disp, KEY_PLAYCD);
 982
 983         switch( status )
 984         {
 985                 case UTILX_KEY_STATUS_PRESSED:
 986                         //The key is pressed.
 987                         break;
 988
 989                 case UTILX_KEY_STATUS_RELEASED:
 990                         //The key is released.
 991                         break;
 992
 993                 case UTILX_KEY_STATUS_UNKNOWN:
 994                 default:
 995                         //The key status is unknown;
 996                         break;
 997         }
 998
 999         return 0;
1000   }
1001
1002   @endcode
1003    * @par Example (using EFL APIs)
1004   @code
1005
1006   #include <utilX.h>
1007   #include <Ecore_Evas.h>
1008   #include <Ecore_X.h>
1009
1010   int main()
1011   {
1012         ...
1013
1014         Ecore_X_Display* disp = ecore_x_display_get();
1015         Utilx_Key_Status status;
1016
1017         status = utilx_get_key_status(disp, KEY_PLAYCD);
1018
1019         switch( status )
1020         {
1021                 case UTILX_KEY_STATUS_PRESSED:
1022                         //The key is pressed.
1023                         break;
1024
1025                 case UTILX_KEY_STATUS_RELEASED:
1026                         //The key is released.
1027                         break;
1028
1029                 case UTILX_KEY_STATUS_UNKNOWN:
1030                 default:
1031                         //The key status is unknown;
1032                         break;
1033         }
1034         return 0;
1035   }
1036   @endcode
1037  */
1038 Utilx_Key_Status utilx_get_key_status(Display* dpy, char *key_name);
1039
1040 /* Window Effect APIs */
1041 /**
1042  * @fn void utilx_set_window_effect_state(Display* dpy, Window win, int state)
1043  * @brief Sets a window's effect state ( enable or disable )
1044  *
1045  * This function sets window's effect state. if effect is not enabled by composite manager, \n
1046  * window's effect could not be enabled.
1047  *
1048  * This function is a asynchronous call.
1049  *
1050  * @param[in] dpy Specifies the connection to the X server
1051  * @param[in] win Specifies the window handle
1052  * @param[in] state Enables/disables the window effect
1053  * @remark This is used only client window. ( not root window )
1054  * @pre This api must be called before fist show ( XMapWindow Event ).
1055  * @post This changes Client Window's Effect related property.
1056  * @see utilx_get_window_effect_state
1057  * @par Example
1058   @code
1059   #include <X11/Xlib.h>
1060   #include <utilX.h>
1061   ...
1062
1063   Display* dpy;
1064   Window root, win;
1065
1066   dpy = XOpenDisplay (NULL);
1067   root = XDefaultRootWindow (dpy);
1068
1069   win = XCreateSimpleWindow (dpy, root, 0, 0, 480, 800, 2, BlackPixel (dpy,0), WhitePixel(dpy,0));
1070
1071   // Sets a window's effect state to enable ( enable : 1, disable 0 )
1072   utilx_set_window_effect_state(dpy, win, 1);
1073
1074   XMapWindow (dpy, win);
1075   ...
1076   @endcode
1077  */
1078 void utilx_set_window_effect_state(Display* dpy, Window win, int state);
1079
1080 /**
1081 * @fn int utilx_get_window_effect_state(Display* dpy, Window win)
1082 * @brief Gets a window's effect state ( enable or disable )
1083 *
1084 * This function returns windows's effect state.\n
1085 * If effect is not enabled by composite manager, then this return value is unusable or meanless.
1086 *
1087 * This function is a asynchronous call.
1088 *
1089 * @param[in] dpy Specifies the connection to the X server
1090 * @param[in] win Specifies the window handle
1091 * @return Current window effect state
1092 * @remark This is used only client window. ( not root window )
1093 * @pre This api does not require any pre-condition.
1094 * @post This api does not change any condition.
1095 * @see utilx_set_window_effect_state
1096 * @par Example
1097  @code
1098  #include <X11/Xlib.h>
1099  #include <utilX.h>
1100  ...
1101
1102  Display* dpy;
1103  Window root, win;
1104
1105  dpy = XOpenDisplay (NULL);
1106  root = XDefaultRootWindow (dpy);
1107
1108  win = XCreateSimpleWindow (dpy, root, 0, 0, 480, 800, 2, BlackPixel (dpy,0), WhitePixel(dpy,0));
1109
1110  XMapWindow (dpy, win);
1111
1112  // Gets a window's effect state ( enable : 1, disable 0 )
1113  printf( "current window's effect state = %d\n", utilx_get_window_effect_state(dpy, win) ) ;
1114  ...
1115  @endcode
1116 */
1117 int utilx_get_window_effect_state(Display* dpy, Window win);
1118
1119 /**
1120  * @fn void utilx_show_fake_effect(Display* dpy, Window win, char *fake_image_file)
1121  * @brief Shows a window's "fake show effect" animation
1122  *
1123  * This function show's application fake show image.\n
1124  * This function is only used by application launching program.
1125  *
1126  * This function is a asynchronous call.
1127  *
1128  * @param[in] dpy Specifies the connection to the X server
1129  * @param[in] win Specifies the root window handle
1130  * @param[in] fake_image_file Specifies the fake window image and file format is png type.
1131  * @remark This is used only menu-screen window.
1132  * @pre  This api must be called before client's fist show ( XMapWindow Event ). you must call this api then run application.
1133  * @post This changes root window's fake effect related property.
1134  * @see utilx_hide_fake_effect
1135  * @par Example
1136   @code
1137   #include <X11/Xlib.h>
1138   #include <utilX.h>
1139   ...
1140
1141   Display* dpy;
1142   Window root;
1143
1144   dpy = XOpenDisplay (NULL);
1145   root = XDefaultRootWindow (dpy);
1146
1147   // Shows a window's "fake show effect" animation, and if you want to see animation, /root/fake_window_image.png file must be exited.
1148   utilx_show_fake_effect( dpy, root, "/root/fake_window_image.png");
1149    ...
1150   @endcode
1151  */
1152 void utilx_show_fake_effect(Display *dpy, Window win, char *fake_image_file);
1153
1154 /**
1155  * @fn void utilx_hide_fake_effect(Display* dpy, Window win)
1156  * @brief Shows a window's "fake hide effect" animation, and this animation uses "fake show effect" 's window image.
1157  *
1158  * This function shoes a window's fake hide effect.\n
1159  * This function is only used by application launching program.\n
1160  * When application was not executed by any error.
1161  *
1162  * This function is a asynchronous call.
1163  *
1164  * @param[in] dpy Specifies the connection to the X server
1165  * @param[in] win Specifies the root window handle
1166  * @remark This is used only menu-screen window.
1167  * @pre This api must be called after "utilx_show_fake_effect()".
1168  * @post This changes root window's fake effect related property.
1169  * @see utilx_show_fake_effect
1170  * @par Example
1171   @code
1172   #include <X11/Xlib.h>
1173   #include <utilX.h>
1174   ...
1175
1176   Display* dpy;
1177   Window root;
1178
1179   dpy = XOpenDisplay (NULL);
1180   root = XDefaultRootWindow (dpy);
1181
1182   // Shows a window's "fake hide effect" animation. and if you wnat to see animation, utilx_show_fake_effect() function must be excuted before utilx_show_fake_effect()
1183   // and if real window is showed , then fake hide effect could not be showed.
1184   utilx_hide_fake_effect( dpy, root );
1185    ...
1186   @endcode
1187  */
1188 void utilx_hide_fake_effect(Display *dpy, Window win);
1189
1190 /**
1191  * @fn void utilx_set_window_effect_style(Display* dpy, Window win, Utilx_Effect_Type type, Utilx_Effect_Style style)
1192  * @brief Sets a window's effect style with effect type.
1193  *
1194  * This function sets a window's effect style with effect type.\n
1195  * Default Window Effect is setted by Window Type and Window Class.\n
1196  * And then, you could change custom effecct.\n
1197  * Custom Effect is available max 10. ( CUSTOM0 ~ CUSTOM9 )\n
1198  * If you didn't set custom effect, then compositing window manger provides Default Window Effect.\n
1199  *
1200  * This function is a asynchronous call.
1201  *
1202  * @param[in] dpy Specifies the connection to the X server
1203  * @param[in] win Specifies the window handle
1204  * @param[in] type Specifies the window's effect type ( ex. UTILX_EFFECT_TYPE_MAP, UTILX_EFFECT_TYPE_UNMAP, etc )
1205  * @param[in] style Specifies  the window's effect style ( ex. UTILX_EFFECT_STYLE_DEFAULT, UTILX_EFFECT_STYLE_NONE, UTILX_EFFECT_STYLE_CUSTOM0, etc )
1206  * @remark This is used only client window. ( not root window )
1207  * @pre This api does not require any pre-condition.
1208  * @post This changes window's effect type related property ( _NET_CM_WINDOW_EFFECT_TYPE  ).
1209  * @see utilx_get_window_effect_style
1210  * @par Example
1211   @code
1212   #include <X11/Xlib.h>
1213   #include <X11/Xutil.h>
1214   #include <utilX.h>
1215   ...
1216
1217   Display *dpy ;
1218   Window win, root ;
1219   unsigned long black, white;
1220
1221   dpy = XOpenDisplay(NULL) ;
1222
1223   black = BlackPixel(dpy, 0);
1224   white = WhitePixel(dpy, 0);
1225
1226   root = XDefaultRootWindow (dpy);
1227   win = XCreateSimpleWindow ( dpy, root, 0, 0, 100, 100, 2, BlackPixel (d,0), WhitePixel(d,0) );
1228
1229   utilx_set_window_effect_style(dpy, win, UTILX_EFFECT_TYPE_MAP, UTILX_EFFECT_STYLE_CUSTOM0); //  window's show effet type change to UTILX_EFFECT_STYLE_CUSTOM0
1230
1231   XMapWindow(dpy, win);
1232
1233   ...
1234
1235   utilx_set_window_effect_style(dpy, win, UTILX_EFFECT_TYPE_UNMAP, UTILX_EFFECT_STYLE_CUSTOM0); // window's hide effet type change to UTILX_EFFECT_STYLE_CUSTOM0
1236
1237   XUnmapWindow (dpy, win);
1238
1239   utilx_set_window_effect_style(dpy, win, UTILX_EFFECT_TYPE_MAP, UTILX_EFFECT_STYLE_DEFAULT); // window's show effet type change to UTILX_EFFECT_STYLE_DEFAULT
1240   XMapWindow (dpy, win);
1241
1242   ...
1243
1244   utilx_set_window_effect_style(dpy, win, UTILX_EFFECT_TYPE_UNMAP, UTILX_EFFECT_STYLE_DEFAULT); // window's hide effet type change to UTILX_EFFECT_STYLE_DEFAULT
1245   XUnmapWindow (dpy, win);
1246
1247   ...
1248
1249   utilx_set_window_effect_style(dpy, win, UTILX_EFFECT_TYPE_MAP, UTILX_EFFECT_STYLE_NONE); // window's show effet type change to UTILX_EFFECT_STYLE_NONE
1250   XMapWindow (dpy, win);
1251
1252   ...
1253
1254   utilx_set_window_effect_style(dpy, win, UTILX_EFFECT_TYPE_UNMAP, UTILX_EFFECT_STYLE_NONE); // window's hide effet type change to UTILX_EFFECT_STYLE_NONE
1255   XUnmapWindow (dpy, win);
1256
1257   ...
1258   @endcode
1259  */
1260 void utilx_set_window_effect_style(Display* dpy, Window win, Utilx_Effect_Type type, Utilx_Effect_Style style);
1261
1262 /**
1263  * @fn Utilx_Effect_Style utilx_get_window_effect_style(Display* dpy, Window win, Utilx_Effect_Type type)
1264  * @brief Gets a window's effect style with effect type.
1265  *
1266  * This function gets a window's effect style with effect type.\n
1267  *
1268  * This function is a asynchronous call.
1269  *
1270  * @param[in] dpy Specifies the connection to the X server
1271  * @param[in] win Specifies the window handle
1272  * @param[in] type Specifies the window's effect type ( ex. UTILX_EFFECT_TYPE_MAP, UTILX_EFFECT_TYPE_UNMAP, etc )
1273  * @return Current window's effect style ( ex. UTILX_EFFECT_STYLE_DEFAULT, UTILX_EFFECT_STYLE_NONE, UTILX_EFFECT_STYLE_CUSTOM0, etc )
1274  * @remark This is used only client window. ( not root window )
1275  * @pre This api does not require any pre-condition.
1276  * @post This api does not change any condition.
1277  * @see utilx_set_window_effect_style
1278  * @par Example
1279   @code
1280   #include <X11/Xlib.h>
1281   #include <X11/Xutil.h>
1282   #include <utilX.h>
1283   ...
1284
1285   Display *dpy ;
1286   Window win, root ;
1287   unsigned long black, white;
1288   Utilx_Effect_Style style;
1289
1290   dpy = XOpenDisplay(NULL) ;
1291
1292   black = BlackPixel(dpy, 0);
1293   white = WhitePixel(dpy, 0);
1294
1295   root = XDefaultRootWindow (dpy);
1296   win = XCreateSimpleWindow ( dpy, root, 0, 0, 100, 100, 2, BlackPixel (d,0), WhitePixel(d,0) );
1297
1298   style = utilx_set_window_effect_style(dpy, win, UTILX_EFFECT_TYPE_MAP); //  get effect style with window's show effet type
1299
1300   ...
1301
1302   style = utilx_set_window_effect_style(dpy, win, UTILX_EFFECT_TYPE_UNMAP); //  get effect style with window's show effet type
1303
1304   ...
1305   @endcode
1306  */
1307 Utilx_Effect_Style utilx_get_window_effect_style(Display* dpy, Window win, Utilx_Effect_Type type);
1308
1309 /**
1310  * @fn void utilx_set_window_opaque_state (Display* dpy, Window win, int opaque)
1311  * @brief Sets the window's opaque state
1312  *
1313  * This function sets window's visibility to opaque even if the window is an alpha window.
1314  * This function is available only alpha window.
1315  * An alpha window's default opaque state is UTILX_OPAQUE_STATE_OFF.
1316  *
1317  * This function is a asynchronous call.
1318  *
1319  * @param[in] dpy Specifies the connection to the X server
1320  * @param[in] win Specifies the window handle
1321  * @param[in] state Specifies whether the window set a visible state to opaque(UTILX_OPAQUE_STATE_ON) or not(UTILX_OPAQUE_STATE_OFF)
1322  * @return 1 on Success, otherwise Fail
1323  * @remark This is used only alpha window.
1324  * @pre None
1325  * @post
1326  * @see
1327  * @par Example
1328   @code
1329   #include <X11/Xlib.h>
1330   #include <utilX.h>
1331
1332   ...
1333
1334   Display* dpy;
1335   Window root, win;
1336   int ret;
1337
1338   dpy = XOpenDisplay (NULL);
1339   root = XDefaultRootWindow (dpy);
1340
1341   win = XCreateSimpleWindow (dpy, root, 0, 0, 480, 800, 2, BlackPixel (dpy,0), WhitePixel(dpy,0));
1342   XMapWindow (dpy, win);
1343
1344   ret = utilx_set_window_opaque_state (dpy, win, UTILX_OPAQUE_STATE_ON);
1345   if (!ret)
1346   {
1347     printf ("Error! Failed to set opaque state.\n");
1348   }
1349
1350   XFlush (dpy);
1351
1352   ...
1353   @endcode
1354  */
1355 int utilx_set_window_opaque_state (Display* dpy, Window win, Utilx_Opaque_State state);
1356
1357 /**
1358  * @fn int utilx_set_screen_capture(Display* dpy, int enable)
1359  * @brief Specifies whether the screen capture functionality is enable or not.
1360  *
1361  * This function makes the screen capture functionality of CBHM enable or disable.
1362  * CBHM = Clipboard History Manager.
1363  *
1364  * This function is synchronous.
1365  *
1366  * @param[in] dpy    Specifies the connection to the X server
1367  * @param[in] enable Specifies the window handle. (1:Enable, 0:Disable)
1368  * @pre This api does not require any pre-condition.
1369  * @post This api does not change any condition.
1370  * @see utilx_get_screen_capture
1371  * @par Example
1372   @code
1373   #include <X11/Xlib.h>
1374   #include <X11/Xutil.h>
1375   #include <utilX.h>
1376   ...
1377
1378   Display *dpy ;
1379
1380   dpy = XOpenDisplay(NULL) ;
1381
1382   utilx_set_screen_capture (dpy, 1);
1383
1384   ...
1385   @endcode
1386  */
1387 int utilx_set_screen_capture(Display* dpy, int enable);
1388
1389 /**
1390  * @fn int utilx_get_screen_capture(Display* dpy, int enable)
1391  * @brief Gets whether the screen capture functionality is enable or not.
1392  *
1393  * This function gets whether the screen capture functionality of CBHM is enable or not.
1394  * CBHM = Clipboard History Manager.
1395  *
1396  * This function is synchronous.
1397  *
1398  * @param[in] dpy    Specifies the connection to the X server
1399  * @pre This api does not require any pre-condition.
1400  * @post This api does not change any condition.
1401  * @see utilx_set_screen_capture
1402  * @par Example
1403   @code
1404   #include <X11/Xlib.h>
1405   #include <X11/Xutil.h>
1406   #include <utilX.h>
1407   ...
1408
1409   Display *dpy ;
1410   int enable;
1411
1412   dpy = XOpenDisplay(NULL) ;
1413
1414   enable = utilx_set_screen_capture (dpy);
1415
1416   ...
1417   @endcode
1418  */
1419 int utilx_get_screen_capture(Display* dpy);
1420
1421 /**
1422  * @fn void utilx_set_window_cardinal_property(Display* dpy, Window win, Atom atom, unsigned int *value)
1423  * @brief Sets the cardinal property to Window
1424  *
1425  * This function Sets the cardinal property to Window.
1426  *
1427  * This function is synchronous.
1428  *
1429  * @param[in] dpy    Specifies the connection to the X server
1430  * @param[in] win    Specifies the window handle
1431  * @param[in] atom   Specifies the atom of cardinal property
1432  * @param[in] value  the value of cardinal property to set.
1433  * @pre This api does not require any pre-condition.
1434  * @post This api does not change any condition.
1435  * @see utilx_get_window_cardinal_property
1436  * @par Example
1437   @code
1438   #include <X11/Xlib.h>
1439   #include <X11/Xutil.h>
1440   #include <utilX.h>
1441   ...
1442
1443   Display *dpy ;
1444   Window root;
1445   Atom atom = None;
1446   int value = 1;
1447
1448   dpy = XOpenDisplay (NULL);
1449   root = XDefaultRootWindow (dpy);
1450
1451   atom = XInternAtom(dpy, "TEST_ATOM", False);
1452
1453   utilx_set_window_cardinal_property (dpy, root, atom, (unsigned int*)&value);
1454
1455   ...
1456   @endcode
1457  */
1458 void utilx_set_window_cardinal_property(Display* dpy, Window win, Atom atom, unsigned int *value);
1459
1460 /**
1461  * @fn int utilx_get_window_cardinal_property(Display* dpy, Window win, Atom atom, unsigned int *value)
1462  * @brief Gets the value of cardinal property.
1463  *
1464  * This function gets the value of cardinal property.
1465  *
1466  * This function is synchronous.
1467  *
1468  * @param[in] dpy    Specifies the connection to the X server
1469  * @param[in] win    Specifies the window handle
1470  * @param[in] atom   Specifies the atom of cardinal property
1471  * @param[out] value  the value of cardinal property to get.
1472  * @pre This api does not require any pre-condition.
1473  * @post This api does not change any condition.
1474  * @see utilx_set_window_cardinal_property
1475  * @par Example
1476   @code
1477   #include <X11/Xlib.h>
1478   #include <X11/Xutil.h>
1479   #include <utilX.h>
1480   ...
1481
1482   Display *dpy ;
1483   Window root;
1484   Atom atom = None;
1485   int value;
1486
1487   dpy = XOpenDisplay (NULL);
1488   root = XDefaultRootWindow (dpy);
1489
1490   atom = XInternAtom(dpy, "TEST_ATOM", False);
1491
1492   if (utilx_set_window_cardinal_property (dpy, root, atom, (unsigned int*)&value) > 0)
1493   {
1494     success;
1495   }
1496
1497   ...
1498   @endcode
1499  */
1500 int utilx_get_window_cardinal_property(Display* dpy, Window win, Atom atom, unsigned int *value);
1501
1502 /**
1503  * @fn void utilx_show_capture_effect(Display *dpy, Window win )
1504  * @brief Shows a capture effect animation
1505  *
1506  * This function show capture effect animation.\n
1507  * This function is only used by Screen Capture Application.
1508  *
1509  * This function is a asynchronous call.
1510  *
1511  * @param[in] dpy Specifies the connection to the X server
1512  * @param[in] win Specifies the root window handle
1513  * @remark This is used only screen capture application.
1514  * @pre  This api does not require any pre-condition.
1515  * @post This api does not change any condition.
1516  * @see utilx_set_screen_capture
1517  * @par Example
1518   @code
1519   #include <X11/Xlib.h>
1520   #include <utilX.h>
1521   ...
1522
1523   Display* dpy;
1524   Window root;
1525
1526   dpy = XOpenDisplay (NULL);
1527   root = XDefaultRootWindow (dpy);
1528
1529   // Shows a  Shows a capture effect animation
1530   utilx_show_capture_effect( dpy, root);
1531    ...
1532   @endcode
1533  */
1534 void utilx_show_capture_effect(Display *dpy, Window win );
1535
1536 /**
1537  * @fn void* utilx_create_screen_shot (Display* dpy, int width, int height)
1538  * @brief Create a screenshot image.
1539  *
1540  * This function create a screenshot image.\n
1541  * To use this function, you should get the permission first. Once this functions
1542  * is called, utilx_release_screen_shot should be called after it.
1543  *
1544  * @param[in] dpy Specifies the connection to the X server
1545  * @param[in] width Specifies the root window handle
1546  * @param[in] height Specifies the root window handle
1547  * @remark You should get the permission to use.
1548  * @post This api does not change any condition.
1549  * @see utilx_release_screen_shot
1550  * @par Example
1551   @code
1552     Display* dpy;
1553     int width, height;
1554     void *dump;
1555
1556     dpy = XOpenDisplay (NULL);
1557     width = DisplayWidth (dpy, DefaultScreen (dpy));
1558     height = DisplayHeight (dpy, DefaultScreen (dpy));
1559
1560     dump = utilx_create_screen_shot (dpy, width, height);
1561     if (dump)
1562     {
1563         // do_something (dump);
1564     }
1565     else
1566     {
1567         // utilx_create_screen_shot can return NULL in some cases.
1568         // Even if it returns NULL, utilx_release_screen_shot should be called.
1569     }
1570
1571     utilx_release_screen_shot ();
1572   @endcode
1573  */
1574 void* utilx_create_screen_shot (Display* dpy, int width, int height);
1575
1576 /**
1577  * @fn void  utilx_release_screen_shot (void)
1578  * @brief Release screenshot resources.
1579  *
1580  * This function release screenshot resources.\n
1581  * utilx_release_screen_shot should be called once utilx_create_screen_shot is
1582  * called.
1583  *
1584  * @see utilx_create_screen_shot
1585  * @par Example
1586   @code
1587     Display* dpy;
1588     int width, height;
1589     void *dump;
1590
1591     dpy = XOpenDisplay (NULL);
1592     width = DisplayWidth (dpy, DefaultScreen (dpy));
1593     height = DisplayHeight (dpy, DefaultScreen (dpy));
1594
1595     dump = utilx_create_screen_shot (dpy, width, height);
1596     if (dump)
1597     {
1598         // do_something (dump);
1599     }
1600     else
1601     {
1602         // utilx_create_screen_shot can return NULL in some cases.
1603         // Even if it returns NULL, utilx_release_screen_shot should be called.
1604     }
1605
1606     utilx_release_screen_shot ();
1607   @endcode
1608  */
1609 void  utilx_release_screen_shot (void);
1610
1611 /**
1612  * @fn void  utilx_set_fb_visible (Display* dpy, Utilx_Fb_Type fb_type, Bool visible)
1613  * @brief Set fb's visibility.
1614  *
1615  * This function can make a framebuffer visible or non-visible. \n
1616  * By the way, in case of UTILX_FB_TYPE_UI, if there is the request for UI update,
1617  * the visibility of UI framebuffer will be changed from False to True automatically.
1618  * Please note this.
1619  *
1620  * @param[in] dpy      Specifies the connection to the X server
1621  * @param[in] fb_type  Specifies the fb type to set visibility of a framebuffer
1622  * @param[in] visible  Visible/Non-Visible
1623  * @see utilx_get_fb_visible
1624  * @par Example
1625   @code
1626   #include <utilX.h>
1627   ...
1628   Display* dpy = XOpenDisplay (NULL);
1629
1630   // Hide the UI framebuffer of main lcd.
1631   utilx_set_fb_visible (dpy, UTILX_FB_TYPE_UI, False);
1632   ...
1633   @endcode
1634  */
1635 void  utilx_set_fb_visible (Display* dpy, Utilx_Fb_Type fb_type, Bool visible);
1636
1637 /**
1638  * @fn Bool  utilx_get_fb_visible (Display* dpy, Utilx_Fb_Type fb_type)
1639  * @brief Get framebuffer's visibility.
1640  *
1641  * This function get the visibility of a framebuffer. \n
1642  *
1643  * @param[in] dpy       Specifies the connection to the X server
1644  * @param[in] fb_type   Specifies the fb type to get visibility of a framebuffer
1645  * @return Current visibility of a framebuffer
1646  * @see utilx_set_fb_visible
1647  * @par Example
1648   @code
1649   #include <utilX.h>
1650   ...
1651   Display* dpy = XOpenDisplay (NULL);
1652   Bool visible;
1653
1654   visible = utilx_get_fb_visible (dpy, UTILX_FB_TYPE_UI);
1655   ...
1656   @endcode
1657  */
1658 Bool  utilx_get_fb_visible (Display* dpy, Utilx_Fb_Type fb_type);
1659
1660 /**
1661  * @fn void  utilx_set_video_offset (Display* dpy, int x, int y)
1662  * @brief Set the offset of video.
1663  *
1664  * This function sets the offset of video layer. \n
1665  *
1666  * @param[in] dpy   Specifies the connection to the X server
1667  * @param[in] x     x offset
1668  * @param[in] y     y offset
1669  * @par Example
1670   @code
1671   #include <utilX.h>
1672   ...
1673   Display* dpy = XOpenDisplay (NULL);
1674
1675   utilx_set_video_offset (dpy, 0, 100);
1676   ...
1677   @endcode
1678  */
1679 void  utilx_set_video_offset (Display* dpy, int x, int y);
1680
1681 #ifdef __cplusplus
1682 }
1683 #endif
1684
1685
1686 /**
1687  * @}
1688  */
1689
1690 #endif /* __SAMSUNG_LINUX_UTIL_X11_H__ */
1691