Tizen Native API  4.0
EFL UTIL WINDOW PROPERTY

Handle properties of windows.

Required Header

#include <efl_util.h>

Overview

The EFL UTIL WINDOW PROPERTY API provides functions to set/get properties of windows such as the notification level, the screen mode and the brightness.

Functions

int efl_util_set_notification_window_level (Evas_Object *window, efl_util_notification_level_e level)
 Sets the priority level for the specified notification window.
int efl_util_get_notification_window_level (Evas_Object *window, efl_util_notification_level_e *level)
 Gets the priority level for the specified notification window.
int efl_util_set_notification_window_level_error_cb (Evas_Object *window, efl_util_notification_window_level_error_cb callback, void *user_data) TIZEN_DEPRECATED_API
 Registers a callback function to be invoked when an error which set the notification level occurs.
int efl_util_unset_notification_window_level_error_cb (Evas_Object *window) TIZEN_DEPRECATED_API
 Unregisters the callback function.
int efl_util_set_window_opaque_state (Evas_Object *window, int opaque)
 Sets the alpha window's visual state to opaque state.
int efl_util_set_window_screen_mode (Evas_Object *window, efl_util_screen_mode_e mode)
 Sets the window's screen mode.
int efl_util_get_window_screen_mode (Evas_Object *window, efl_util_screen_mode_e *mode)
 Gets the screen mode of the specified window.
int efl_util_set_window_screen_mode_error_cb (Evas_Object *window, efl_util_window_screen_mode_error_cb callback, void *user_data) TIZEN_DEPRECATED_API
 Registers a callback function to be invoked when an error which set the screen mode.
int efl_util_unset_window_screen_mode_error_cb (Evas_Object *window) TIZEN_DEPRECATED_API
 Unregisters the callback function.
int efl_util_set_window_brightness (Evas_Object *window, int brightness)
 Sets the user's preferred brightness of the specified window.
int efl_util_get_window_brightness (Evas_Object *window, int *brightness)
 Gets the user's preferred brightness of the specified window.

Typedefs

typedef void(* efl_util_notification_window_level_error_cb )(Evas_Object *window, int error_code, void *user_data)
 Called when an error occurs for setting notification window level.
typedef void(* efl_util_window_screen_mode_error_cb )(Evas_Object *window, int error_code, void *user_data)
 Called when an error occurs for setting window's screen mode.

Typedef Documentation

typedef void(* efl_util_notification_window_level_error_cb)(Evas_Object *window, int error_code, void *user_data)

Called when an error occurs for setting notification window level.

Deprecated:
Deprecated since 3.0.
Since :
2.3.1
Remarks:
An application can check error by the return value of efl_util_set_notification_window_level since 3.0.
Parameters:
[in]windowThe EFL window
[in]error_codeThe error code (EFL_UTIL_ERROR_PERMISSION_DENIED)
[in]user_dataThe user data passed from the callback registration function
See also:
efl_util_set_notification_window_level_error_cb()
efl_util_unset_notification_window_level_error_cb()
typedef void(* efl_util_window_screen_mode_error_cb)(Evas_Object *window, int error_code, void *user_data)

Called when an error occurs for setting window's screen mode.

Deprecated:
Deprecated since 3.0.
Since :
2.4
Remarks:
An application can check error by the return value of efl_util_set_window_screen_mode since 3.0.
Parameters:
[in]windowThe EFL window
[in]error_codeThe error code (EFL_UTIL_ERROR_PERMISSION_DENIED)
[in]user_dataThe user data passed from the callback registration function
See also:
efl_util_set_window_screen_mode_error_cb()
efl_util_unset_window_screen_mode_error_cb()

Enumeration Type Documentation

Enumeration for EFL UTIL ERROR.

Since :
2.3.1
Enumerator:
EFL_UTIL_ERROR_NONE 

Successful

EFL_UTIL_ERROR_INVALID_PARAMETER 

Invalid parameter

EFL_UTIL_ERROR_OUT_OF_MEMORY 

Out of memory

EFL_UTIL_ERROR_PERMISSION_DENIED 

Permission denied

EFL_UTIL_ERROR_NO_SUCH_DEVICE 
Warning:
This is not for use by third-party applications. No such device or address (Since: 3.0)
EFL_UTIL_ERROR_INVALID_OPERATION 
Warning:
This is not for use by third-party applications. Function not implemented (Since: 3.0)
EFL_UTIL_ERROR_NOT_SUPPORTED 
Warning:
This is not for use by third-party applications. Not supported (Since: 3.0)
EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE 

