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 __TIZEN_LINUX_UTIL_X11_H__
  21 #define __TIZEN_LINUX_UTIL_X11_H__
  22
  23 #ifdef __GNUC__
  24 #define DEPRECATED __attribute__((deprecated))
  25 #else
  26 #define DEPRECATED
  27 #endif
  28
  29 /**
  30 * @internal
  31 * @addtogroup CAPI_UI_UTILX_MODULE
  32 * @{
  33 */
  34
  35 #include <sys/types.h>
  36 #include <X11/X.h>
  37 #include <X11/Xlib.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /**
  44 * @internal
  45  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Volume Up' key.
  46  */
  47 #define KEY_VOLUMEUP            "XF86AudioRaiseVolume"
  48 /**
  49  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Volume Down' key.
  50  */
  51 #define KEY_VOLUMEDOWN          "XF86AudioLowerVolume"
  52 /**
  53  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Half-Press of Camera' key.
  54  */
  55 #define KEY_CAMERA              "XF86WebCam"
  56 /**
  57  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Full-Press of Camera' key.
  58  */
  59 #define KEY_CONFIG              "XF86Pictures"
  60
  61 /**
  62  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Power' key.
  63  */
  64 #define KEY_POWER               "XF86PowerOff"
  65 /**
  66  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Pause' key.
  67  */
  68 #define KEY_PAUSE               "XF86Standby"
  69 /**
  70  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Cancel' key.
  71  */
  72 #define KEY_CANCEL              "Cancel"
  73
  74 // Earjack/BT Headset/Multimedia keys
  75 /**
  76  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Play Audio' key.
  77  */
  78 #define KEY_PLAYCD              "XF86AudioPlay"
  79 /**
  80  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Stop Audio' key.
  81  */
  82 #define KEY_STOPCD              "XF86AudioStop"
  83 /**
  84  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Pause Audio' key.
  85  */
  86 #define KEY_PAUSECD             "XF86AudioPause"
  87 /**
  88  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Next Song' key.
  89  */
  90 #define KEY_NEXTSONG            "XF86AudioNext"
  91 /**
  92  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Previous Song' key.
  93  */
  94 #define KEY_PREVIOUSSONG        "XF86AudioPrev"
  95 /**
  96  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Rewind Song' key.
  97  */
  98 #define KEY_REWIND              "XF86AudioRewind"
  99 /**
 100  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Forward Song' key.
 101  */
 102 #define KEY_FASTFORWARD         "XF86AudioForward"
 103 /**
 104  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Media' key.
 105  */
 106 #define KEY_MEDIA               "XF86AudioMedia"
 107 /**
 108  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'PlayPause' key.
 109  */
 110 #define KEY_PLAYPAUSE           "XF86AudioPlayPause"
 111 /**
 112  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Mute' key.
 113  */
 114 #define KEY_MUTE                        "XF86AudioMute"
 115
 116 // 3-Touch key
 117 /**
 118  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Send' key.
 119  */
 120 #define KEY_SEND                "XF86Send"
 121 /**
 122  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Home' key.
 123  */
 124 #define KEY_SELECT              "XF86Phone"
 125 /**
 126  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'End' key.
 127  */
 128 #define KEY_END                 "XF86Stop"
 129
 130 // Renamed 3-Touch key
 131 /**
 132  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Send' key.
 133  */
 134 #define KEY_MENU                "XF86Send"
 135 /**
 136  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Home' key.
 137  */
 138 #define KEY_HOME                "XF86Phone"
 139 /**
 140  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'End' key.
 141  */
 142 #define KEY_BACK                "XF86Stop"
 143
 144 //Other functions keys
 145 /**
 146  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'HomePage' key.
 147  */
 148 #define KEY_HOMEPAGE            "XF86HomePage"
 149 /**
 150  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'WWW' key.
 151  */
 152 #define KEY_WEBPAGE             "XF86WWW"
 153 /**
 154  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Mail' key.
 155  */
 156 #define KEY_MAIL                        "XF86Mail"
 157 /**
 158  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'ScreenSaver' key.
 159  */
 160 #define KEY_SCREENSAVER "XF86ScreenSaver"
 161 /**
 162  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'BrightnessUp' key.
 163  */
 164 #define KEY_BRIGHTNESSUP        "XF86MonBrightnessUp"
 165 /**
 166  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'BrightnessDown' key.
 167  */
 168 #define KEY_BRIGHTNESSDOWN      "XF86MonBrightnessDown"
 169 /**
 170  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Soft keyboard(toggle)' key.
 171  */
 172 #define KEY_SOFTKBD                     "XF86MenuKB"
 173 /**
 174  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Quick panel(toggle)' key.
 175  */
 176 #define KEY_QUICKPANEL          "XF86Tools"
 177 /**
 178  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Task switcher(toggle)' key.
 179  */
 180 #define KEY_TASKSWITCH          "XF86TaskPane"
 181 /**
 182  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Apptray(toggle)' key.
 183  */
 184 #define KEY_APPS                "XF86Launch0"
 185 /**
 186  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Search(toggle)' key.
 187  */
 188 #define KEY_SEARCH              "XF86Search"
 189 /**
 190  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Voice(toggle)' key.
 191  */
 192 #define KEY_VOICE               "XF86Launch2"
 193 /**
 194  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Language(toggle)' key.
 195  */
 196 #define KEY_LANGUAGE            "Hangul"
 197 /**
 198  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Call(toggle)' key.
 199  */
 200 #define KEY_CONNECT                     "XF86Go"
 201 /**
 202  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Play(toggle)' key.
 203  */
 204 #define KEY_GAMEPLAY            "XF86Game"
 205 /**
 206  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Voice Wakeup LPSD' key.
 207  */
 208 #define KEY_VOICEWAKEUP_LPSD            "XF86Launch3"
 209 /**
 210  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Voice Wakeup' key.
 211  */
 212 #define KEY_VOICEWAKEUP         "XF86Launch4"
 213
 214 /**
 215  * @brief Definition for the length of a string corresponding to the 'Volume Up' key.
 216  */
 217 #define LEN_KEY_VOLUMEUP                20
 218 /**
 219  * @brief Definition for the length of a string corresponding to the 'Volume Down' key.
 220  */
 221 #define LEN_KEY_VOLUMEDOWN      20
 222
 223 /**
 224  * @brief Definition for the length of a string corresponding to the 'Half-Press of Camera' key.
 225  */
 226 #define LEN_KEY_CAMERA          10
 227 /**
 228  * @brief Definition for the length of a string corresponding to the 'Full-Press of Camera' key.
 229  */
 230 #define LEN_KEY_CONFIG          12
 231
 232 /**
 233  * @brief Definition for the length of a string corresponding to the 'Power' key.
 234  */
 235 #define LEN_KEY_POWER           12
 236 /**
 237  * @brief Definition for the length of a string corresponding to the 'Pause' key.
 238  */
 239 #define LEN_KEY_PAUSE           11
 240
 241 // Earjack/BT Headset/Multimedia keys
 242 /**
 243  * @brief Definition for the length of a string corresponding to the 'Play Audio' key.
 244  */
 245 #define LEN_KEY_PLAYCD          13
 246 /**
 247  * @brief Definition for the length of a string corresponding to the 'Stop Audio' key.
 248  */
 249 #define LEN_KEY_STOPCD          13
 250 /**
 251  * @brief Definition for the length of a string corresponding to the 'Pause Audio' key.
 252  */
 253 #define LEN_KEY_PAUSECD         14
 254 /**
 255  * @brief Definition for the length of a string corresponding to the 'Next Song' key.
 256  */
 257 #define LEN_KEY_NEXTSONG        13
 258 /**
 259  * @brief Definition for the length of a string corresponding to the 'Previous Song' key.
 260  */
 261 #define LEN_KEY_PREVIOUSSONG            13
 262 /**
 263  * @brief Definition for the length of a string corresponding to the 'Rewind Song' key.
 264  */
 265 #define LEN_KEY_REWIND          15
 266 /**
 267  * @brief Definition for the length of a string corresponding to the 'Forwand Song' key.
 268  */
 269 #define LEN_KEY_FASTFORWARD             16
 270 /**
 271  * @brief Definition for the length of a string corresponding to the 'Media' key.
 272  */
 273 #define LEN_KEY_MEDIA           14
 274 /**
 275  * @brief Definition for the length of a string corresponding to the 'PlayPause' key.
 276  */
 277 #define LEN_KEY_PLAYPAUSE       13
 278 /**
 279  * @brief Definition for the length of a string corresponding to the 'Mute' key.
 280  */
 281 #define LEN_KEY_MUTE            13
 282
 283 // 3-Touch key
 284 /**
 285  * @brief Definition for the length of a string corresponding to the 'Send' key.
 286  */
 287 #define LEN_KEY_SEND            8
 288 /**
 289  * @brief Definition for the length of a string corresponding to the 'Home' key.
 290  */
 291 #define LEN_KEY_SELECT          9
 292 /**
 293  * @brief Definition for the length of a string corresponding to the 'End' key.
 294  */
 295 #define LEN_KEY_END             8
 296
 297 // Renamed 3-Touch key
 298 /**
 299  * @brief Definition for the length of a string corresponding to the 'Send' key.
 300  */
 301 #define LEN_KEY_MENU            8
 302 /**
 303  * @brief Definition for the length of a string corresponding to the 'Home' key.
 304  */
 305 #define LEN_KEY_HOME            9
 306 /**
 307  * @brief Definition for the length of a string corresponding to the 'End' key.
 308  */
 309 #define LEN_KEY_BACK            8
 310
 311 //Other functions keys
 312 /**
 313  * @brief Definition for the length of a string corresponding to the 'HomePage' key.
 314  */
 315 #define LEN_KEY_HOMEPAGE        12
 316 /**
 317  * @brief Definition for the length of a string corresponding to the 'WWW' key.
 318  */
 319 #define LEN_KEY_WEBPAGE 7
 320 /**
 321  * @brief Definition for the length of a string corresponding to the 'Mail' key.
 322  */
 323 #define LEN_KEY_MAIL            8
 324 /**
 325  * @brief Definition for the length of a string corresponding to the 'ScreenSaver' key.
 326  */
 327 #define LEN_KEY_SCREENSAVER     15
 328 /**
 329  * @brief Definition for the length of a string corresponding to the 'BrightnessUp' key.
 330  */
 331 #define LEN_KEY_BRIGHTNESSUP    19
 332 /**
 333  * @brief Definition for the length of a string corresponding to the 'BrightnessDown' key.
 334  */
 335 #define LEN_KEY_BRIGHTNESSDOWN  21
 336 /**
 337  * @brief Definition for the length of a string corresponding to the 'Soft keyboard(toggle)' key.
 338  */
 339 #define LEN_KEY_SOFTKBD         10
 340 /**
 341  * @brief Definition for the length of a string corresponding to the 'Quick panel(toggle)' key.
 342  */
 343 #define LEN_KEY_QUICKPANEL              9
 344 /**
 345  * @brief Definition for the length of a string corresponding to the 'Task switcher(toggle)' key.
 346  */
 347 #define LEN_KEY_TASKSWITCH      12
 348 /**
 349  * @brief Definition for the length of a string corresponding to the 'Apptray(toggle)' key.
 350  */
 351 #define LEN_KEY_APPS                    11
 352 /**
 353  * @brief Definition for the length of a string corresponding to the 'Search(toggle)' key.
 354  */
 355 #define LEN_KEY_SEARCH                  10
 356 /**
 357  * @brief Definition for the length of a string corresponding to the 'Voice(toggle)' key.
 358  */
 359 #define LEN_KEY_VOICE                   11
 360 /**
 361  * @brief Definition for the length of a string corresponding to the 'Language(toggle)' key.
 362  */
 363 #define LEN_KEY_LANGUAGE                6
 364 /**
 365  * @brief Definition for the length of a string corresponding to the 'Call(toggle)' key.
 366  */
 367 #define LEN_KEY_CONNECT                 6
 368 /**
 369  * @brief Definition for the length of a string corresponding to the 'Play(toggle)' key.
 370  */
 371 #define LEN_KEY_GAMEPLAY                8
 372 /**
 373  * @brief Definition for the length of a string corresponding to the 'Voice Wakeup LPSD' key.
 374  */
 375 #define LEN_KEY_VOICEWAKEUP_LPSD        11
 376 /**
 377  * @brief Definition for the length of a string corresponding to the 'Voice Wakeup' key.
 378  */
 379 #define LEN_KEY_VOICEWAKEUP                     11
 380
 381 /**
 382  * @brief Definition for getting the grabbed-key exclusively regardless of its position on the window stack with the possibility of overriding the grab by the other client window mode.
 383  */
 384 #define OR_EXCLUSIVE_GRAB       0xf00000
 385 /**
 386  * @brief Definition for getting the grabbed-key exclusively regardless of its position on the window stack mode.
 387  */
 388 #define EXCLUSIVE_GRAB          0x0f0000
 389 /**
 390  * @brief Definition for getting the grabbed-key only when on the top of the grabbing-window stack mode.
 391  */
 392 #define TOP_POSITION_GRAB       0x00f000
 393 /**
 394  * @brief Definition for getting the grabbed-key together with the other client window(s) mode.
 395  */
 396 #define SHARED_GRAB             0x000f00
 397 /**
 398  * @brief Definition for getting the key-grab mode of a client window.
 399  */
 400 #define GRAB_MODE_MASK  0xffff00
 401
 402 /**
 403  * @brief Definition for the client window grabbing the key which is already in the EXCLUSIVE mode.
 404  */
 405 #define EXCLUSIVE_GRABBED_ALREADY       1
 406
 407 /**
 408  * @brief Definition for getting/setting the property while grabbing a key for a window.
 409  */
 410 #define STR_ATOM_GRAB_KEY       "_GRAB_KEY"
 411 /**
 412  * @brief Definition for the key grabbed by a client window in the EXCLUSIVE mode.
 413  */
 414 #define STR_ATOM_GRAB_EXCL_WIN  "_GRAB_EXCL_WIN_KEYCODE"
 415 /**
 416  * @brief Definition for the key grabbed by a client window in the OR_EXCLUSIVE mode.
 417  */
 418 #define STR_ATOM_GRAB_OR_EXCL_WIN       "_GRAB_OR_EXCL_WIN_KEYCODE"
 419
 420 /**
 421  * @brief Enumeration for notification window's priority level.
 422  */
 423 typedef enum _Utilx_Notification_Level
 424 {
 425         UTILX_NOTIFICATION_LEVEL_LOW, /**< Low level notification */
 426         UTILX_NOTIFICATION_LEVEL_NORMAL, /**< Normal level notification*/
 427         UTILX_NOTIFICATION_LEVEL_HIGH /**< High level notification */
 428 } Utilx_Notification_Level;
 429
 430 /**
 431  * @brief Enumeration for the opaque state.
 432  */
 433 typedef enum _Utilx_Opaque_State
 434 {
 435         UTILX_OPAQUE_STATE_OFF = 0, /**< Transparent state */
 436         UTILX_OPAQUE_STATE_ON  = 1, /**< Opaque state */
 437 } Utilx_Opaque_State;
 438
 439 /**
 440  * @brief Sets the priority level for the specified notification window, asynchronously.
 441  *
 442  * @details This function sets the priority level of notification windows.\n
 443  *          Every notification window has a base priority level by the notification window's priority value (default priority is #UTILX_NOTIFICATION_LEVEL_LOW).
 444  *
 445  *          The priority is used for ordering of notification windows.\n
 446  *          The notification window with the priority set to #UTILX_NOTIFICATION_LEVEL_HIGH will be placed at the top of the notification windows.\n
 447  *          If there are notification windows which have same priorities, the last created notification window will be placed on the other window.
 448  *
 449  * @since_tizen 2.3
 450  * @remarks This is used only for notification windows.
 451  * @param[in] dpy The connection to the X server
 452  * @param[in] win The window to set
 453  * @param[in] level The level (#UTILX_NOTIFICATION_LEVEL_LOW, #UTILX_NOTIFICATION_LEVEL_NORMAL, #UTILX_NOTIFICATION_LEVEL_HIGH)
 454  * @pre The window should be a notification type window.
 455  * @see #Utilx_Notification_Level
 456  * @see utilx_get_system_notification_level()
 457  * @par Example
 458   @code
 459   #include <utilX.h>
 460
 461   ...
 462
 463   Evas_Object *win;
 464   Ecore_X_Window xwin;
 465
 466   win = create_mwnd();
 467   xwin = elm_win_xwindow_get(win);
 468
 469   // Set Notification type
 470   ecore_x_netwm_window_type_set (xwin, ECORE_X_WINDOW_TYPE_NOTIFICATION);
 471
 472   // Set Notification's priority
 473   utilx_set_system_notification_level (ecore_x_display_get(), xwin, UTILX_NOTIFICATION_LEVEL_HIGH);
 474
 475   ...
 476   @endcode
 477  */
 478 void utilx_set_system_notification_level (Display* dpy, Window win, Utilx_Notification_Level level);
 479
 480 /**
 481  * @brief Gets the priority level for the specified notification window.
 482  *
 483  * @details This function returns the priority level of notification windows.\n
 484  *          If a user didn't set the notification's priority level, this function returns the default value (#UTILX_NOTIFICATION_LEVEL_LOW).
 485  *
 486  *          This function is a synchronous call.
 487  *
 488  * @since_tizen 2.3
 489  * @remarks This is used only for notification windows.
 490  * @param[in] dpy The connection to the X server
 491  * @param[in] win The window to get
 492  * @return The current notification level (#UTILX_NOTIFICATION_LEVEL_LOW, #UTILX_NOTIFICATION_LEVEL_NORMAL, #UTILX_NOTIFICATION_LEVEL_HIGH)
 493  * @pre The window should be a notification type window.
 494  * @see utilx_set_system_notification_level()
 495  * @par Example
 496   @code
 497   #include <utilX.h>
 498
 499   ...
 500
 501   Evas_Object *win;
 502   Ecore_X_Window xwin;
 503   Utilx_Notification_Level level;
 504
 505   win = elm_win_add (NULL, "test", ELM_WIN_NOTIFICATION);
 506   xwin = elm_win_xwindow_get(win);
 507
 508   level = utilx_get_system_notification_level (ecore_x_display_get(), xwin);
 509
 510   ...
 511   @endcode
 512  */
 513 Utilx_Notification_Level utilx_get_system_notification_level (Display* dpy, Window win);
 514
 515 /**
 516  * @brief Gets the string list and count of available key-names to grab.
 517  * @details This function returns the newly-allocated list and count of available key-names to grab for a target device.
 518  *          The key-name is unchangeable whatever you develope in different target.
 519  *          However, key-symbol got by utilx_get_key_symbol() is changeable in different target.
 520  * @since_tizen 3.0
 521  * @remarks You should free the pointer of name list by free() to avoid memory-leak
 522  * @param[out] count The number of avaiable keys for a target device
 523  * @return newly-allocated list of available key strings, otherwise NULL.
 524  * @see utilx_get_key_symbol()
 525  * @par Example
 526    @code
 527
 528   #include <utilX.h>
 529
 530   int
 531   main (int argc, char* argv[])
 532   {
 533         const char **names;
 534         int count = 0;
 535         int i;
 536
 537         names = utilx_get_available_key_names (&count);
 538         if (!names)
 539                 exit (-1);
 540
 541         for (i = 0; i < count; i++)
 542         {
 543                 const char *symbol = utilx_get_key_symbol (names[i]);
 544                 printf ("name: %s, symbol: %s\n", names[i], symbol);
 545         }
 546
 547         //should free names
 548         free (names);
 549
 550         return 0;
 551   }
 552
 553   @endcode
 554  */
 555 const char** utilx_get_available_key_names (int *count);
 556
 557 /**
 558  * @brief Gets a key-symbol string for a available key-name string to grab.
 559  * @details This function returns a key-symbol string for a available key-name to grab for a target device.
 560  *          The key-name got by utilx_get_available_key_names() is unchangeable whatever you develope in different target.
 561  *          However, key-symbol is changeable in different target.
 562  * @since_tizen 3.0
 563  * @param[in] key_name The name of a key got by utilx_get_available_key_names()
 564  * @return key-symbol string if success, otherwise NULL.
 565  * @see utilx_get_available_key_names(), utilx_grab_key(), utilx_ungrab_key()
 566  * @par Example
 567    @code
 568
 569   #include <utilX.h>
 570
 571   int
 572   main (int argc, char* argv[])
 573   {
 574         const char **names;
 575         int count = 0;
 576         int i;
 577
 578         names = utilx_get_available_key_names (&count);
 579         if (!names)
 580                 exit (-1);
 581
 582         for (i = 0; i < count; i++)
 583         {
 584                 const char *symbol = utilx_get_key_symbol (names[i]);
 585                 printf ("name: %s, symbol: %s\n", names[i], symbol);
 586         }
 587
 588         //should free names
 589         free (names);
 590
 591         return 0;
 592   }
 593
 594   @endcode
 595  */
 596 const char* utilx_get_key_symbol (const char *key_name);
 597
 598 /**
 599  * @brief Grabs the key specfied by @a key_symbol for a window in the @a grab_mode.
 600  *
 601  * @details This function establishes a grab of the specified key for the specified window.\n
 602  *          Once a key is grabbed, all events originating from the key will only be reported to the specfied window.\n
 603  *          The grab of the key can be released by calling utilx_ungrab_key().
 604  *
 605  *          This function is synchronous.
 606  *
 607  * @since_tizen 2.3
 608  * @remarks If utilx_grab_key() returns @c 0, the specified window will get the events of the specified key.\n
 609  *          However, delivery of a key can always be changed by other applications grabbing the key with higher priority.\n
 610  *          It can also be changed by the changes of window stacks.\n
 611  *          A trial for choosing a proper grab mode will be needed.
 612  * @param[in] dpy The connection to the X server
 613  * @param[in] win The window to grab a key
 614  * @param[in] key_symbol The symbol of a key in the string
 615  * @param[in] grab_mode The grab mode (such as #EXCLUSIVE_GRAB, #TOP_POSITION_GRAB, and #SHARED_GRAB)
 616  * @return @c 0 on success,
 617  *         otherwise failure
 618  * @pre This API must be called after the window 'win' has been mapped.
 619  * @post This API adds/changes the window property related to the grabbed key.
 620  * @see utilx_ungrab_key(), utilx_get_available_key_names(), utilx_get_key_symbol()
 621  * @par Example (using X11 APIs)
 622   @code
 623   #include <X11/Xlib.h>
 624   #include <utilX.h>
 625
 626   static const char* key_symbol;
 627
 628   static int
 629   get_key_symbol (void)
 630   {
 631       const char **names;
 632       int i, count = 0;
 633
 634       names = utilx_get_available_key_names (&count);
 635       if (!names)
 636           return 0;
 637
 638       for (i = 0; i < count; i++)
 639           if (!strcmp (names[i], "KEY_UP"))
 640           {
 641               key_symbol = utilx_get_key_symbol ("KEY_UP");
 642               printf ("found: key(%s,%s)\n", "KEY_UP", key_symbol);
 643               free (names);  // should free
 644               return 1;
 645           }
 646
 647       free (names); // should free
 648       return 0;
 649   }
 650
 651   int main()
 652   {
 653       Display *disp = XOpenDisplay(NULL);
 654       XEvent e;
 655       int grab_result;
 656       Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(disp,0), WhitePixel(disp,0));
 657       XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask | ExposureMask);
 658       XMapWindow(disp, w);
 659
 660       if (!get_key_symbol ())
 661           return -1;
 662
 663       while(1)
 664       {
 665           XNextEvent(disp, &e);
 666
 667           switch(e.type)
 668           {
 669           case MapNotify:
 670               //EXCLUSIVE_GRAB
 671               grab_result = utilx_grab_key(disp, w, key_symbol, EXCLUSIVE_GRAB);
 672               if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
 673                   return -1;
 674
 675               //utilx_grab_key(disp, w, key_symbol, TOP_POSITION_GRAB);
 676               //utilx_grab_key(disp, w, key_symbol, SHARED_GRAB);
 677
 678               break;
 679           }
 680           ...
 681       }
 682
 683       ...
 684
 685       utilx_ungrab_key(disp, w, key_symbol);
 686
 687       return 0;
 688   }
 689   @endcode
 690    * @par Example (using EFL APIs)
 691   @code
 692   #include <utilX.h>
 693   #include <Ecore_Evas.h>
 694   #include <Ecore_X.h>
 695
 696   static const char* key_symbol;
 697
 698   static int
 699   get_key_symbol (void)
 700   {
 701       const char **names;
 702       int i, count = 0;
 703
 704       names = utilx_get_available_key_names (&count);
 705       if (!names)
 706           return 0;
 707
 708       for (i = 0; i < count; i++)
 709           if (!strcmp (names[i], "KEY_UP"))
 710           {
 711               key_symbol = utilx_get_key_symbol ("KEY_UP");
 712               printf ("found: key(%s,%s)\n", "KEY_UP", key_symbol);
 713               free (names);  // should free
 714               return 1;
 715           }
 716
 717       free (names); // should free
 718       return 0;
 719   }
 720
 721   int main()
 722   {
 723         ...
 724
 725         Ecore_X_Display* disp = ecore_x_display_get();
 726         Ecore_X_Window w = ecore_evas_software_x11_window_get(ee);
 727         int grab_result;
 728
 729         get_key_symbol ();
 730
 731       //EXCLUSIVE_GRAB
 732       grab_result = utilx_grab_key(disp, w, key_symbol, EXCLUSIVE_GRAB);
 733       if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
 734           return -1;
 735
 736       //utilx_grab_key(disp, w, key_symbol, TOP_POSITION_GRAB);
 737       //utilx_grab_key(disp, w, key_symbol, SHARED_GRAB);
 738
 739         ...
 740
 741       utilx_ungrab_key(disp, w, key_symbol); //Ungrab whenever a user wants to
 742
 743         return 0;
 744   }
 745   @endcode
 746  */
 747 int utilx_grab_key (Display* dpy, Window win, const char* key_symbol, int grab_mode);
 748
 749 /**
 750  * @brief Ungrabs the key specfied by @a key_symbol for a window.
 751  *
 752  * @details This function releases the already established grab of the specfied key for the specified window.\n
 753  *          Once the grab of the key is released, delivery of the key events for the specfied window is going to be stopped.
 754  *
 755  *          This function is synchronous.
 756  *
 757  * @since_tizen 2.3
 758  * @param[in] dpy The connection to the X server
 759  * @param[in] win The window to grab a key
 760  * @param[in] key_symbol The symbol of a key in the string got by utilx_get_key_symbol()
 761  * @return @c 0 on success,
 762  *         otherwise failure
 763  * @pre This API must be called after the window 'win' is mapped.
 764  * @post This API changes/removes the window property related to the grabbed key.
 765  * @see utilx_grab_key(), utilx_get_available_key_names(), utilx_get_key_symbol()
 766  * @par Example (using X11 APIs)
 767   @code
 768   #include <X11/Xlib.h>
 769   #include <utilX.h>
 770
 771   static const char* key_symbol;
 772
 773   static int
 774   get_key_symbol (void)
 775   {
 776       const char **names;
 777       int i, count = 0;
 778
 779       names = utilx_get_available_key_names (&count);
 780       if (!names)
 781           return 0;
 782
 783       for (i = 0; i < count; i++)
 784           if (!strcmp (names[i], "KEY_UP"))
 785           {
 786               key_symbol = utilx_get_key_symbol ("KEY_UP");
 787               printf ("found: key(%s,%s)\n", "KEY_UP", key_symbol);
 788               free (names);  // should free
 789               return 1;
 790           }
 791
 792       free (names); // should free
 793       return 0;
 794   }
 795
 796   int main()
 797   {
 798       Display *disp = XOpenDisplay(NULL);
 799       XEvent e;
 800       int grab_result;
 801       Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(disp,0), WhitePixel(disp,0));
 802       XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask | ExposureMask);
 803       XMapWindow(disp, w);
 804
 805       if (!get_key_symbol ())
 806           return -1;
 807
 808       while(1)
 809       {
 810           XNextEvent(disp, &e);
 811
 812           switch(e.type)
 813           {
 814           case MapNotify:
 815               //EXCLUSIVE_GRAB
 816               grab_result = utilx_grab_key(disp, w, key_symbol, EXCLUSIVE_GRAB);
 817               if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
 818                   return -1;
 819
 820               //utilx_grab_key(disp, w, key_symbol, TOP_POSITION_GRAB);
 821               //utilx_grab_key(disp, w, key_symbol, SHARED_GRAB);
 822
 823               break;
 824           }
 825           ...
 826       }
 827
 828       ...
 829
 830       utilx_ungrab_key(disp, w, key_symbol);
 831
 832       return 0;
 833   }
 834   @endcode
 835    * @par Example (using EFL APIs)
 836   @code
 837   #include <utilX.h>
 838   #include <Ecore_Evas.h>
 839   #include <Ecore_X.h>
 840
 841   static const char* key_symbol;
 842
 843   static int
 844   get_key_symbol (void)
 845   {
 846       const char **names;
 847       int i, count = 0;
 848
 849       names = utilx_get_available_key_names (&count);
 850       if (!names)
 851           return 0;
 852
 853       for (i = 0; i < count; i++)
 854           if (!strcmp (names[i], "KEY_UP"))
 855           {
 856               key_symbol = utilx_get_key_symbol ("KEY_UP");
 857               printf ("found: key(%s,%s)\n", "KEY_UP", key_symbol);
 858               free (names);  // should free
 859               return 1;
 860           }
 861
 862       free (names); // should free
 863       return 0;
 864   }
 865
 866   int main()
 867   {
 868         ...
 869
 870         Ecore_X_Display* disp = ecore_x_display_get();
 871         Ecore_X_Window w = ecore_evas_software_x11_window_get(ee);
 872         int grab_result;
 873
 874         get_key_symbol ();
 875
 876       //EXCLUSIVE_GRAB
 877       grab_result = utilx_grab_key(disp, w, key_symbol, EXCLUSIVE_GRAB);
 878       if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
 879           return -1;
 880
 881       //utilx_grab_key(disp, w, key_symbol, TOP_POSITION_GRAB);
 882       //utilx_grab_key(disp, w, key_symbol, SHARED_GRAB);
 883
 884         ...
 885
 886       utilx_ungrab_key(disp, w, key_symbol); //Ungrab whenever a user wants to
 887
 888         return 0;
 889   }
 890   @endcode
 891  */
 892 int utilx_ungrab_key (Display* dpy, Window win, const char* key_symbol);
 893
 894 /**
 895  * @brief Sets the window's opaque state.
 896  *
 897  * @details This function sets the window's visibility to opaque even if the window is an alpha window.
 898  *          This function is available only for an alpha window.
 899  *          An alpha window's default opaque state is #UTILX_OPAQUE_STATE_OFF.
 900  *
 901  *          This function is an asynchronous call.
 902  *
 903  * @since_tizen 2.3
 904  * @remarks This is used only for alpha windows.
 905  * @param[in] dpy The connection to the X server
 906  * @param[in] win The window handle
 907  * @param[in] state The value that indicates whether the window has set a visible state to opaque(#UTILX_OPAQUE_STATE_ON) or not(#UTILX_OPAQUE_STATE_OFF)
 908  * @return @c 1 on success,
 909            otherwise failure
 910  * @par Example
 911   @code
 912   #include <X11/Xlib.h>
 913   #include <utilX.h>
 914
 915   ...
 916
 917   Display* dpy;
 918   Window root, win;
 919   int ret;
 920
 921   dpy = XOpenDisplay (NULL);
 922   root = XDefaultRootWindow (dpy);
 923
 924   win = XCreateSimpleWindow (dpy, root, 0, 0, 480, 800, 2, BlackPixel (dpy,0), WhitePixel(dpy,0));
 925   XMapWindow (dpy, win);
 926
 927   ret = utilx_set_window_opaque_state (dpy, win, UTILX_OPAQUE_STATE_ON);
 928   if (!ret)
 929   {
 930     printf ("Error! Failed to set opaque state.\n");
 931   }
 932
 933   XFlush (dpy);
 934
 935   ...
 936   @endcode
 937  */
 938 int utilx_set_window_opaque_state (Display* dpy, Window win, Utilx_Opaque_State state);
 939
 940 /**
 941  * @brief Creates a screenshot image.
 942  *
 943  * @details This function creates a screenshot image of the display.\n
 944  *          To use this function, you should get the permission first.\n
 945  *          In addition, device LCD must be turned on; otherwise, this function fails.\n
 946  *          Once this functions is called, utilx_release_screen_shot() should be called after it.
 947  *
 948  * @since_tizen 2.3
 949  * @privlevel platform
 950  * @privilege %http://tizen.org/privilege/screenshot
 951  * @remarks You should get the permission to use. Device LCD must be on.
 952  * @param[in] dpy The connection to the X server
 953  * @param[in] width The root window handle
 954  * @param[in] height The root window handle
 955  * @see utilx_release_screen_shot()
 956  * @par Example
 957   @code
 958     Display* dpy;
 959     int width, height;
 960     void *dump;
 961
 962     dpy = XOpenDisplay (NULL);
 963     width = DisplayWidth (dpy, DefaultScreen (dpy));
 964     height = DisplayHeight (dpy, DefaultScreen (dpy));
 965
 966     dump = utilx_create_screen_shot (dpy, width, height);
 967     if (dump)
 968     {
 969         // do_something (dump);
 970     }
 971     else
 972     {
 973         // utilx_create_screen_shot can return NULL in some cases.
 974         // Even if it returns NULL, utilx_release_screen_shot should be called.
 975     }
 976
 977     utilx_release_screen_shot ();
 978   @endcode
 979  */
 980 void* utilx_create_screen_shot (Display* dpy, int width, int height);
 981
 982 /**
 983  * @brief Releases screenshot resources.
 984  *
 985  * @details This function releases resources associated with screenshot
 986  *          image of the display. utilx_release_screen_shot() should be called once
 987  *          utilx_create_screen_shot() is called.
 988  *
 989  * @since_tizen 2.3
 990  * @privlevel platform
 991  * @privilege %http://tizen.org/privilege/screenshot
 992  * @see utilx_create_screen_shot()
 993  * @par Example
 994   @code
 995     Display* dpy;
 996     int width, height;
 997     void *dump;
 998
 999     dpy = XOpenDisplay (NULL);
1000     width = DisplayWidth (dpy, DefaultScreen (dpy));
1001     height = DisplayHeight (dpy, DefaultScreen (dpy));
1002
1003     dump = utilx_create_screen_shot (dpy, width, height);
1004     if (dump)
1005     {
1006         // do_something (dump);
1007     }
1008     else
1009     {
1010         // utilx_create_screen_shot can return NULL in some cases.
1011         // Even if it returns NULL, utilx_release_screen_shot should be called.
1012     }
1013
1014     utilx_release_screen_shot ();
1015   @endcode
1016  */
1017 void  utilx_release_screen_shot (void);
1018
1019 #ifdef __cplusplus
1020 }
1021 #endif
1022
1023 /**
1024 *@}
1025 */
1026
1027 #endif /* __TIZEN_LINUX_UTIL_X11_H__ */
1028