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 // Hauppauge remocon keys
 215 /**
 216  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Channel Up' key.
 217  */
 218 #define KEY_CHANNELUP   "XF86KbdBrightnessUp"
 219 /**
 220  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Channel Down' key.
 221  */
 222 #define KEY_CHANNELDOWN "XF86KbdBrightnessDown"
 223 /**
 224  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Close' key.
 225  */
 226 #define KEY_CLOSE "XF86Close"
 227 /**
 228  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Video Pause' key.
 229  */
 230 #define KEY_VIDEOPAUSE "Pause"
 231 /**
 232  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'Audio Record' key.
 233  */
 234 #define KEY_RECORD "XF86AudioRecord"
 235
 236 /**
 237  * @brief Definition for XKeySym (XServer Key Symbol) corresponding to the 'TV(toggle)' key.
 238  */
 239 #define KEY_TV "XF86Display"
 240
 241
 242 /**
 243  * @brief Definition for the length of a string corresponding to the 'Volume Up' key.
 244  */
 245 #define LEN_KEY_VOLUMEUP                20
 246 /**
 247  * @brief Definition for the length of a string corresponding to the 'Volume Down' key.
 248  */
 249 #define LEN_KEY_VOLUMEDOWN      20
 250
 251 /**
 252  * @brief Definition for the length of a string corresponding to the 'Half-Press of Camera' key.
 253  */
 254 #define LEN_KEY_CAMERA          10
 255 /**
 256  * @brief Definition for the length of a string corresponding to the 'Full-Press of Camera' key.
 257  */
 258 #define LEN_KEY_CONFIG          12
 259
 260 /**
 261  * @brief Definition for the length of a string corresponding to the 'Power' key.
 262  */
 263 #define LEN_KEY_POWER           12
 264 /**
 265  * @brief Definition for the length of a string corresponding to the 'Pause' key.
 266  */
 267 #define LEN_KEY_PAUSE           11
 268
 269 // Earjack/BT Headset/Multimedia keys
 270 /**
 271  * @brief Definition for the length of a string corresponding to the 'Play Audio' key.
 272  */
 273 #define LEN_KEY_PLAYCD          13
 274 /**
 275  * @brief Definition for the length of a string corresponding to the 'Stop Audio' key.
 276  */
 277 #define LEN_KEY_STOPCD          13
 278 /**
 279  * @brief Definition for the length of a string corresponding to the 'Pause Audio' key.
 280  */
 281 #define LEN_KEY_PAUSECD         14
 282 /**
 283  * @brief Definition for the length of a string corresponding to the 'Next Song' key.
 284  */
 285 #define LEN_KEY_NEXTSONG        13
 286 /**
 287  * @brief Definition for the length of a string corresponding to the 'Previous Song' key.
 288  */
 289 #define LEN_KEY_PREVIOUSSONG            13
 290 /**
 291  * @brief Definition for the length of a string corresponding to the 'Rewind Song' key.
 292  */
 293 #define LEN_KEY_REWIND          15
 294 /**
 295  * @brief Definition for the length of a string corresponding to the 'Forwand Song' key.
 296  */
 297 #define LEN_KEY_FASTFORWARD             16
 298 /**
 299  * @brief Definition for the length of a string corresponding to the 'Media' key.
 300  */
 301 #define LEN_KEY_MEDIA           14
 302 /**
 303  * @brief Definition for the length of a string corresponding to the 'PlayPause' key.
 304  */
 305 #define LEN_KEY_PLAYPAUSE       13
 306 /**
 307  * @brief Definition for the length of a string corresponding to the 'Mute' key.
 308  */
 309 #define LEN_KEY_MUTE            13
 310
 311 // 3-Touch key
 312 /**
 313  * @brief Definition for the length of a string corresponding to the 'Send' key.
 314  */
 315 #define LEN_KEY_SEND            8
 316 /**
 317  * @brief Definition for the length of a string corresponding to the 'Home' key.
 318  */
 319 #define LEN_KEY_SELECT          9
 320 /**
 321  * @brief Definition for the length of a string corresponding to the 'End' key.
 322  */
 323 #define LEN_KEY_END             8
 324
 325 // Renamed 3-Touch key
 326 /**
 327  * @brief Definition for the length of a string corresponding to the 'Send' key.
 328  */
 329 #define LEN_KEY_MENU            8
 330 /**
 331  * @brief Definition for the length of a string corresponding to the 'Home' key.
 332  */
 333 #define LEN_KEY_HOME            9
 334 /**
 335  * @brief Definition for the length of a string corresponding to the 'End' key.
 336  */
 337 #define LEN_KEY_BACK            8
 338
 339 //Other functions keys
 340 /**
 341  * @brief Definition for the length of a string corresponding to the 'HomePage' key.
 342  */
 343 #define LEN_KEY_HOMEPAGE        12
 344 /**
 345  * @brief Definition for the length of a string corresponding to the 'WWW' key.
 346  */
 347 #define LEN_KEY_WEBPAGE 7
 348 /**
 349  * @brief Definition for the length of a string corresponding to the 'Mail' key.
 350  */
 351 #define LEN_KEY_MAIL            8
 352 /**
 353  * @brief Definition for the length of a string corresponding to the 'ScreenSaver' key.
 354  */
 355 #define LEN_KEY_SCREENSAVER     15
 356 /**
 357  * @brief Definition for the length of a string corresponding to the 'BrightnessUp' key.
 358  */
 359 #define LEN_KEY_BRIGHTNESSUP    19
 360 /**
 361  * @brief Definition for the length of a string corresponding to the 'BrightnessDown' key.
 362  */
 363 #define LEN_KEY_BRIGHTNESSDOWN  21
 364 /**
 365  * @brief Definition for the length of a string corresponding to the 'Soft keyboard(toggle)' key.
 366  */
 367 #define LEN_KEY_SOFTKBD         10
 368 /**
 369  * @brief Definition for the length of a string corresponding to the 'Quick panel(toggle)' key.
 370  */
 371 #define LEN_KEY_QUICKPANEL              9
 372 /**
 373  * @brief Definition for the length of a string corresponding to the 'Task switcher(toggle)' key.
 374  */
 375 #define LEN_KEY_TASKSWITCH      12
 376 /**
 377  * @brief Definition for the length of a string corresponding to the 'Apptray(toggle)' key.
 378  */
 379 #define LEN_KEY_APPS                    11
 380 /**
 381  * @brief Definition for the length of a string corresponding to the 'Search(toggle)' key.
 382  */
 383 #define LEN_KEY_SEARCH                  10
 384 /**
 385  * @brief Definition for the length of a string corresponding to the 'Voice(toggle)' key.
 386  */
 387 #define LEN_KEY_VOICE                   11
 388 /**
 389  * @brief Definition for the length of a string corresponding to the 'Language(toggle)' key.
 390  */
 391 #define LEN_KEY_LANGUAGE                6
 392 /**
 393  * @brief Definition for the length of a string corresponding to the 'Call(toggle)' key.
 394  */
 395 #define LEN_KEY_CONNECT                 6
 396 /**
 397  * @brief Definition for the length of a string corresponding to the 'Play(toggle)' key.
 398  */
 399 #define LEN_KEY_GAMEPLAY                8
 400 /**
 401  * @brief Definition for the length of a string corresponding to the 'Voice Wakeup LPSD' key.
 402  */
 403 #define LEN_KEY_VOICEWAKEUP_LPSD        11
 404 /**
 405  * @brief Definition for the length of a string corresponding to the 'Voice Wakeup' key.
 406  */
 407 #define LEN_KEY_VOICEWAKEUP                     11
 408
 409 // Hauppauge remocon keys
 410 /**
 411  * @brief Definition for the length of a string corresponding to the 'Channel Up' key.
 412  */
 413 #define LEN_KEY_CHANNELUP       19
 414 /**
 415  * @brief Definition for the length of a string corresponding to the 'Channel Down' key.
 416  */
 417 #define LEN_KEY_CHANNELDOWN     21
 418 /**
 419  * @brief Definition for the length of a string corresponding to the 'Close' key.
 420  */
 421 #define LEN_KEY_CLOSE 9
 422 /**
 423  * @brief Definition for the length of a string corresponding to the 'Video Pause' key.
 424  */
 425 #define LEN_KEY_VIDEOPAUSE 5
 426 /**
 427  * @brief Definition for the length of a string corresponding to the 'Audio Record' key.
 428  */
 429 #define LEN_KEY_RECORD 15
 430 /**
 431  * @brief Definition for the length of a string corresponding to the 'TV(toggle)' key.
 432  */
 433 #define LEN_KEY_TV 11
 434
 435
 436 /**
 437  * @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.
 438  */
 439 #define OR_EXCLUSIVE_GRAB       0xf00000
 440 /**
 441  * @brief Definition for getting the grabbed-key exclusively regardless of its position on the window stack mode.
 442  */
 443 #define EXCLUSIVE_GRAB          0x0f0000
 444 /**
 445  * @brief Definition for getting the grabbed-key only when on the top of the grabbing-window stack mode.
 446  */
 447 #define TOP_POSITION_GRAB       0x00f000
 448 /**
 449  * @brief Definition for getting the grabbed-key together with the other client window(s) mode.
 450  */
 451 #define SHARED_GRAB             0x000f00
 452 /**
 453  * @brief Definition for getting the key-grab mode of a client window.
 454  */
 455 #define GRAB_MODE_MASK  0xffff00
 456
 457 /**
 458  * @brief Definition for the client window grabbing the key which is already in the EXCLUSIVE mode.
 459  */
 460 #define EXCLUSIVE_GRABBED_ALREADY       1
 461
 462 /**
 463  * @brief Definition for getting/setting the property while grabbing a key for a window.
 464  */
 465 #define STR_ATOM_GRAB_KEY       "_GRAB_KEY"
 466 /**
 467  * @brief Definition for the key grabbed by a client window in the EXCLUSIVE mode.
 468  */
 469 #define STR_ATOM_GRAB_EXCL_WIN  "_GRAB_EXCL_WIN_KEYCODE"
 470 /**
 471  * @brief Definition for the key grabbed by a client window in the OR_EXCLUSIVE mode.
 472  */
 473 #define STR_ATOM_GRAB_OR_EXCL_WIN       "_GRAB_OR_EXCL_WIN_KEYCODE"
 474
 475 /**
 476  * @brief Enumeration for notification window's priority level.
 477  */
 478 typedef enum _Utilx_Notification_Level
 479 {
 480         UTILX_NOTIFICATION_LEVEL_LOW, /**< Low level notification */
 481         UTILX_NOTIFICATION_LEVEL_NORMAL, /**< Normal level notification*/
 482         UTILX_NOTIFICATION_LEVEL_HIGH /**< High level notification */
 483 } Utilx_Notification_Level;
 484
 485 /**
 486  * @brief Enumeration for the opaque state.
 487  */
 488 typedef enum _Utilx_Opaque_State
 489 {
 490         UTILX_OPAQUE_STATE_OFF = 0, /**< Transparent state */
 491         UTILX_OPAQUE_STATE_ON  = 1, /**< Opaque state */
 492 } Utilx_Opaque_State;
 493
 494 /**
 495  * @brief Sets the priority level for the specified notification window, asynchronously.
 496  *
 497  * @details This function sets the priority level of notification windows.\n
 498  *          Every notification window has a base priority level by the notification window's priority value (default priority is #UTILX_NOTIFICATION_LEVEL_LOW).
 499  *
 500  *          The priority is used for ordering of notification windows.\n
 501  *          The notification window with the priority set to #UTILX_NOTIFICATION_LEVEL_HIGH will be placed at the top of the notification windows.\n
 502  *          If there are notification windows which have same priorities, the last created notification window will be placed on the other window.
 503  *
 504  * @since_tizen 2.3
 505  * @remarks This is used only for notification windows.
 506  * @param[in] dpy The connection to the X server
 507  * @param[in] win The window to set
 508  * @param[in] level The level (#UTILX_NOTIFICATION_LEVEL_LOW, #UTILX_NOTIFICATION_LEVEL_NORMAL, #UTILX_NOTIFICATION_LEVEL_HIGH)
 509  * @pre The window should be a notification type window.
 510  * @see #Utilx_Notification_Level
 511  * @see utilx_get_system_notification_level()
 512  * @par Example
 513   @code
 514   #include <utilX.h>
 515
 516   ...
 517
 518   Evas_Object *win;
 519   Ecore_X_Window xwin;
 520
 521   win = create_mwnd();
 522   xwin = elm_win_xwindow_get(win);
 523
 524   // Set Notification type
 525   ecore_x_netwm_window_type_set (xwin, ECORE_X_WINDOW_TYPE_NOTIFICATION);
 526
 527   // Set Notification's priority
 528   utilx_set_system_notification_level (ecore_x_display_get(), xwin, UTILX_NOTIFICATION_LEVEL_HIGH);
 529
 530   ...
 531   @endcode
 532  */
 533 void utilx_set_system_notification_level (Display* dpy, Window win, Utilx_Notification_Level level);
 534
 535 /**
 536  * @brief Gets the priority level for the specified notification window.
 537  *
 538  * @details This function returns the priority level of notification windows.\n
 539  *          If a user didn't set the notification's priority level, this function returns the default value (#UTILX_NOTIFICATION_LEVEL_LOW).
 540  *
 541  *          This function is a synchronous call.
 542  *
 543  * @since_tizen 2.3
 544  * @remarks This is used only for notification windows.
 545  * @param[in] dpy The connection to the X server
 546  * @param[in] win The window to get
 547  * @return The current notification level (#UTILX_NOTIFICATION_LEVEL_LOW, #UTILX_NOTIFICATION_LEVEL_NORMAL, #UTILX_NOTIFICATION_LEVEL_HIGH)
 548  * @pre The window should be a notification type window.
 549  * @see utilx_set_system_notification_level()
 550  * @par Example
 551   @code
 552   #include <utilX.h>
 553
 554   ...
 555
 556   Evas_Object *win;
 557   Ecore_X_Window xwin;
 558   Utilx_Notification_Level level;
 559
 560   win = elm_win_add (NULL, "test", ELM_WIN_NOTIFICATION);
 561   xwin = elm_win_xwindow_get(win);
 562
 563   level = utilx_get_system_notification_level (ecore_x_display_get(), xwin);
 564
 565   ...
 566   @endcode
 567  */
 568 Utilx_Notification_Level utilx_get_system_notification_level (Display* dpy, Window win);
 569
 570 /**
 571  * @brief Gets the string list and count of available key-names to grab.
 572  * @details This function returns the newly-allocated list and count of available key-names to grab for a target device.
 573  *          The key-name is unchangeable whatever you develope in different target.
 574  *          However, key-symbol got by utilx_get_key_symbol() is changeable in different target.
 575  * @since_tizen 3.0
 576  * @remarks You should free the pointer of name list by free() to avoid memory-leak
 577  * @param[out] count The number of avaiable keys for a target device
 578  * @return newly-allocated list of available key strings, otherwise NULL.
 579  * @see utilx_get_key_symbol()
 580  * @par Example
 581    @code
 582
 583   #include <utilX.h>
 584
 585   int
 586   main (int argc, char* argv[])
 587   {
 588         const char **names;
 589         int count = 0;
 590         int i;
 591
 592         names = utilx_get_available_key_names (&count);
 593         if (!names)
 594                 exit (-1);
 595
 596         for (i = 0; i < count; i++)
 597         {
 598                 const char *symbol = utilx_get_key_symbol (names[i]);
 599                 printf ("name: %s, symbol: %s\n", names[i], symbol);
 600         }
 601
 602         //should free names
 603         free (names);
 604
 605         return 0;
 606   }
 607
 608   @endcode
 609  */
 610 const char** utilx_get_available_key_names (int *count);
 611
 612 /**
 613  * @brief Gets a key-symbol string for a available key-name string to grab.
 614  * @details This function returns a key-symbol string for a available key-name to grab for a target device.
 615  *          The key-name got by utilx_get_available_key_names() is unchangeable whatever you develope in different target.
 616  *          However, key-symbol is changeable in different target.
 617  * @since_tizen 3.0
 618  * @param[in] key_name The name of a key got by utilx_get_available_key_names()
 619  * @return key-symbol string if success, otherwise NULL.
 620  * @see utilx_get_available_key_names(), utilx_grab_key(), utilx_ungrab_key()
 621  * @par Example
 622    @code
 623
 624   #include <utilX.h>
 625
 626   int
 627   main (int argc, char* argv[])
 628   {
 629         const char **names;
 630         int count = 0;
 631         int i;
 632
 633         names = utilx_get_available_key_names (&count);
 634         if (!names)
 635                 exit (-1);
 636
 637         for (i = 0; i < count; i++)
 638         {
 639                 const char *symbol = utilx_get_key_symbol (names[i]);
 640                 printf ("name: %s, symbol: %s\n", names[i], symbol);
 641         }
 642
 643         //should free names
 644         free (names);
 645
 646         return 0;
 647   }
 648
 649   @endcode
 650  */
 651 const char* utilx_get_key_symbol (const char *key_name);
 652
 653 /**
 654  * @brief Grabs the key specfied by @a key_symbol for a window in the @a grab_mode.
 655  *
 656  * @details This function establishes a grab of the specified key for the specified window.\n
 657  *          Once a key is grabbed, all events originating from the key will only be reported to the specfied window.\n
 658  *          The grab of the key can be released by calling utilx_ungrab_key().
 659  *
 660  *          This function is synchronous.
 661  *
 662  * @since_tizen 2.3
 663  * @remarks If utilx_grab_key() returns @c 0, the specified window will get the events of the specified key.\n
 664  *          However, delivery of a key can always be changed by other applications grabbing the key with higher priority.\n
 665  *          It can also be changed by the changes of window stacks.\n
 666  *          A trial for choosing a proper grab mode will be needed.
 667  * @param[in] dpy The connection to the X server
 668  * @param[in] win The window to grab a key
 669  * @param[in] key_symbol The symbol of a key in the string
 670  * @param[in] grab_mode The grab mode (such as #EXCLUSIVE_GRAB, #TOP_POSITION_GRAB, and #SHARED_GRAB)
 671  * @return @c 0 on success,
 672  *         otherwise failure
 673  * @pre This API must be called after the window 'win' has been mapped.
 674  * @post This API adds/changes the window property related to the grabbed key.
 675  * @see utilx_ungrab_key(), utilx_get_available_key_names(), utilx_get_key_symbol()
 676  * @par Example (using X11 APIs)
 677   @code
 678   #include <X11/Xlib.h>
 679   #include <utilX.h>
 680
 681   static const char* key_symbol;
 682
 683   static int
 684   get_key_symbol (void)
 685   {
 686       const char **names;
 687       int i, count = 0;
 688
 689       names = utilx_get_available_key_names (&count);
 690       if (!names)
 691           return 0;
 692
 693       for (i = 0; i < count; i++)
 694           if (!strcmp (names[i], "KEY_UP"))
 695           {
 696               key_symbol = utilx_get_key_symbol ("KEY_UP");
 697               printf ("found: key(%s,%s)\n", "KEY_UP", key_symbol);
 698               free (names);  // should free
 699               return 1;
 700           }
 701
 702       free (names); // should free
 703       return 0;
 704   }
 705
 706   int main()
 707   {
 708       Display *disp = XOpenDisplay(NULL);
 709       XEvent e;
 710       int grab_result;
 711       Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(disp,0), WhitePixel(disp,0));
 712       XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask | ExposureMask);
 713       XMapWindow(disp, w);
 714
 715       if (!get_key_symbol ())
 716           return -1;
 717
 718       while(1)
 719       {
 720           XNextEvent(disp, &e);
 721
 722           switch(e.type)
 723           {
 724           case MapNotify:
 725               //EXCLUSIVE_GRAB
 726               grab_result = utilx_grab_key(disp, w, key_symbol, EXCLUSIVE_GRAB);
 727               if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
 728                   return -1;
 729
 730               //utilx_grab_key(disp, w, key_symbol, TOP_POSITION_GRAB);
 731               //utilx_grab_key(disp, w, key_symbol, SHARED_GRAB);
 732
 733               break;
 734           }
 735           ...
 736       }
 737
 738       ...
 739
 740       utilx_ungrab_key(disp, w, key_symbol);
 741
 742       return 0;
 743   }
 744   @endcode
 745    * @par Example (using EFL APIs)
 746   @code
 747   #include <utilX.h>
 748   #include <Ecore_Evas.h>
 749   #include <Ecore_X.h>
 750
 751   static const char* key_symbol;
 752
 753   static int
 754   get_key_symbol (void)
 755   {
 756       const char **names;
 757       int i, count = 0;
 758
 759       names = utilx_get_available_key_names (&count);
 760       if (!names)
 761           return 0;
 762
 763       for (i = 0; i < count; i++)
 764           if (!strcmp (names[i], "KEY_UP"))
 765           {
 766               key_symbol = utilx_get_key_symbol ("KEY_UP");
 767               printf ("found: key(%s,%s)\n", "KEY_UP", key_symbol);
 768               free (names);  // should free
 769               return 1;
 770           }
 771
 772       free (names); // should free
 773       return 0;
 774   }
 775
 776   int main()
 777   {
 778         ...
 779
 780         Ecore_X_Display* disp = ecore_x_display_get();
 781         Ecore_X_Window w = ecore_evas_software_x11_window_get(ee);
 782         int grab_result;
 783
 784         get_key_symbol ();
 785
 786       //EXCLUSIVE_GRAB
 787       grab_result = utilx_grab_key(disp, w, key_symbol, EXCLUSIVE_GRAB);
 788       if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
 789           return -1;
 790
 791       //utilx_grab_key(disp, w, key_symbol, TOP_POSITION_GRAB);
 792       //utilx_grab_key(disp, w, key_symbol, SHARED_GRAB);
 793
 794         ...
 795
 796       utilx_ungrab_key(disp, w, key_symbol); //Ungrab whenever a user wants to
 797
 798         return 0;
 799   }
 800   @endcode
 801  */
 802 int utilx_grab_key (Display* dpy, Window win, const char* key_symbol, int grab_mode);
 803
 804 /**
 805  * @brief Ungrabs the key specfied by @a key_symbol for a window.
 806  *
 807  * @details This function releases the already established grab of the specfied key for the specified window.\n
 808  *          Once the grab of the key is released, delivery of the key events for the specfied window is going to be stopped.
 809  *
 810  *          This function is synchronous.
 811  *
 812  * @since_tizen 2.3
 813  * @param[in] dpy The connection to the X server
 814  * @param[in] win The window to grab a key
 815  * @param[in] key_symbol The symbol of a key in the string got by utilx_get_key_symbol()
 816  * @return @c 0 on success,
 817  *         otherwise failure
 818  * @pre This API must be called after the window 'win' is mapped.
 819  * @post This API changes/removes the window property related to the grabbed key.
 820  * @see utilx_grab_key(), utilx_get_available_key_names(), utilx_get_key_symbol()
 821  * @par Example (using X11 APIs)
 822   @code
 823   #include <X11/Xlib.h>
 824   #include <utilX.h>
 825
 826   static const char* key_symbol;
 827
 828   static int
 829   get_key_symbol (void)
 830   {
 831       const char **names;
 832       int i, count = 0;
 833
 834       names = utilx_get_available_key_names (&count);
 835       if (!names)
 836           return 0;
 837
 838       for (i = 0; i < count; i++)
 839           if (!strcmp (names[i], "KEY_UP"))
 840           {
 841               key_symbol = utilx_get_key_symbol ("KEY_UP");
 842               printf ("found: key(%s,%s)\n", "KEY_UP", key_symbol);
 843               free (names);  // should free
 844               return 1;
 845           }
 846
 847       free (names); // should free
 848       return 0;
 849   }
 850
 851   int main()
 852   {
 853       Display *disp = XOpenDisplay(NULL);
 854       XEvent e;
 855       int grab_result;
 856       Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(disp,0), WhitePixel(disp,0));
 857       XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask | ExposureMask);
 858       XMapWindow(disp, w);
 859
 860       if (!get_key_symbol ())
 861           return -1;
 862
 863       while(1)
 864       {
 865           XNextEvent(disp, &e);
 866
 867           switch(e.type)
 868           {
 869           case MapNotify:
 870               //EXCLUSIVE_GRAB
 871               grab_result = utilx_grab_key(disp, w, key_symbol, EXCLUSIVE_GRAB);
 872               if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
 873                   return -1;
 874
 875               //utilx_grab_key(disp, w, key_symbol, TOP_POSITION_GRAB);
 876               //utilx_grab_key(disp, w, key_symbol, SHARED_GRAB);
 877
 878               break;
 879           }
 880           ...
 881       }
 882
 883       ...
 884
 885       utilx_ungrab_key(disp, w, key_symbol);
 886
 887       return 0;
 888   }
 889   @endcode
 890    * @par Example (using EFL APIs)
 891   @code
 892   #include <utilX.h>
 893   #include <Ecore_Evas.h>
 894   #include <Ecore_X.h>
 895
 896   static const char* key_symbol;
 897
 898   static int
 899   get_key_symbol (void)
 900   {
 901       const char **names;
 902       int i, count = 0;
 903
 904       names = utilx_get_available_key_names (&count);
 905       if (!names)
 906           return 0;
 907
 908       for (i = 0; i < count; i++)
 909           if (!strcmp (names[i], "KEY_UP"))
 910           {
 911               key_symbol = utilx_get_key_symbol ("KEY_UP");
 912               printf ("found: key(%s,%s)\n", "KEY_UP", key_symbol);
 913               free (names);  // should free
 914               return 1;
 915           }
 916
 917       free (names); // should free
 918       return 0;
 919   }
 920
 921   int main()
 922   {
 923         ...
 924
 925         Ecore_X_Display* disp = ecore_x_display_get();
 926         Ecore_X_Window w = ecore_evas_software_x11_window_get(ee);
 927         int grab_result;
 928
 929         get_key_symbol ();
 930
 931       //EXCLUSIVE_GRAB
 932       grab_result = utilx_grab_key(disp, w, key_symbol, EXCLUSIVE_GRAB);
 933       if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
 934           return -1;
 935
 936       //utilx_grab_key(disp, w, key_symbol, TOP_POSITION_GRAB);
 937       //utilx_grab_key(disp, w, key_symbol, SHARED_GRAB);
 938
 939         ...
 940
 941       utilx_ungrab_key(disp, w, key_symbol); //Ungrab whenever a user wants to
 942
 943         return 0;
 944   }
 945   @endcode
 946  */
 947 int utilx_ungrab_key (Display* dpy, Window win, const char* key_symbol);
 948
 949 /**
 950  * @brief Sets the window's opaque state.
 951  *
 952  * @details This function sets the window's visibility to opaque even if the window is an alpha window.
 953  *          This function is available only for an alpha window.
 954  *          An alpha window's default opaque state is #UTILX_OPAQUE_STATE_OFF.
 955  *
 956  *          This function is an asynchronous call.
 957  *
 958  * @since_tizen 2.3
 959  * @remarks This is used only for alpha windows.
 960  * @param[in] dpy The connection to the X server
 961  * @param[in] win The window handle
 962  * @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)
 963  * @return @c 1 on success,
 964            otherwise failure
 965  * @par Example
 966   @code
 967   #include <X11/Xlib.h>
 968   #include <utilX.h>
 969
 970   ...
 971
 972   Display* dpy;
 973   Window root, win;
 974   int ret;
 975
 976   dpy = XOpenDisplay (NULL);
 977   root = XDefaultRootWindow (dpy);
 978
 979   win = XCreateSimpleWindow (dpy, root, 0, 0, 480, 800, 2, BlackPixel (dpy,0), WhitePixel(dpy,0));
 980   XMapWindow (dpy, win);
 981
 982   ret = utilx_set_window_opaque_state (dpy, win, UTILX_OPAQUE_STATE_ON);
 983   if (!ret)
 984   {
 985     printf ("Error! Failed to set opaque state.\n");
 986   }
 987
 988   XFlush (dpy);
 989
 990   ...
 991   @endcode
 992  */
 993 int utilx_set_window_opaque_state (Display* dpy, Window win, Utilx_Opaque_State state);
 994
 995 /**
 996  * @brief Creates a screenshot image.
 997  *
 998  * @details This function creates a screenshot image of the display.\n
 999  *          To use this function, you should get the permission first.\n
1000  *          In addition, device LCD must be turned on; otherwise, this function fails.\n
1001  *          Once this functions is called, utilx_release_screen_shot() should be called after it.
1002  *
1003  * @since_tizen 2.3
1004  * @privlevel platform
1005  * @privilege %http://tizen.org/privilege/screenshot
1006  * @remarks You should get the permission to use. Device LCD must be on.
1007  * @param[in] dpy The connection to the X server
1008  * @param[in] width The root window handle
1009  * @param[in] height The root window handle
1010  * @see utilx_release_screen_shot()
1011  * @par Example
1012   @code
1013     Display* dpy;
1014     int width, height;
1015     void *dump;
1016
1017     dpy = XOpenDisplay (NULL);
1018     width = DisplayWidth (dpy, DefaultScreen (dpy));
1019     height = DisplayHeight (dpy, DefaultScreen (dpy));
1020
1021     dump = utilx_create_screen_shot (dpy, width, height);
1022     if (dump)
1023     {
1024         // do_something (dump);
1025     }
1026     else
1027     {
1028         // utilx_create_screen_shot can return NULL in some cases.
1029         // Even if it returns NULL, utilx_release_screen_shot should be called.
1030     }
1031
1032     utilx_release_screen_shot ();
1033   @endcode
1034  */
1035 void* utilx_create_screen_shot (Display* dpy, int width, int height);
1036
1037 /**
1038  * @brief Releases screenshot resources.
1039  *
1040  * @details This function releases resources associated with screenshot
1041  *          image of the display. utilx_release_screen_shot() should be called once
1042  *          utilx_create_screen_shot() is called.
1043  *
1044  * @since_tizen 2.3
1045  * @privlevel platform
1046  * @privilege %http://tizen.org/privilege/screenshot
1047  * @see utilx_create_screen_shot()
1048  * @par Example
1049   @code
1050     Display* dpy;
1051     int width, height;
1052     void *dump;
1053
1054     dpy = XOpenDisplay (NULL);
1055     width = DisplayWidth (dpy, DefaultScreen (dpy));
1056     height = DisplayHeight (dpy, DefaultScreen (dpy));
1057
1058     dump = utilx_create_screen_shot (dpy, width, height);
1059     if (dump)
1060     {
1061         // do_something (dump);
1062     }
1063     else
1064     {
1065         // utilx_create_screen_shot can return NULL in some cases.
1066         // Even if it returns NULL, utilx_release_screen_shot should be called.
1067     }
1068
1069     utilx_release_screen_shot ();
1070   @endcode
1071  */
1072 void  utilx_release_screen_shot (void);
1073
1074 #ifdef __cplusplus
1075 }
1076 #endif
1077
1078 /**
1079 *@}
1080 */
1081
1082 #endif /* __TIZEN_LINUX_UTIL_X11_H__ */
1083