4 Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
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
10 http://www.apache.org/licenses/LICENSE-2.0
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.
20 #ifndef __SAMSUNG_LINUX_UTIL_X11_H__
21 #define __SAMSUNG_LINUX_UTIL_X11_H__
24 #define DEPRECATED __attribute__((deprecated))
30 * @defgroup utilX X11 utilities
32 * @brief Samsung Linux platform X11 utilties
34 * Common X11 utilities
35 * You can use this API with #include <utilX.h>
43 #include <sys/types.h>
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 */
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 */
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 */
62 // Earjack/BT Headset/Multimedia keys
63 #define KEY_PLAYCD "XF86AudioPlay" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Play Audio' key */
64 #define KEY_STOPCD "XF86AudioStop" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Stop Audio' key */
65 #define KEY_PAUSECD "XF86AudioPause" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Pause Audio' key */
66 #define KEY_NEXTSONG "XF86AudioNext" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Next Song' key */
67 #define KEY_PREVIOUSSONG "XF86AudioPrev" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Previous Song' key */
68 #define KEY_REWIND "XF86AudioRewind" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Rewind Song' key */
69 #define KEY_FASTFORWARD "XF86AudioForward" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Forward Song' key */
70 #define KEY_MEDIA "XF86AudioMedia" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Media' key */
73 #define KEY_SEND "XF86Send" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Send' key */
74 #define KEY_SELECT "XF86Phone" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Home' key */
75 #define KEY_END "XF86Stop" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'End' key */
77 // Renamed 3-Touch key
78 #define KEY_MENU "XF86Send" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Send' key */
79 #define KEY_HOME "XF86Phone" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'Home' key */
80 #define KEY_BACK "XF86Stop" /**< this macro means the XKeySym (XServer Key Symbol) corresponds to 'End' key */
82 #define LEN_KEY_VOLUMEUP 20 /**< this macro is the length of string corresponds to 'Volume Up' key */
83 #define LEN_KEY_VOLUMEDOWN 20 /**< this macro is the length of string corresponds to 'Volume Down' key */
85 #define LEN_KEY_CAMERA 10 /**< this macro is the length of string corresponds to 'Half-Press of Camera' key */
86 #define LEN_KEY_CONFIG 12 /**< this macro is the length of string corresponds to 'Full-Press of Camera' key */
88 #define LEN_KEY_POWER 12 /**< this macro is the length of string corresponds to 'Power' key */
89 #define LEN_KEY_PAUSE 11 /**< this macro is the length of string corresponds to 'Pause' key */
91 // Earjack/BT Headset/Multimedia keys
92 #define LEN_KEY_PLAYCD 13/**< this macro is the length of string corresponds to 'Play Audio' key */
93 #define LEN_KEY_STOPCD 13/**< this macro is the length of string corresponds to 'Stop Audio' key */
94 #define LEN_KEY_PAUSECD 14/**< this macro is the length of string corresponds to 'Pause Audio' key */
95 #define LEN_KEY_NEXTSONG 13/**< this macro is the length of string corresponds to 'Next Song' key */
96 #define LEN_KEY_PREVIOUSSONG 13/**< this macro is the length of string corresponds to 'Previous Song' key */
97 #define LEN_KEY_REWIND 15/**< this macro is the length of string corresponds to 'Rewind Song' key */
98 #define LEN_KEY_FASTFORWARD 16/**< this macro is the length of string corresponds to 'Forwand Song' key */
99 #define LEN_KEY_MEDIA 14/**< this macro is the length of string corresponds to 'Media' key */
102 #define LEN_KEY_SEND 8 /**< this macro is the length of string corresponds to 'Send' key */
103 #define LEN_KEY_SELECT 9 /**< this macro is the length of string corresponds to 'Home' key */
104 #define LEN_KEY_END 8 /**< this macro is the length of string corresponds to 'End' key */
106 // Renamed 3-Touch key
107 #define LEN_KEY_MENU 8 /**< this macro is the length of string corresponds to 'Send' key */
108 #define LEN_KEY_HOME 9 /**< this macro is the length of string corresponds to 'Home' key */
109 #define LEN_KEY_BACK 8 /**< this macro is the length of string corresponds to 'End' key */
111 #define OR_EXCLUSIVE_GRAB 0xf00000 /**< this means that the client window will always get the grabbed-key exclusively regardless of the position on the window stack but the grab is overridable by the other client window */
112 #define EXCLUSIVE_GRAB 0x0f0000 /**< this means that the client window will always get the grabbed-key exclusively regardless of the position on the window stack */
113 #define TOP_POSITION_GRAB 0x00f000 /**< this means that the client window will get the grabbed-key only when on the top of the grabbing-window stack */
114 #define SHARED_GRAB 0x000f00 /**< this means that the client window will get the grabbed-key together with the other client window(s) */
115 #define GRAB_MODE_MASK 0xffff00 /**< this mask will be used for getting the key-grab mode of a client window */
117 #define EXCLUSIVE_GRABBED_ALREADY 1 /**< this means that the client window is grabbing the key already in EXCLUSIVE mode */
119 #define STR_ATOM_GRAB_KEY "_GRAB_KEY" /**< this is an XATOM for getting/setting the property for grabbing a key for a window */
120 #define STR_ATOM_GRAB_EXCL_WIN "_GRAB_EXCL_WIN_KEYCODE" /**< this means that the key was grabbed by a client window in EXCLUSIVE mod */
121 #define STR_ATOM_GRAB_OR_EXCL_WIN "_GRAB_OR_EXCL_WIN_KEYCODE" /**< this means that the key was grabbed by a client window in OR_EXCLUSIVE mod */
124 * @brief Enumeration of key status
126 typedef enum _Utilx_Key_Status
128 UTILX_KEY_STATUS_PRESSED, /**< key status is pressed */
129 UTILX_KEY_STATUS_RELEASED, /**< key status is released */
130 UTILX_KEY_STATUS_UNKNOWN /** < key status is unknown or error happened */
134 * @brief Enumeration of notification window's priority level
136 typedef enum _Utilx_Notification_Level
138 UTILX_NOTIFICATION_LEVEL_LOW, /**< low level notification */
139 UTILX_NOTIFICATION_LEVEL_NORMAL, /**< normal level notification*/
140 UTILX_NOTIFICATION_LEVEL_HIGH /**< high level notification */
141 } Utilx_Notification_Level;
144 * @brief Enumeration of Compositing Window Manager's Effect Type
146 typedef enum _Utilx_Effect_Type
148 UTILX_EFFECT_TYPE_MAP, /**< Effect for Window's Map Notify Event */
149 UTILX_EFFECT_TYPE_UNMAP, /**< Effect for Window's UnMap Notify Event */
150 UTILX_EFFECT_TYPE_RAISEABOVE, /**< Effect for Window's Configure Notify ( RaiseAbove case ) Event */
151 UTILX_EFFECT_TYPE_ROTATION, /**< Effect for Window's Rotation Property Change Notify Event ( X Property: ECORE_X_ATOM_E_ILLUME_ROTATE_WINDOW_ANGLE ) */
152 UTILX_EFFECT_TYPE_FOCUSIN, /**< Effect for Window's FocusIn Event ( E17's Event: E_EVENT_BORDER_FOCUS_IN ) */
153 UTILX_EFFECT_TYPE_FOCUSOUT /**< Effect for Window's FocusOut Event ( E17's Event : E_EVENT_BORDER_FOCUS_OUT ) */
157 * @brief Enumeration of Compositing Window Manager's Effect Style
159 typedef enum _Utilx_Effect_Style
161 UTILX_EFFECT_STYLE_DEFAULT, /**< Default Effect Style for Effect Type */
162 UTILX_EFFECT_STYLE_NONE, /**< None of Effect Style for Effect Type */
163 UTILX_EFFECT_STYLE_CUSTOM0, /**< Custom0 Effect Style for Effect Type */
164 UTILX_EFFECT_STYLE_CUSTOM1, /**< Custom1 Effect Style for Effect Type */
165 UTILX_EFFECT_STYLE_CUSTOM2, /**< Custom2 Effect Style for Effect Type */
166 UTILX_EFFECT_STYLE_CUSTOM3, /**< Custom3 Effect Style for Effect Type */
167 UTILX_EFFECT_STYLE_CUSTOM4, /**< Custom4 Effect Style for Effect Type */
168 UTILX_EFFECT_STYLE_CUSTOM5, /**< Custom5 Effect Style for Effect Type */
169 UTILX_EFFECT_STYLE_CUSTOM6, /**< Custom6 Effect Style for Effect Type */
170 UTILX_EFFECT_STYLE_CUSTOM7, /**< Custom7 Effect Style for Effect Type */
171 UTILX_EFFECT_STYLE_CUSTOM8, /**< Custom8 Effect Style for Effect Type */
172 UTILX_EFFECT_STYLE_CUSTOM9 /**< Custom9 Effect Style for Effect Type */
173 } Utilx_Effect_Style;
176 * @brief Enumeration of opaque state
178 typedef enum _Utilx_Opaque_State
180 UTILX_OPAQUE_STATE_OFF = 0, /**< Transparent state */
181 UTILX_OPAQUE_STATE_ON = 1, /**< Opaque state */
182 } Utilx_Opaque_State;
186 * @fn void utilx_set_system_notification_level (Display* dpy, Window win, Utilx_Notification_Level level)
187 * @brief Sets the priority level for the specified notification window
189 * This function sets the priority level of the notification windows.\n
190 * Every notification window has a base priority level by the notification window's priority value. (Default priority is UTILX_NOTIFICATION_LEVEL_LOW)
192 * The priority is used for ordering of notification windows.\n
193 * The notification window which is set UTILX_NOTIFICATION_LEVEL_HIGH priority will be placed to the top of notification windows.\n
194 * If there are notification windows that have same priorities, the latest created notification window is placed on the other window.
196 * This function is a asynchronous call.
198 * @param[in] dpy Specifies the connection to the X server
199 * @param[in] win Specifies the window to be set
200 * @param[in] level Specifies the level (UTILX_NOTIFICATION_LEVEL_LOW, UTILX_NOTIFICATION_LEVEL_NORMAL, UTILX_NOTIFICATION_LEVEL_HIGH)
201 * @remark This is used only notification window.
202 * @pre The win should be notification type window
204 * @see utilx_get_system_notification_level
215 xwin = elm_win_xwindow_get(win);
217 // Set Notification type
218 ecore_x_netwm_window_type_set (xwin, ECORE_X_WINDOW_TYPE_NOTIFICATION);
220 // Set Notification's priority
221 utilx_set_system_notification_level (ecore_x_display_get(), xwin, UTILX_NOTIFICATION_LEVEL_HIGH);
226 void utilx_set_system_notification_level (Display* dpy, Window win, Utilx_Notification_Level level);
229 * @fn Utilx_Notification_Level utilx_get_system_notification_level (Display* dpy, Window win)
230 * @brief Gets the priority level for the specified notification window
232 * This function returns the priority level of the notification windows.\n
233 * If a user didn't set the notification's priority level, this function returns default value (UTILX_NOTIFICATION_LEVEL_LOW).
235 * This function is a synchronous call.
237 * @param[in] dpy Specifies the connection to the X server
238 * @param[in] win Specifies the window to be get
239 * @return current notication level (UTILX_NOTIFICATION_LEVEL_LOW, UTILX_NOTIFICATION_LEVEL_NORMAL, UTILX_NOTIFICATION_LEVEL_HIGH)
240 * @remark This is used only notification window.
241 * @pre The win should be notification type window
243 * @see utilx_set_system_notification_level
252 Utilx_Notification_Level level;
254 win = elm_win_add (NULL, "test", ELM_WIN_NOTIFICATION);
255 xwin = elm_win_xwindow_get(win);
257 level = utilx_get_system_notification_level (ecore_x_display_get(), xwin);
262 Utilx_Notification_Level utilx_get_system_notification_level (Display* dpy, Window win);
265 * @fn void utilx_enable_indicator (Display* dpy, Window win, int enable)
266 * @brief Sets the window to show/hide the indicator
268 * This function enables or disables the indicator.
270 * If an application wants to show the window with the indicator, the application must call this function with 1 as the enable parameter.\n
271 * Otherwise, the application must call this function with 0 as the enable parameter.
273 * This function is a asynchronous call.
275 * @param[in] dpy Specifies the connection to the X server
276 * @param[in] win Specifies the window to use indicator
277 * @param[in] enable Specifies whether the window use indicator or not
280 * @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.
281 * @see elm_win_indicator_state_set, utilx_get_indicator_state
284 #include <X11/Xlib.h>
292 dpy = XOpenDisplay (NULL);
293 root = XDefaultRootWindow (dpy);
295 win = XCreateSimpleWindow (dpy, root, 0, 0, 480, 800, 2, BlackPixel (dpy,0), WhitePixel(dpy,0));
296 XMapWindow (dpy, win);
298 // If the win want to show indicator, enables indicator.
299 utilx_enable_indicator (dpy, win, 1);
302 // If the win want to hide indicator, disables indicator.
303 utilx_enable_indicator (dpy, win, 0);
309 void utilx_enable_indicator (Display* dpy, Window win, int enable);
312 * @fn int utilx_get_indicator_state (Display* dpy, Window win)
313 * @brief Gets the indicator's state of the specified window
315 * This function gets the indicator's state of the specified window.
317 * An application can set the indicator's state using utilx_enable_indicator or elm_win_indicator_state_set.
318 * If an application sets enables the indicator, this returns 1.\n
319 * If an application disables the indicator, this returns 0.\n
320 * If an application doesn't set the indicator's state, in other words,
321 * an application doesn't call utilx_enable_indicator or elm_win_indicator_state_set,
324 * This function is a asynchronous call.
326 * @param[in] dpy Specifies the connection to the X server
327 * @param[in] win Specifies the window to get the indicator's state
328 * @return 1 if the indicator is enabled, 0 if the indicator is disabled, otherwise -1
332 * @see elm_win_indicator_state_set, utilx_enable_indicator
335 #include <X11/Xlib.h>
344 dpy = XOpenDisplay (NULL);
345 root = XDefaultRootWindow (dpy);
347 win = XCreateSimpleWindow (dpy, root, 0, 0, 480, 800, 2, BlackPixel (dpy,0), WhitePixel(dpy,0));
348 XMapWindow (dpy, win);
350 state = utilx_get_indicator_state (dpy, win)
351 // state is -1 (unknown)
353 // If the win want to show indicator, enables indicator.
354 utilx_enable_indicator (dpy, win, 1);
357 state = utilx_get_indicator_state (dpy, win)
358 // state is 1 (enabled)
360 // If the win want to hide indicator, disables indicator.
361 utilx_enable_indicator (dpy, win, 0);
364 state = utilx_get_indicator_state (dpy, win)
365 // state is 0 (disabled)
370 int utilx_get_indicator_state (Display* dpy, Window win);
374 * @fn int utilx_grab_key (Display* dpy, Window win, const char* key_name, int grab_mode)
375 * @brief Grabs a key specfied by key_name for win in grab_mode
377 * This function establishs a grab of the specified key for the specified window.\n
378 * Once a key was grabbed, all events originated from the key will only be reported to the specfied window.\n
379 * The grab of the key will be released by calling utilx_ungrab_key.
381 * This function is synchronous.
383 * @param[in] dpy Specifies the connection to the X server
384 * @param[in] win Specifies the window to grab a key
385 * @param[in] key_name Name of a key in string (ex> KEY_VOLUMEUP, KEY_VOLUMEDOWN, KEY_SEND and so on)
386 * @param[in] grab_mode Grab mode (such as EXCLUSIVE_GRAB, TOP_POSITION_GRAB and SHARED_GRAB)
387 * @return 0 on Success, otherwise Fail
388 * @remark If utilx_grab_key() returns 0, the specified window will get the events of the specified key.\n
389 However, delivery of a key can always be changed by other applications grabbing the key with higher priority.\n
390 It can also be changed by the changes of window stacks.\n
391 Trial for choosing a proper grab mode will be needed.
392 * @pre This API must be called after the window 'win' has been mapped
393 * @post This API adds/changes the window property related to grabbed key
394 * @see utilx_ungrab_key
395 * @par Example (using X11 APIs)
400 #include <X11/Xlib.h>
405 Display *disp = XOpenDisplay(NULL);
408 Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(d,0), WhitePixel(d,0));
409 XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask);
414 XNextEvent(disp, &e);
418 grab_result = utilx_grab_key(disp, w, KEY_POWER, EXCLUSIVE_GRAB);
419 if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
427 utilx_ungrab_key(disp, win, KEY_POWER);
431 // TOP_POSITION_GRAB //
433 #include <X11/Xlib.h>
438 Display *disp = XOpenDisplay(NULL);
440 Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(d,0), WhitePixel(d,0));
441 XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask);
446 XNextEvent(disp, &e);
450 utilx_grab_key(disp, w, KEY_POWER, TOP_POSITION_GRAB);
457 utilx_ungrab_key(disp, win, KEY_POWER);
463 #include <X11/Xlib.h>
468 Display *disp = XOpenDisplay(NULL);
470 Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(d,0), WhitePixel(d,0));
471 XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask);
476 XNextEvent(disp, &e);
480 utilx_grab_key(disp, w, KEY_POWER, SHARED_GRAB);
487 utilx_ungrab_key(disp, win, KEY_POWER);
492 * @par Example (using EFL APIs)
498 #include <Ecore_Evas.h>
505 Ecore_X_Display* disp = ecore_x_display_get();
506 Ecore_X_Window win = ecore_evas_software_x11_window_get(ee);
508 int grab_result = utilx_grab_key(disp, win, KEY_POWER, EXCLUSIVE_GRAB);
509 if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
514 utilx_ungrab_key(disp, win, KEY_POWER);//Ungrab whenever you want to ¡¦
518 // TOP_POSITION_GRAB //
521 #include <Ecore_Evas.h>
528 Ecore_X_Display* disp = ecore_x_display_get();
529 Ecore_X_Window win = ecore_evas_software_x11_window_get(ee);
531 utilx_grab_key(disp, win, KEY_POWER, TOP_POSITION_GRAB);
535 utilx_ungrab_key(disp, win, KEY_POWER);//Ungrab whenever you want to ¡¦
542 #include <Ecore_Evas.h>
549 Ecore_X_Display* disp = ecore_x_display_get();
550 Ecore_X_Window win = ecore_evas_software_x11_window_get(ee);
552 utilx_grab_key(disp, win, KEY_POWER, SHARED_GRAB);
556 utilx_ungrab_key(disp, win, KEY_POWER);//Ungrab whenever you want to ¡¦
561 int utilx_grab_key (Display* dpy, Window win, const char* key_name, int grab_mode);
564 * @fn int utilx_ungrab_key (Display* dpy, Window win, const char* key_name)
565 * @brief Ungrabs a key specfied by key_name for win
567 * This function releases the already established grab of the specfied key for the specified window.\n
568 * Once the grab of the key was released, delivery of the key events for the specfied window is going to be stopped.
570 * This function is synchronous.
572 * @param[in] dpy Specifies the connection to the X server
573 * @param[in] win Specifies the window to grab a key
574 * @param[in] key_name Name of a key in string (ex> KEY_VOLUMEUP, KEY_VOLUMEDOWN, KEY_SEND and so on)
575 * @return 0 on Success, otherwise Fail
576 * @remark No additional information
577 * @pre This API must be called after the window 'win' has been mapped
578 * @post This API changes/removes the window property related to grabbed key
579 * @see utilx_grab_key
580 * @par Example (using X11 APIs)
585 #include <X11/Xlib.h>
590 Display *disp = XOpenDisplay(NULL);
593 Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(d,0), WhitePixel(d,0));
594 XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask);
599 XNextEvent(disp, &e);
603 grab_result = utilx_grab_key(disp, w, KEY_POWER, EXCLUSIVE_GRAB);
604 if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
612 utilx_ungrab_key(disp, win, KEY_POWER);
616 // TOP_POSITION_GRAB //
618 #include <X11/Xlib.h>
623 Display *disp = XOpenDisplay(NULL);
625 Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(d,0), WhitePixel(d,0));
626 XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask);
631 XNextEvent(disp, &e);
635 utilx_grab_key(disp, w, KEY_POWER, TOP_POSITION_GRAB);
642 utilx_ungrab_key(disp, win, KEY_POWER);
648 #include <X11/Xlib.h>
653 Display *disp = XOpenDisplay(NULL);
655 Window w = XCreateSimpleWindow(disp, DefaultRootWindow(disp), 5,5, 470, 780, 2, BlackPixel(d,0), WhitePixel(d,0));
656 XSelectInput(disp, w, StructureNotifyMask | KeyPressMask | KeyReleaseMask);
661 XNextEvent(disp, &e);
665 utilx_grab_key(disp, w, KEY_POWER, SHARED_GRAB);
672 utilx_ungrab_key(disp, win, KEY_POWER);
677 * @par Example (using EFL APIs)
683 #include <Ecore_Evas.h>
690 Ecore_X_Display* disp = ecore_x_display_get();
691 Ecore_X_Window win = ecore_evas_software_x11_window_get(ee);
693 int grab_result = utilx_grab_key(disp, win, KEY_POWER, EXCLUSIVE_GRAB);
694 if( EXCLUSIVE_GRABBED_ALREADY == grab_result )
698 utilx_ungrab_key(disp, win, KEY_POWER);//Ungrab whenever you want to ¡¦
702 // TOP_POSITION_GRAB //
705 #include <Ecore_Evas.h>
712 Ecore_X_Display* disp = ecore_x_display_get();
713 Ecore_X_Window win = ecore_evas_software_x11_window_get(ee);
715 utilx_grab_key(disp, win, KEY_POWER, TOP_POSITION_GRAB);
719 utilx_ungrab_key(disp, win, KEY_POWER);//Ungrab whenever you want to ¡¦
727 #include <Ecore_Evas.h>
734 Ecore_X_Display* disp = ecore_x_display_get();
735 Ecore_X_Window win = ecore_evas_software_x11_window_get(ee);
737 utilx_grab_key(disp, win, KEY_POWER, SHARED_GRAB);
741 utilx_ungrab_key(disp, win, KEY_POWER);//Ungrab whenever you want to ¡¦
746 int utilx_ungrab_key (Display* dpy, Window win, const char* key_name);
749 * @fn int utilx_get_key_status(Display* dpy, char *key_name)
750 * @brief Gets a status of a key specified by key_name
752 * This function gets a status of a key.\n
753 * ex>UTILX_KEY_STATUS_PRESSED, UTILX_KEY_STATUS_RELEASED and UTILX_KEY_STATUS_UNKNOWN
755 * This function is synchronous.
757 * @param[in] dpy Specifies the connection to the X server
758 * @param[in] key_name Name of a key in string (ex> KEY_VOLUMEUP, KEY_VOLUMEDOWN, KEY_SEND and so on)
759 * @return 0 on Success, otherwise Fail
760 * @remark No additional information
761 * @pre This API must be called for H/W keys specified in this header file(utilX.h).
762 * @par Example (using X11 APIs)
765 #include <X11/Xlib.h>
770 Display *disp = XOpenDisplay(NULL);
771 Utilx_Key_Status status;
773 status = utilx_get_key_status(disp, KEY_PLAYCD);
777 case UTILX_KEY_STATUS_PRESSED:
778 //The key is pressed.
781 case UTILX_KEY_STATUS_RELEASED:
782 //The key is released.
785 case UTILX_KEY_STATUS_UNKNOWN:
787 //The key status is unknown;
795 * @par Example (using EFL APIs)
799 #include <Ecore_Evas.h>
806 Ecore_X_Display* disp = ecore_x_display_get();
807 Utilx_Key_Status status;
809 status = utilx_get_key_status(disp, KEY_PLAYCD);
813 case UTILX_KEY_STATUS_PRESSED:
814 //The key is pressed.
817 case UTILX_KEY_STATUS_RELEASED:
818 //The key is released.
821 case UTILX_KEY_STATUS_UNKNOWN:
823 //The key status is unknown;
830 Utilx_Key_Status utilx_get_key_status(Display* dpy, char *key_name);
832 /* Window Effect APIs */
834 * @fn void utilx_set_window_effect_state(Display* dpy, Window win, int state)
835 * @brief Sets a window's effect state ( enable or disable )
837 * This function sets window's effect state. if effect is not enabled by composite manager, \n
838 * window's effect could not be enabled.
840 * This function is a asynchronous call.
842 * @param[in] dpy Specifies the connection to the X server
843 * @param[in] win Specifies the window handle
844 * @param[in] state Enables/disables the window effect
845 * @remark This is used only client window. ( not root window )
846 * @pre This api must be called before fist show ( XMapWindow Event ).
847 * @post This changes Client Window's Effect related property.
848 * @see utilx_get_window_effect_state
851 #include <X11/Xlib.h>
858 dpy = XOpenDisplay (NULL);
859 root = XDefaultRootWindow (dpy);
861 win = XCreateSimpleWindow (dpy, root, 0, 0, 480, 800, 2, BlackPixel (dpy,0), WhitePixel(dpy,0));
863 // Sets a window's effect state to enable ( enable : 1, disable 0 )
864 utilx_set_window_effect_state(dpy, win, 1);
866 XMapWindow (dpy, win);
870 void utilx_set_window_effect_state(Display* dpy, Window win, int state);
873 * @fn int utilx_get_window_effect_state(Display* dpy, Window win)
874 * @brief Gets a window's effect state ( enable or disable )
876 * This function returns windows's effect state.\n
877 * If effect is not enabled by composite manager, then this return value is unusable or meanless.
879 * This function is a asynchronous call.
881 * @param[in] dpy Specifies the connection to the X server
882 * @param[in] win Specifies the window handle
883 * @return Current window effect state
884 * @remark This is used only client window. ( not root window )
885 * @pre This api does not require any pre-condition.
886 * @post This api does not change any condition.
887 * @see utilx_set_window_effect_state
890 #include <X11/Xlib.h>
897 dpy = XOpenDisplay (NULL);
898 root = XDefaultRootWindow (dpy);
900 win = XCreateSimpleWindow (dpy, root, 0, 0, 480, 800, 2, BlackPixel (dpy,0), WhitePixel(dpy,0));
902 XMapWindow (dpy, win);
904 // Gets a window's effect state ( enable : 1, disable 0 )
905 printf( "current window's effect state = %d\n", utilx_get_window_effect_state(dpy, win) ) ;
909 int utilx_get_window_effect_state(Display* dpy, Window win);
912 * @fn void utilx_show_fake_effect(Display* dpy, Window win, char *fake_image_file)
913 * @brief Shows a window's "fake show effect" animation
915 * This function show's application fake show image.\n
916 * This function is only used by application launching program.
918 * This function is a asynchronous call.
920 * @param[in] dpy Specifies the connection to the X server
921 * @param[in] win Specifies the root window handle
922 * @param[in] fake_image_file Specifies the fake window image and file format is png type.
923 * @remark This is used only menu-screen window.
924 * @pre This api must be called before client's fist show ( XMapWindow Event ). you must call this api then run application.
925 * @post This changes root window's fake effect related property.
926 * @see utilx_hide_fake_effect
929 #include <X11/Xlib.h>
936 dpy = XOpenDisplay (NULL);
937 root = XDefaultRootWindow (dpy);
939 // Shows a window's "fake show effect" animation, and if you want to see animation, /root/fake_window_image.png file must be exited.
940 utilx_show_fake_effect( dpy, root, "/root/fake_window_image.png");
944 void utilx_show_fake_effect(Display *dpy, Window win, char *fake_image_file);
947 * @fn void utilx_hide_fake_effect(Display* dpy, Window win)
948 * @brief Shows a window's "fake hide effect" animation, and this animation uses "fake show effect" 's window image.
950 * This function shoes a window's fake hide effect.\n
951 * This function is only used by application launching program.\n
952 * When application was not executed by any error.
954 * This function is a asynchronous call.
956 * @param[in] dpy Specifies the connection to the X server
957 * @param[in] win Specifies the root window handle
958 * @remark This is used only menu-screen window.
959 * @pre This api must be called after "utilx_show_fake_effect()".
960 * @post This changes root window's fake effect related property.
961 * @see utilx_show_fake_effect
964 #include <X11/Xlib.h>
971 dpy = XOpenDisplay (NULL);
972 root = XDefaultRootWindow (dpy);
974 // 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()
975 // and if real window is showed , then fake hide effect could not be showed.
976 utilx_hide_fake_effect( dpy, root );
980 void utilx_hide_fake_effect(Display *dpy, Window win);
983 * @fn void utilx_set_window_effect_style(Display* dpy, Window win, Utilx_Effect_Type type, Utilx_Effect_Style style)
984 * @brief Sets a window's effect style with effect type.
986 * This function sets a window's effect style with effect type.\n
987 * Default Window Effect is setted by Window Type and Window Class.\n
988 * And then, you could change custom effecct.\n
989 * Custom Effect is available max 10. ( CUSTOM0 ~ CUSTOM9 )\n
990 * If you didn't set custom effect, then compositing window manger provides Default Window Effect.\n
992 * This function is a asynchronous call.
994 * @param[in] dpy Specifies the connection to the X server
995 * @param[in] win Specifies the window handle
996 * @param[in] type Specifies the window's effect type ( ex. UTILX_EFFECT_TYPE_MAP, UTILX_EFFECT_TYPE_UNMAP, etc )
997 * @param[in] style Specifies the window's effect style ( ex. UTILX_EFFECT_STYLE_DEFAULT, UTILX_EFFECT_STYLE_NONE, UTILX_EFFECT_STYLE_CUSTOM0, etc )
998 * @remark This is used only client window. ( not root window )
999 * @pre This api does not require any pre-condition.
1000 * @post This changes window's effect type related property ( _NET_CM_WINDOW_EFFECT_TYPE ).
1001 * @see utilx_get_window_effect_style
1004 #include <X11/Xlib.h>
1005 #include <X11/Xutil.h>
1011 unsigned long black, white;
1013 dpy = XOpenDisplay(NULL) ;
1015 black = BlackPixel(dpy, 0);
1016 white = WhitePixel(dpy, 0);
1018 root = XDefaultRootWindow (dpy);
1019 win = XCreateSimpleWindow ( dpy, root, 0, 0, 100, 100, 2, BlackPixel (d,0), WhitePixel(d,0) );
1021 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
1023 XMapWindow(dpy, win);
1027 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
1029 XUnmapWindow (dpy, win);
1031 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
1032 XMapWindow (dpy, win);
1036 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
1037 XUnmapWindow (dpy, win);
1041 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
1042 XMapWindow (dpy, win);
1046 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
1047 XUnmapWindow (dpy, win);
1052 void utilx_set_window_effect_style(Display* dpy, Window win, Utilx_Effect_Type type, Utilx_Effect_Style style);
1055 * @fn Utilx_Effect_Style utilx_get_window_effect_style(Display* dpy, Window win, Utilx_Effect_Type type)
1056 * @brief Gets a window's effect style with effect type.
1058 * This function gets a window's effect style with effect type.\n
1060 * This function is a asynchronous call.
1062 * @param[in] dpy Specifies the connection to the X server
1063 * @param[in] win Specifies the window handle
1064 * @param[in] type Specifies the window's effect type ( ex. UTILX_EFFECT_TYPE_MAP, UTILX_EFFECT_TYPE_UNMAP, etc )
1065 * @return Current window's effect style ( ex. UTILX_EFFECT_STYLE_DEFAULT, UTILX_EFFECT_STYLE_NONE, UTILX_EFFECT_STYLE_CUSTOM0, etc )
1066 * @remark This is used only client window. ( not root window )
1067 * @pre This api does not require any pre-condition.
1068 * @post This api does not change any condition.
1069 * @see utilx_set_window_effect_style
1072 #include <X11/Xlib.h>
1073 #include <X11/Xutil.h>
1079 unsigned long black, white;
1080 Utilx_Effect_Style style;
1082 dpy = XOpenDisplay(NULL) ;
1084 black = BlackPixel(dpy, 0);
1085 white = WhitePixel(dpy, 0);
1087 root = XDefaultRootWindow (dpy);
1088 win = XCreateSimpleWindow ( dpy, root, 0, 0, 100, 100, 2, BlackPixel (d,0), WhitePixel(d,0) );
1090 style = utilx_set_window_effect_style(dpy, win, UTILX_EFFECT_TYPE_MAP); // get effect style with window's show effet type
1094 style = utilx_set_window_effect_style(dpy, win, UTILX_EFFECT_TYPE_UNMAP); // get effect style with window's show effet type
1099 Utilx_Effect_Style utilx_get_window_effect_style(Display* dpy, Window win, Utilx_Effect_Type type);
1102 * @fn void utilx_set_window_opaque_state (Display* dpy, Window win, int opaque)
1103 * @brief Sets the window's opaque state
1105 * This function sets window's visibility to opaque even if the window is an alpha window.
1106 * This function is available only alpha window.
1107 * An alpha window's default opaque state is UTILX_OPAQUE_STATE_OFF.
1109 * This function is a asynchronous call.
1111 * @param[in] dpy Specifies the connection to the X server
1112 * @param[in] win Specifies the window handle
1113 * @param[in] state Specifies whether the window set a visible state to opaque(UTILX_OPAQUE_STATE_ON) or not(UTILX_OPAQUE_STATE_OFF)
1114 * @return 1 on Success, otherwise Fail
1115 * @remark This is used only alpha window.
1121 #include <X11/Xlib.h>
1130 dpy = XOpenDisplay (NULL);
1131 root = XDefaultRootWindow (dpy);
1133 win = XCreateSimpleWindow (dpy, root, 0, 0, 480, 800, 2, BlackPixel (dpy,0), WhitePixel(dpy,0));
1134 XMapWindow (dpy, win);
1136 ret = utilx_set_window_opaque_state (dpy, win, UTILX_OPAQUE_STATE_ON);
1139 printf ("Error! Failed to set opaque state.\n");
1147 int utilx_set_window_opaque_state (Display* dpy, Window win, Utilx_Opaque_State state);
1150 * @fn int utilx_set_screen_capture(Display* dpy, int enable)
1151 * @brief Specifies whether the screen capture functionality is enable or not.
1153 * This function makes the screen capture functionality of CBHM enable or disable.
1154 * CBHM = Clipboard History Manager.
1156 * This function is synchronous.
1158 * @param[in] dpy Specifies the connection to the X server
1159 * @param[in] enable Specifies the window handle. (1:Enable, 0:Disable)
1160 * @pre This api does not require any pre-condition.
1161 * @post This api does not change any condition.
1162 * @see utilx_get_screen_capture
1165 #include <X11/Xlib.h>
1166 #include <X11/Xutil.h>
1172 dpy = XOpenDisplay(NULL) ;
1174 utilx_set_screen_capture (dpy, 1);
1179 int utilx_set_screen_capture(Display* dpy, int enable);
1182 * @fn int utilx_get_screen_capture(Display* dpy, int enable)
1183 * @brief Gets whether the screen capture functionality is enable or not.
1185 * This function gets whether the screen capture functionality of CBHM is enable or not.
1186 * CBHM = Clipboard History Manager.
1188 * This function is synchronous.
1190 * @param[in] dpy Specifies the connection to the X server
1191 * @pre This api does not require any pre-condition.
1192 * @post This api does not change any condition.
1193 * @see utilx_set_screen_capture
1196 #include <X11/Xlib.h>
1197 #include <X11/Xutil.h>
1204 dpy = XOpenDisplay(NULL) ;
1206 enable = utilx_set_screen_capture (dpy);
1211 int utilx_get_screen_capture(Display* dpy);
1214 * @fn void utilx_set_window_cardinal_property(Display* dpy, Window win, Atom atom, unsigned int *value)
1215 * @brief Sets the cardinal property to Window
1217 * This function Sets the cardinal property to Window.
1219 * This function is synchronous.
1221 * @param[in] dpy Specifies the connection to the X server
1222 * @param[in] win Specifies the window handle
1223 * @param[in] atom Specifies the atom of cardinal property
1224 * @param[in] value the value of cardinal property to set.
1225 * @pre This api does not require any pre-condition.
1226 * @post This api does not change any condition.
1227 * @see utilx_get_window_cardinal_property
1230 #include <X11/Xlib.h>
1231 #include <X11/Xutil.h>
1240 dpy = XOpenDisplay (NULL);
1241 root = XDefaultRootWindow (dpy);
1243 atom = XInternAtom(dpy, "TEST_ATOM", False);
1245 utilx_set_window_cardinal_property (dpy, root, atom, (unsigned int*)&value);
1250 void utilx_set_window_cardinal_property(Display* dpy, Window win, Atom atom, unsigned int *value);
1253 * @fn int utilx_get_window_cardinal_property(Display* dpy, Window win, Atom atom, unsigned int *value)
1254 * @brief Gets the value of cardinal property.
1256 * This function gets the value of cardinal property.
1258 * This function is synchronous.
1260 * @param[in] dpy Specifies the connection to the X server
1261 * @param[in] win Specifies the window handle
1262 * @param[in] atom Specifies the atom of cardinal property
1263 * @param[out] value the value of cardinal property to get.
1264 * @pre This api does not require any pre-condition.
1265 * @post This api does not change any condition.
1266 * @see utilx_set_window_cardinal_property
1269 #include <X11/Xlib.h>
1270 #include <X11/Xutil.h>
1279 dpy = XOpenDisplay (NULL);
1280 root = XDefaultRootWindow (dpy);
1282 atom = XInternAtom(dpy, "TEST_ATOM", False);
1284 if (utilx_set_window_cardinal_property (dpy, root, atom, (unsigned int*)&value) > 0)
1292 int utilx_get_window_cardinal_property(Display* dpy, Window win, Atom atom, unsigned int *value);
1295 * @fn void utilx_show_capture_effect(Display *dpy, Window win )
1296 * @brief Shows a capture effect animation
1298 * This function show capture effect animation.\n
1299 * This function is only used by Screen Capture Application.
1301 * This function is a asynchronous call.
1303 * @param[in] dpy Specifies the connection to the X server
1304 * @param[in] win Specifies the root window handle
1305 * @remark This is used only screen capture application.
1306 * @pre This api does not require any pre-condition.
1307 * @post This api does not change any condition.
1308 * @see utilx_set_screen_capture
1311 #include <X11/Xlib.h>
1318 dpy = XOpenDisplay (NULL);
1319 root = XDefaultRootWindow (dpy);
1321 // Shows a Shows a capture effect animation
1322 utilx_show_capture_effect( dpy, root);
1326 void utilx_show_capture_effect(Display *dpy, Window win );
1337 #endif /* __SAMSUNG_LINUX_UTIL_X11_H__ */