The Display API provides functions to control the display status.

Required Header

#include <device/display.h>
#include <device/callback.h>

Overview

The Display API provides the way to get supported display count and the display brightness. It also supports the API to set the display brightness. Application can receive the display event by callback function from the system.

Related Features

This API is related with the following features:

http://tizen.org/feature/display
http://tizen.org/feature/display.state

It is recommended to design feature related codes in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from feature element description.

Functions
int	device_display_get_numbers (int *device_number)
	Gets the number of display devices connected to current device.
int	device_display_get_max_brightness (int display_index, int *max_brightness)
	Gets the maximum brightness value that can be set based on the display index.
int	device_display_get_brightness (int display_index, int *brightness)
	Gets the display brightness value based on the display index.
int	device_display_set_brightness (int display_index, int brightness)
	Sets the display brightness value based on the display index.
int	device_display_get_state (display_state_e *state)
	Gets the current device's display state, including normal, dim, and off states.
int	device_display_change_state (display_state_e state)
	Changes the current device's display state to the specified state by force.

Enumeration Type Documentation

enum display_state_e

Enumeration for the available display states.

Since :: 2.3

Remarks:: DISPLAY_STATE_SCREEN_DIM may be ignored if the DIM state is disabled on the platform.

Enumerator:

DISPLAY_STATE_NORMAL	Normal state
DISPLAY_STATE_SCREEN_DIM	Screen dim state
DISPLAY_STATE_SCREEN_OFF	Screen off state

Function Documentation

int device_display_change_state ( display_state_e state )

Changes the current device's display state to the specified state by force.

It should be checked the profile version and supported display state.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/display

Remarks:: This API triggers display change process and then updates the status when it completes. While the operation is on-going, the device_display_get_state() function returns previous display state.; DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: http://tizen.org/feature/display.state.

Parameters:

[in] state The display state

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_PERMISSION_DENIED	Permission denied
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device

Example

  ...
  result = device_display_change_state(DISPLAY_STATE_SCREEN_OFF);
  if (result < 0)
      dlog_print(DLOG_ERROR, LOG_TAG, "[ERROR] return value result =%d, \n",result);
  else
      dlog_print(DLOG_DEBUG, LOG_TAG, "[SUCCESS] return value result =%d \n",result);
  ...

See also:: device_power_request_lock(); device_power_release_lock(); device_add_callback; device_remove_callback; DEVICE_CALLBACK_DISPLAY_STATE

int device_display_get_brightness	(	int	display_index,
		int *	brightness
	)

Gets the display brightness value based on the display index.

Retrieves the current brightness level of a specific display device.
The display device is identified by its index, which can be obtained using the device_get_display_numbers().

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/display

Remarks:: DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: http://tizen.org/feature/display
or when the display HW module (e.g., plug-in touchscreen) is detached.

Parameters:

[in]	display_index	The index of the display It can be greater than or equal to `0` and less than the number of displays returned by device_display_get_numbers(). The index zero is always assigned to the main display
[out]	brightness	The current brightness value of the display

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_PERMISSION_DENIED	Permission denied
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device #include <device/display.h> ... int number_of_display = 0, brightness = 0, display_index = 0; int ret = 0; ... ret = device_display_get_numbers(&number_of_display); if (ret == DEVICE_ERROR_NONE) { display_index = number_of_display - 1; device_display_get_brightness(display_index, &brightness); ... } ...

See also:: device_display_get_numbers(); device_display_set_brightness(); device_display_get_max_brightness()

int device_display_get_max_brightness	(	int	display_index,
		int *	max_brightness
	)

Gets the maximum brightness value that can be set based on the display index.

Retrieves the maximum brightness level of a specific display device.
The display device is identified by its index, which can be obtained using the device_get_display_numbers() function.
The maximum brightness level is returned in the max_brightness parameter.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/display

Remarks:: DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: http://tizen.org/feature/display
or when the display HW module (e.g., plug-in touchscreen) is detached.

Parameters:

[in]	display_index	The index of the display It can be greater than or equal to `0` and less than the number of displays returned by device_display_get_numbers(). The index zero is always assigned to the main display
[out]	max_brightness	The maximum brightness value of the display

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_PERMISSION_DENIED	Permission denied
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device #include <device/display.h> ... int number_of_display = 0, brightness = 0, display_index = 0; int ret = 0; ... ret = device_display_get_numbers(&number_of_display); if (ret == DEVICE_ERROR_NONE) { display_index = number_of_display - 1; device_display_get_max_brightness(display_index, brightness); ... } ...

See also:: device_display_get_numbers(); device_display_set_brightness(); device_display_get_brightness()

int device_display_get_numbers ( int * device_number )

Gets the number of display devices connected to current device.

Retrieves the number of display devices connected to the system.
The number of displays is returned in the device_number parameter.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/display

Remarks:: DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: http://tizen.org/feature/display

Parameters:

[out] device_number A pointer to an integer where the total number of displays will be stored

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_PERMISSION_DENIED	Permission denied
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device #include <device/display.h> ... int number_of_display = 0; int ret = 0; ... ret = device_display_get_numbers(&number_of_display); ...

See also:: device_display_get_brightness(); device_display_set_brightness(); device_display_get_max_brightness()

int device_display_get_state ( display_state_e * state )

Gets the current device's display state, including normal, dim, and off states.

Gets the current state of the display.
The current display state is returned in the state parameter.

Since :: 2.3

Remarks:: DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: http://tizen.org/feature/display

Parameters:

[out]

state

The display state

DISPLAY_STATE_NORMAL: The normal display state.
DISPLAY_STATE_DIM: The dimmed display state.
DISPLAY_STATE_OFF: The off display state.

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device #include <system/device.h> ... display_state_e state; int ret = 0; ... ret = device_display_get_state(&state); if (ret == DEVICE_ERROR_NONE) { ... } ...

See also:: device_add_callback; device_remove_callback; DEVICE_CALLBACK_DISPLAY_STATE

int device_display_set_brightness	(	int	display_index,
		int	brightness
	)

Sets the display brightness value based on the display index.

Sets the brightness level of a specific display device.
The display device is identified by its index, which can be obtained using the device_get_display_numbers().

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/display

Remarks:: DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: http://tizen.org/feature/display
or when the display HW module (e.g., plug-in touchscreen) is detached.

Parameters:

[in]	display_index	The index of the display It can be greater than or equal to `0` and less than the number of displays returned by device_display_get_numbers(). The index zero is always assigned to the main display
[in]	brightness	The new brightness value to set The maximum value can be represented by device_display_get_max_brightness()

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_PERMISSION_DENIED	Permission denied
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device #include <system/device.h> ... int number_of_display = 0, brightness = 100, display_index = 0; int ret = 0; ... ret = device_display_get_numbers(&number_of_display); if (ret == DEVICE_ERROR_NONE) { display_index = number_of_display - 1; device_display_set_brightness(display_index, brightness); ... } ...

See also:: device_display_get_numbers(); device_display_get_max_brightness(); device_display_get_brightness()

Required Header

Overview

Related Features

Functions

Enumeration Type Documentation

Function Documentation