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