Window type not supported

EFL_UTIL_ERROR_SCREENSHOT_INIT_FAIL 
Warning:
This is not for use by third-party applications. Screenshot initialization fail (Since: 3.0)
EFL_UTIL_ERROR_SCREENSHOT_EXECUTION_FAIL 
Warning:
This is not for use by third-party applications. Screenshot execution fail (Since: 3.0)
EFL_UTIL_ERROR_NO_RESOURCE_AVAILABLE 

Resource is not available (Since: 4.0)

Enumeration of notification window's priority level.

Since :
2.3.1
Enumerator:
EFL_UTIL_NOTIFICATION_LEVEL_1 

Default notification level. (Deprecated since 3.0. Use EFL_UTIL_NOTIFICATION_LEVEL_DEFAULT instead.)

EFL_UTIL_NOTIFICATION_LEVEL_2 

Higher notification level than default. (Deprecated since 3.0. Use EFL_UTIL_NOTIFICATION_LEVEL_MEDIUM instead.)

EFL_UTIL_NOTIFICATION_LEVEL_3 

The highest notification level. (Deprecated since 3.0. Use EFL_UTIL_NOTIFICATION_LEVEL_TOP instead.)

EFL_UTIL_NOTIFICATION_LEVEL_NONE 

No (reset) notification level. This value makes the window place in normal layer. (Since: 3.0)

EFL_UTIL_NOTIFICATION_LEVEL_DEFAULT 

Default notification level. (Since: 3.0)

EFL_UTIL_NOTIFICATION_LEVEL_MEDIUM 

Higher notification level than default. (Since: 3.0)

EFL_UTIL_NOTIFICATION_LEVEL_HIGH 

Higher notification level than medium. (Since: 3.0)

EFL_UTIL_NOTIFICATION_LEVEL_TOP 

The highest notification level. (Since: 3.0)

Enumeration of screen mode.

Since :
3.0
Enumerator:
EFL_UTIL_SCREEN_MODE_DEFAULT 

The mode which turns the screen off after a timeout.

EFL_UTIL_SCREEN_MODE_ALWAYS_ON 

The mode which keeps the screen turned on.


Function Documentation

Gets the priority level for the specified notification window.

Since :
2.3.1
Remarks:
This API can be used for a notification type window only. Up to the version 2.3.1, it supports as async APIs. But it is synchronous call since Tizen 3.0
Parameters:
[in]windowThe EFL window
[out]levelThe notification window level
Returns:
0 on success, otherwise a negative error value
Return values:
EFL_UTIL_ERROR_NONESuccessful
EFL_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPEWindow type not supported
int efl_util_get_window_brightness ( Evas_Object window,
int *  brightness 
)

Gets the user's preferred brightness of the specified window.

Since :
3.0
Parameters:
[in]windowThe EFL window
[out]brightnessThe preferred brightness
Returns:
0 on success, otherwise a negative error value
Return values:
EFL_UTIL_ERROR_NONESuccessful
EFL_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
efl_util_set_window_brightness()

Gets the screen mode of the specified window.

Since :
3.0
Parameters:
[in]windowThe EFL window
[out]modeThe screen mode
Returns:
0 on success, otherwise a negative error value
Return values:
EFL_UTIL_ERROR_NONESuccessful
EFL_UTIL_ERROR_INVALID_PARAMETERInvalid parameter

Sets the priority level for the specified notification window.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/window.priority.set
Remarks:
This API can be used for a notification type window only. Up to the version 2.3.1, it supports as async APIs. But it is synchronous call since Tizen 3.0
Parameters:
[in]windowThe EFL window
[in]levelThe notification window level
Returns:
0 on success, otherwise a negative error value
Return values:
EFL_UTIL_ERROR_NONESuccessful
EFL_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPEWindow type not supported
EFL_UTIL_ERROR_PERMISSION_DENIEDPermission denied

Registers a callback function to be invoked when an error which set the notification level occurs.

Deprecated:
Deprecated since 3.0. Use the return value of efl_util_set_notification_window_level() instead.
Since :
2.3.1
Remarks:
An application can check error by the return value of efl_util_set_notification_window_level since 3.0.
Parameters:
[in]windowThe EFL window
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
EFL_UTIL_ERROR_NONESuccessful
EFL_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
EFL_UTIL_ERROR_OUT_OF_MEMORYOut of memory
Postcondition:
efl_util_notification_window_level_error_cb() will be invoked.
See also:
efl_util_unset_notification_window_level_error_cb()
efl_util_notification_window_level_error_cb()
int efl_util_set_window_brightness ( Evas_Object window,
int  brightness 
)

