utilX.h

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