/**
* @brief Enumeration for the available display rotation states.
- * * @since_tizen 7.0
+ * @since_tizen 7.0
*/
typedef enum
/**
* @brief Enumeration for the display initial direction.
- * Initial direction means the display direction of degree 0.
+ * Initial direction means the display direction of degree @c 0.
* @since_tizen 7.0
*/
typedef enum
/**
- * @brief Gets the display brightness value.
+ * @brief Gets the brightness value of a specific display device based on its state.
+ * @details The display device is identified by its index, which can be obtained using the device_get_display_numbers() function.\n
+ * The desired display state is specified in the @a state parameter, and the brightness level is returned in the @a brightness parameter.
* @since_tizen 5.0
* @privlevel public
* @privilege %http://tizen.org/privilege/display
+ * @remarks Ensure that the provided @a brightness pointer is valid and has enough memory allocated.
* @param[in] display_index The index of the display \n
* It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
* The index zero is always assigned to the main display
* @param[out] brightness The current brightness value of the display
* @param[in] state The enum value of the display state \n
- * @return @c 0 on success,
- * otherwise a negative error value
+ * - @c DISPLAY_STATE_NORMAL: Normal state \n
+ * - @c DISPLAY_STATE_DIM: Screen Dim state \n
+ * - @c DISPLAY_STATE_OFF: Screen Off state
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
- * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported in this device
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
- * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_OPERATION_FAILED Operation not permitted
+ * @code
+ * #include <device/display-internal.h>
+ * ...
+ * int number_of_display = 0, brightness = 0, display_index = 0;
+ * display_state_e display_state = DISPLAY_STATE_NORMAL;
+ * int ret = 0;
+ * ...
+ * ret = device_get_display_numbers(&number_of_display);
+ * if (ret == DEVICE_ERROR_NONE) {
+ * display_index = number_of_display - 1;
+ * device_display_get_brightness_state(display_index, display_state, &brightness);
+ * ...
+ * }
+ * ...
+ * @endcode
* @see device_display_get_numbers()
* @see device_display_set_brightness_state()
* @see device_display_get_max_brightness_state()
/**
- * @brief Gets the maximum brightness value that can be set.
+ * @brief Gets the maximum brightness value of a specific display device based on its state that can be set.
+ * @details The display device is identified by its index, which can be obtained using the device_get_display_numbers() function.\n
+ * The desired display state is specified in the @a state parameter, and the max_brightness level is returned in the @a brightness parameter.
* @since_tizen 5.0
* @privlevel public
* @privilege %http://tizen.org/privilege/display
+ * @remarks Ensure that the provided @a brightness pointer is valid and has enough memory allocated.
* @param[in] display_index The index of the display \n
* It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
* The index zero is always assigned to the main display
* @param[out] max_brightness The maximum brightness value of the display
* @param[in] state The enum value of the display state \n
- * @return @c 0 on success,
- * otherwise a negative error value
+ * - @c DISPLAY_STATE_NORMAL: Normal state \n
+ * - @c DISPLAY_STATE_DIM: Screen Dim state \n
+ * - @c DISPLAY_STATE_OFF: Screen Off state
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
- * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported in this device
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
- * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_OPERATION_FAILED Operation not permitted
+ * @code
+ * #include <device/display-internal.h>
+ * ...
+ * int number_of_display = 0, max_brightness = 0, display_index = 0;
+ * display_state_e display_state = DISPLAY_STATE_NORMAL;
+ * int ret = 0;
+ * ...
+ * ret = device_get_display_numbers(&number_of_display);
+ * if (ret == DEVICE_ERROR_NONE) {
+ * display_index = number_of_display - 1;
+ * device_display_get_max_brightness_state(display_index, display_state, &max_brightness);
+ * ...
+ * }
+ * ...
+ * @endcode
* @see device_display_get_numbers()
* @see device_display_get_brightness_state()
* @see device_display_set_brightness_state()
/**
- * @brief Sets the display brightness value.
+ * @brief Sets the brightness value to a specific display device based on its state.
+ * @details The display device is identified by its index, which can be obtained using the device_get_display_numbers() function.
+ * The desired display state is specified in the @a state parameter, and the desired brightness level is specified in the @a brightness parameter.
* @since_tizen 5.0
* @privlevel public
* @privilege %http://tizen.org/privilege/display
+ * @remarks Ensure that the provided @a display_index, @a state, and @a brightness are valid values.
* @param[in] display_index The index of the display \n
* It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
* The index zero is always assigned to the main display
* @param[in] brightness The new brightness value to set \n
* The maximum value can be represented by device_display_get_max_brightness_state()
* @param[in] state The enum value of the display state \n
- * @return @c 0 on success,
- * otherwise a negative error value
+ * - @c DISPLAY_STATE_NORMAL: Normal state \n
+ * - @c DISPLAY_STATE_DIM: Screen Dim state \n
+ * - @c DISPLAY_STATE_OFF: Screen Off state
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
- * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported in this device
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
- * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_OPERATION_FAILED Operation not permitted
+ * @code
+ * #include <device/display-internal.h>
+ * ...
+ * int number_of_display = 0, brightness = 100, display_index = 0;
+ * display_state_e display_state = DISPLAY_STATE_NORMAL;
+ * int ret = 0;
+ * ...
+ * ret = device_get_display_numbers(&number_of_display);
+ * if (ret == DEVICE_ERROR_NONE) {
+ * display_index = number_of_display - 1;
+ * device_display_set_brightness_state(display_index, display_state, brightness);
+ * ...
+ * }
+ * ...
+ * @endcode
* @see device_display_get_numbers()
* @see device_display_get_max_brightness()
* @see device_display_set_brightness_state()
int device_display_set_brightness_state(int display_index, display_state_e state, int brightness);
/**
- * @brief Change display state by a specific reason
+ * @brief Changes the display state based on a specific reason.
+ * @details The desired display state is specified in the type parameter, and the reason for changing the display state is specified in the reason parameter.
* @since_tizen 5.0
* @privlevel public
* @privilege %http://tizen.org/privilege/display
+ * @remarks @a type parameter value cannot be DISPLAY_STATE_SCREEN_DIM, it is invalid.
* @param[in] type The type is display state to change\n
* DISPLAY_STATE_NORMAL : change to normal\n
* DISPLAY_STATE_SCREEN_OFF: change to off\n
* @param[in] reason Reason that causes display chage state\n
+ * It should be one of @c "palm", @c "gesture" or @c "event"
* @param[in] timeout Timeout to change state\n
* @param[in] cb Callback function for handling result of dbus method call\n
- * @return @c 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * #include <device/display-internal.h>
+ * ...
+ * void dbus_cb(GVariant *result, void *data, GError *err)
+ * {
+ * int temp = 0;
+ *
+ * if (!result) {
+ * _E("Can't get result of display state change request.:%s", err->message);
+ * return;
+ * }
+ * if (!g_variant_get_safe(result, "(i)", &temp)) {
+ * _E("Failed to get variant(%s): no call back message", g_variant_get_type_string(result));
+ * goto out;
+ * }
+ * _I("replay message(%d)", temp);
+ * out:
+ * g_variant_unref(result);
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = 0;
+ *
+ * ret = device_display_change_state_by_reason(DISPLAY_STATE_SCREEN_OFF, "palm", 0, dbus_cb);
+ * ...
+ * return 0;
+ * }
+ * ...
+ * @endcode
* @see device_display_change_state_by_reason()
*/
int device_display_change_state_by_reason(display_state_e type, const char *reason, int timeout, dbus_pending_cb cb);
/**
* @platform
- * @brief Check display feature(http://tizen.org/feature/display)
+ * @brief Checks whether the current device's display feature is supported.
+ * @details Checks whether the display feature is supported on the device.\n
+ * The display feature refers to the ability of the device to control the display settings and related properties.
* @since_tizen 6.5
- * @return @c 1 if it is supported,
- * otherwise 0
+ * @remarks Checks the display feature(http://tizen.org/feature/display) value.
+ * @return @c 1 if the display feature is supported, otherwise @c 0
+ * @code
+ * #include <device/display-internal.h>
+ * ...
+ * int ret = 0;
+ * ret = is_feature_display_supported();
+ * if (!ret) {
+ * _E("display feature is not supported");
+ * ...
+ * }
+ * ...
+ * @endcode
*/
int is_feature_display_supported(void);
/**
- * @brief Get display rotation angle
+ * @brief Gets the rotation angle and initial direction of a specific display device.
+ * @details The display device is identified by its index, which can be obtained using the device_get_display_numbers().
+ * The rotation angle is returned in the @a angle parameter,
+ * and the initial direction is returned in the @a init_direction parameter.
* @since_tizen 7.0
* @privilege %http://tizen.org/privilege/display
- * @remarks It shows the physical display angle, not SW screen angle.
+ * @remarks It shows the physical display angle, not the software screen angle.
* @param[in] display_index The index of the display \n
* It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
* The index zero is always assigned to the main display
* DEVICE_DISPLAY_ROTATION_ANGLE_DEGREE_180\n
* DEVICE_DISPLAY_ROTATION_ANGLE_DEGREE_270\n
* @param[out] init_direction The type is display initial direction
- * When the rotation angle is 0 degree, initial direction means the display is a horizontal or vertical.\n
+ * When the rotation angle is @c 0 degree, initial direction means the display is a horizontal or vertical.\n
* DEVICE_DISPLAY_INIT_DIRECTION_HORIZONTAL\n
* DEVICE_DISPLAY_INIT_DIRECTION_VERTICAL\n
- * @return @c 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
- * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported in this device
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
- * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_OPERATION_FAILED Operation not permitted
+ * @code
+ * #include <stdio.h>
+ * #include <device/display.h>
+ * ...
+ * int main(void)
+ * {
+ * int display_index = 0;
+ * device_display_rotation_angle_e angle;
+ * device_display_init_direction_e init_direction;
+ * int ret = 0;
+ * ...
+ * ret = device_display_get_rotation_angle(display_index, &angle, &init_direction);
+ * if (ret == DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * return 0;
+ * }
+ * ...
+ * @endcode
+ * @see device_display_set_rotation_angle()
+ * @see device_display_rotation_angle_e
+ * @see device_display_init_direction_e
*/
int device_display_get_rotation_angle(int display_index,
device_display_rotation_angle_e *angle,
device_display_init_direction_e *init_direction);
/**
- * @brief Set display rotation angle
+ * @brief Sets the rotation angle and initial direction of a specific display device.
+ * @details The display device is identified by its index, which can be obtained using the device_get_display_numbers() function.
+ * The desired rotation angle is specified in the @a angle parameter, and the desired rotation direction is specified in the @a rotation_direction parameter.
* @since_tizen 7.0
* @privilege %http://tizen.org/privilege/display
- * @remarks It shows the physical display angle, not SW screen angle.
+ * @remarks It shows the physical display angle, not the software screen angle.
* It is function to set specific fixed angle, not for additional turning.
* For example, when this function called with same angle twice, there will be no actual action on the second call.
* @param[in] display_index The index of the display \n
* @param[in] rotation_direction The type is display rotation direction\n
* DEVICE_DISPLAY_ROTATION_DIRECTION_CLOCKWISE\n
* DEVICE_DISPLAY_ROTATION_DIRECTION_COUNTER_CLOCKWISE\n
- * @return @c 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
- * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported in this device
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
- * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_OPERATION_FAILED Operation not permitted
+ * @code
+ * #include <stdio.h>
+ * #include <device/display.h>
+ * ...
+ * int main(void)
+ * {
+ * int display_index = 0;
+ * device_display_rotation_angle_e angle = DEVICE_DISPLAY_ROTATION_ANGLE_DEGREE_90;
+ * device_display_rotation_direction_e rotation_direction = DEVICE_DISPLAY_ROTATION_DIRECTION_CLOCKWISE;
+ * int ret = 0;
+ * ...
+ * ret = device_display_set_rotation_angle(display_index, angle, rotation_direction);
+ * if (ret == DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * return 0;
+ * }
+ * ...
+ * @endcode
+ * @see device_display_get_rotation_angle()
+ * @see device_display_rotation_angle_e
+ * @see device_display_rotation_direction_e
*/
int device_display_set_rotation_angle(int display_index,
device_display_rotation_angle_e angle,
/**
* @platform
- * @brief Check display state feature(http://tizen.org/feature/display.state)
+ * @brief Checks whether the current device's display state feature is supported.
+ * @details Checks whether the display state feature is supported on the device.\n
+ * The display state feature refers to the ability of the device to control the display state related properties.
* @since_tizen 6.5
- * @return @c 1 if it is supported,
- * otherwise 0
+ * @remarks Checks the display state feature(http://tizen.org/feature/display.state) value.
+ * @return @c 1 if the display state feature is supported, otherwise @c 0
+ * @code
+ * #include <device/display-internal.h>
+ * ...
+ * int ret = 0;
+ * ret = is_feature_display_state_supported();
+ * if (!ret) {
+ * _E("display state feature is not supported");
+ * ...
+ * }
+ * ...
+ * @endcode
*/
int is_feature_display_state_supported(void);
/**
- * @brief Change display white balance value.
+ * @brief Change display white balance value from the display HAL module
+ * @details The @a white_balance_type parameter and @a value is used to calucate the reference value for white.
* @since_tizen 7.0
* @privlevel 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 \n
* @param[in] display_index The index of the display \n
-* It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
-* The index zero is always assigned to the main display
+ * It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
+ * The index zero is always assigned to the main display
* @param[in] white_balance_type The type to adjust white balance value
- * @param[in] value The value to be set for white balance type
- * @return @c 0 on success,
- * otherwise a negative error value
+ * DISPLAY_WHITE_BALANCE_R_GAIN \n
+ * DISPLAY_WHITE_BALANCE_G_GAIN \n
+ * DISPLAY_WHITE_BALANCE_B_GAIN \n
+ * DISPLAY_WHITE_BALANCE_R_OFFSET \n
+ * DISPLAY_WHITE_BALANCE_G_OFFSET \n
+ * DISPLAY_WHITE_BALANCE_B_OFFSET
+ * @param[in] value The value to be set for @a white_balance_type \n
+ * It's range is (@c 0 ~ @c 2047)
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
- * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported in this device
- * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
+ * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #include <device/display-internal.h>
+ * ...
+ * int ret = 0;
+ * ret = device_display_set_white_balance(DEVICE_WHITE_BALANCE_R_GAIN, 1024);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * ...
+ * ret = device_display_set_white_balance(DEVICE_WHITE_BALANCE_R_OFFSET, 1024);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * ...
+ * @endcode
* @see device_display_get_numbers()
+ * @see device_display_get_white_balance()
+ * @see display_white_balance_e
*/
int device_display_set_white_balance(int display_index, display_white_balance_e white_balance_type, int value);
/**
- * @brief Get display white balance value.
+ * @brief Gets display white balance value based on @a white_balance_type from the display HAL module.
+ * @details The @a white_balance_type parameter and @a value is used to calucate the reference value for white.
* @since_tizen 7.0
* @privlevel public
* @privilege %http://tizen.org/privilege/display
* @param[in] display_index The index of the display \n
* It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
* The index zero is always assigned to the main display
- * @param[in] white_balance_type The type to get current white balance value
- * @param[out] value The white balance type value of the display
+ * @param[in] white_balance_type The type to adjust white balance value
+ * DISPLAY_WHITE_BALANCE_R_GAIN \n
+ * DISPLAY_WHITE_BALANCE_G_GAIN \n
+ * DISPLAY_WHITE_BALANCE_B_GAIN \n
+ * DISPLAY_WHITE_BALANCE_R_OFFSET \n
+ * DISPLAY_WHITE_BALANCE_G_OFFSET \n
+ * DISPLAY_WHITE_BALANCE_B_OFFSET
+ * @param[out] value The value to be set for @a white_balance_type \n
+ * It's range is (@c 0 ~ @c 2047)
* @return @c 0 on success,
* otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation not permitted
+ * @code
+ * #include <device/display-internal.h>
+ * ...
+ * int ret = 0, r_gain_value = 0, r_offset_value = 0;
+ * ret = device_display_get_white_balance(DEVICE_WHITE_BALANCE_R_GAIN, &r_gain_value);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * ...
+ * ret = device_display_get_white_balance(DEVICE_WHITE_BALANCE_R_OFFSET, &r_offset_value);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * ...
+ * @endcode
* @see device_display_get_numbers()
+ * @see device_display_set_white_balance()
+ * @see display_white_balance_e
*/
int device_display_get_white_balance(int display_index, display_white_balance_e white_balance_type, int *value);
/**
- * @brief Gets the number of display devices.
+ * @brief Gets the number of display devices connected to current device.
+ * @details Retrieves the number of display devices connected to the system.\n
+ * The number of displays is returned in the @a device_number parameter.
* @since_tizen 2.3
* @privlevel 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
- * @param[out] device_number The total number of displays
- * @return @c 0 on success,
- * otherwise a negative error value
+ * @param[out] device_number A pointer to an integer where the total number of displays will be stored
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
* @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #include <device/display.h>
+ * ...
+ * int number_of_display = 0;
+ * int ret = 0;
+ * ...
+ * ret = device_display_get_numbers(&number_of_display);
+ * ...
+ * @endcode
* @see device_display_get_brightness()
* @see device_display_set_brightness()
* @see device_display_get_max_brightness()
/**
- * @brief Gets the maximum brightness value that can be set.
+ * @brief Gets the maximum brightness value that can be set based on the display index.
+ * @details Retrieves the maximum brightness level of a specific display device.\n
+ * The display device is identified by its index, which can be obtained using the device_get_display_numbers() function.\n
+ * The maximum brightness level is returned in the @a max_brightness parameter.
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/display
* It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
* The index zero is always assigned to the main display
* @param[out] max_brightness The maximum brightness value of the display
- * @return @c 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
* @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #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);
+ * ...
+ * }
+ * ...
+ * @endcode
* @see device_display_get_numbers()
* @see device_display_set_brightness()
* @see device_display_get_brightness()
/**
- * @brief Gets the display brightness value.
+ * @brief Gets the display brightness value based on the display index.
+ * @details Retrieves the current brightness level of a specific display device.\n
+ * The display device is identified by its index, which can be obtained using the device_get_display_numbers().
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/display
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
* @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #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);
+ * ...
+ * }
+ * ...
+ * @endcode
* @see device_display_get_numbers()
* @see device_display_set_brightness()
* @see device_display_get_max_brightness()
/**
- * @brief Sets the display brightness value.
+ * @brief Sets the display brightness value based on the display index.
+ * @details Sets the brightness level of a specific display device.\n
+ * The display device is identified by its index, which can be obtained using the device_get_display_numbers().
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/display
* The index zero is always assigned to the main display
* @param[in] brightness The new brightness value to set \n
* The maximum value can be represented by device_display_get_max_brightness()
- * @return @c 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
* @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #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);
+ * ...
+ * }
+ * ...
+ * @endcode
* @see device_display_get_numbers()
* @see device_display_get_max_brightness()
* @see device_display_get_brightness()
/**
- * @brief Gets the current display state.
+ * @brief Gets the current device's display state, including normal, dim, and off states.
+ * @details Gets the current state of the display.\n
+ * The current display state is returned in the @a state parameter.
* @since_tizen 2.3
* @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: %http://tizen.org/feature/display
* @param[out] state The display state
- * @return @c 0 on success,
- * otherwise a negative error value
+ * - DISPLAY_STATE_NORMAL: The normal display state.\n
+ * - DISPLAY_STATE_DIM: The dimmed display state.\n
+ * - DISPLAY_STATE_OFF: The off display state.
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
* @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #include <system/device.h>
+ * ...
+ * display_state_e state;
+ * int ret = 0;
+ * ...
+ * ret = device_display_get_state(&state);
+ * if (ret == DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * ...
+ * @endcode
* @see device_add_callback
* @see device_remove_callback
* @see #DEVICE_CALLBACK_DISPLAY_STATE
/**
- * @brief Changes the display state by force.
+ * @brief Changes the current device's display state to the specified state by force.
+ * @details It should be checked the profile version and supported display state.
* @since_tizen 2.3
* @privlevel 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.
* @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: %http://tizen.org/feature/display.state.
* @param[in] state The display state
- * @return @c 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
* @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
- * @see device_power_request_lock()
- * @see device_power_release_lock()
- * @see device_add_callback
- * @see device_remove_callback
- * @see #DEVICE_CALLBACK_DISPLAY_STATE
- *
* @par Example
* @code
* ...
* dlog_print(DLOG_DEBUG, LOG_TAG, "[SUCCESS] return value result =%d \n",result);
* ...
* @endcode
+ * @see device_power_request_lock()
+ * @see device_power_release_lock()
+ * @see device_add_callback
+ * @see device_remove_callback
+ * @see #DEVICE_CALLBACK_DISPLAY_STATE
*/
int device_display_change_state(display_state_e state);
projects / platform / core / api / device.git / commitdiff