Sets the user's preferred brightness of the specified window.

This API is useful when the application need to change the brightness of the screen when it is appeared on the screen. If the application sets the brightness 0 to 100 to its window and the application window is shown wholly or partially, the window manager requests the display system to change the brightness of the screen using user's preferred brightness. If the window is no longer shown, then the window manger request the display system to go back to default brightness. If the brightness is less than 0, this means to use the default screen brightness.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/display
Remarks:
This API needs the privilege. If the application which is not get the privilege use this API, the window manager generates the permission deny error.
Parameters:
[in]windowThe EFL window
[in]brightnessThe preferred brightness
Returns:
0 on success, otherwise a negative error value
Return values:
EFL_UTIL_ERROR_NONESuccessful
EFL_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
EFL_UTIL_ERROR_PERMISSION_DENIEDPermission denied
EFL_UTIL_ERROR_OUT_OF_MEMORYOut of memory
See also:
efl_util_get_window_brightness()
int efl_util_set_window_opaque_state ( Evas_Object window,
int  opaque 
)

Sets the alpha window's visual state to opaque state.

This API sets the alpha window's visual state to opaque state. If the alpha window sets the visual state to the opaque, then the window manager could handle it as the opaque window while calculating visibility. This API will have no effect when used by a non-alpha window.

Since :
3.0
Parameters:
[in]windowThe EFL window
[in]opaqueThe value that indicates whether the window has set a visual state to opaque (0: unset, 1: set)
Returns:
0 on success, otherwise a negative error value
Return values:
EFL_UTIL_ERROR_NONESuccessful
EFL_UTIL_ERROR_INVALID_PARAMETERInvalid parameter

Sets the window's screen mode.

This API is useful when the application need to keep the display turned on. If the application set the mode to EFL_UTIL_SCREEN_MODE_ALWAYS_ON to its window and the window is shown wholly or partially, the window manager requests the display system to keep the display on as long as the window is shown. If the window is no longer shown, then the window manger request the display system to go back to normal operation. Default screen mode of window is EFL_UTIL_SCREEN_MODE_DEFAULT.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/display
Remarks:
This API needs the privilege. If the application which is not get the privilege use this API, the window manager generates the permission deny error.
Parameters:
[in]windowThe EFL window
[in]modeThe screen mode
Returns:
0 on success, otherwise a negative error value
Return values:
EFL_UTIL_ERROR_NONESuccessful
EFL_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
EFL_UTIL_ERROR_PERMISSION_DENIEDPermission denied

Registers a callback function to be invoked when an error which set the screen mode.

Deprecated:
Deprecated since 3.0. Use the return value of efl_util_set_window_screen_mode() instead.
Since :
2.4
Remarks:
An application can check error by the return value of efl_util_set_window_screen_mode since 3.0.
Parameters:
[in]windowThe EFL window
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
EFL_UTIL_ERROR_NONESuccessful
EFL_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
EFL_UTIL_ERROR_OUT_OF_MEMORYOut of memory
Postcondition:
efl_util_window_screen_mode_error_cb() will be invoked.
See also:
efl_util_unset_window_screen_mode_error_cb()
efl_util_window_screen_mode_error_cb()

Unregisters the callback function.

Deprecated:
Deprecated since 3.0. Use the return value of efl_util_set_notification_window_level() instead.
Since :
2.3.1
Remarks:
An application can check error by the return value of efl_util_set_notification_window_level since 3.0.
Parameters:
[in]windowThe EFL window
Returns:
0 on success, otherwise a negative error value
Return values:
EFL_UTIL_ERROR_NONESuccessful
EFL_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
efl_util_set_notification_window_level_error_cb()

Unregisters the callback function.

Deprecated:
Deprecated since 3.0. Use the return value of efl_util_set_window_screen_mode() instead.
Since :
2.4
Remarks:
An application can check error by the return value of efl_util_set_window_screen_mode since 3.0.
Parameters:
[in]windowThe EFL window
Returns:
0 on success, otherwise a negative error value
Return values:
EFL_UTIL_ERROR_NONESuccessful
EFL_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
efl_util_set_window_screen_mode_error_cb()