X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFSysVibrator.h;h=c29f1208ceaf3eb061fa52847cfbbf2053fa2e18;hb=f6fe22fddce04f1e48556cc2e3219b292117d91f;hp=526305fe4b011d8ede9780d2912e6161e0d9f47c;hpb=b9b4f497f831de4a8bf597718a45f3b104c90586;p=platform%2Fframework%2Fnative%2Fappfw.git diff --git a/inc/FSysVibrator.h b/inc/FSysVibrator.h index 526305f..c29f120 100644 --- a/inc/FSysVibrator.h +++ b/inc/FSysVibrator.h @@ -1,5 +1,4 @@ // -// Open Service Platform // Copyright (c) 2012 Samsung Electronics Co., Ltd. // // Licensed under the Apache License, Version 2.0 (the License); @@ -36,7 +35,7 @@ namespace Tizen { namespace System * * @since 2.0 * - * The %Vibrator class handles the vibration functionality of a device. It allows you to manage the device's vibrator parameters, such as vibration count and level. + * The %Vibrator class handles the vibration functionality of a device. It allows the management of the device's vibrator parameters, such as the vibration count and level. * * For more information on the class features, see Vibrator Management. * @@ -67,11 +66,11 @@ namespace Tizen { namespace System * goto CATCH; * } * - * // Initialize vibration pattern + * // Initializes the vibration pattern * IntensityDurationVibrationPattern patterns[4] = {{2000, 50}, {1000, 0}, {500, -1}, {1000, 80}}; * int length = sizeof(patterns); - * // Vibrate with a given pattern and repeat count + * // Vibrates with a given pattern and repeats count * vibrator.Start(patterns, length, 3); * * return E_SUCCESS; @@ -85,23 +84,23 @@ namespace Tizen { namespace System /** * @struct IntensityDurationVibrationPattern - * @brief This struct has the specified duration and a vibration intensity level. + * @brief This struct represents the specified duration and vibration intensity level. * - * This can be used with Vibrator::Start(IntensityDurationVibrationPattern[] patterns, int length, int repeatCount) as a custom pattern. + * The %IntensityDurationVibrationPattern struct represents the specified duration and vibration intensity level. This struct can be used with Vibrator::Start(IntensityDurationVibrationPattern[] patterns, int length, int repeatCount) as a custom pattern. * * @since 2.1 */ struct _OSP_EXPORT_ IntensityDurationVibrationPattern { - int duration; /**< The duration in milliseconds when the vibrator is on. @n - * The @c duration is not allowed a negative value. - */ + int duration; /**< The duration in milliseconds when the vibrator is on @n + * The @c duration does not allow a negative value. + */ int intensity; /**< The vibration intensity [@c -1~ @c 100]: @n - * @li The system default vibration intensity (-1) - * @li The silent vibration intensity (0) - * @li The minimum vibration intensity (1) - * @li The maximum vibration intensity (100) - */ + * @li The system default vibration intensity (-1) + * @li The silent vibration intensity (0) + * @li The minimum vibration intensity (1) + * @li The maximum vibration intensity (100) + */ }; @@ -111,11 +110,11 @@ class _OSP_EXPORT_ Vibrator public: /** - * This is the default constructor for this class. - * + * This is the default constructor for this class. @n + * The object is not fully constructed after this constructor is called. + * For full construction, the Construct() method must be called right after calling this constructor. * @since 2.0 * - * @remarks The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor. */ Vibrator(void); @@ -143,27 +142,28 @@ public: /** - * Vibrates the device with the specified array pattern which has vibration intensity and duration. @n - * This method returns the result immediately so that the vibration occurs simultaneously as the device runs. @n - * If this method is called again before the previous vibration stops, the previous vibration is canceled and the new vibration starts immediately. @n + * Vibrates the device with a specified array pattern that has a vibration intensity and duration. @n + * The %Start() method returns the result immediately so that the vibration occurs simultaneously as the device runs. @n + * If this method is called again before the previous vibration stops, the previous vibration is cancelled and the new vibration starts immediately. @n * If a new vibrator instance triggers the vibration, the vibrator merges the previous vibration pattern with the new one in the overlapped time. @n - * If the system alert occurs such as ring vibration and a system event notification, the vibration can be interrupted. @n - * If the application is terminated, the vibration is canceled. + * If a system alert occurs such as a ring vibration or a system event notification, the vibration can be interrupted. @n + * If the application is terminated, the vibration is cancelled. * * @since 2.1 - * - * @privilege %http://tizen.org/privilege/vibrator + * @privlevel public + * @privilege %http://tizen.org/privilege/vibrator * * @return An error code * - * @param[in] patterns An array of @c IntensityDurationVibrationPattern. - * @param[in] length The length of @c patterns. - * @param[in] repeatCount The number of repeat for pattern. This value has to be between 1 to 100. - * @exception E_SUCCESS The method is successful. + * @param[in] patterns The array of @c IntensityDurationVibrationPattern + * @param[in] length The length of @c patterns + * @param[in] repeatCount The number of times the pattern repeats @n + * This value must be between @c 1 to @c 100. + * @exception E_SUCCESS The method is successful. * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. - * @exception E_INVALID_ARG A specified input parameter is invalid. - * @exception E_OPERATION_FAILED The device operation has failed. - * @remarks The vibration intensity does not apply the change, even if the system default vibration intensity is changed after starting vibration. + * @exception E_INVALID_ARG A specified input parameter is invalid. + * @exception E_OPERATION_FAILED The device operation has failed. + * @remarks The vibration intensity does not apply the change, even if the system default vibration intensity is changed after starting the vibration. * @see IntensityDurationVibrationPattern */ result Start(IntensityDurationVibrationPattern* patterns, int length, int repeatCount = 1); @@ -171,63 +171,66 @@ public: /** * Vibrates the device with the specified pattern and level. @n * The %Start() method returns the result immediately so that the vibration occurs simultaneously as the device runs. - * If this method is called again before the previous vibration stops, the previous vibration is canceled and the new vibration starts immediately. + * If this method is called again before the previous vibration stops, the previous vibration is cancelled and the new vibration starts immediately. * + * @brief [Deprecated] + * @deprecated This method is deprecated. Instead of using this method, use Start(IntensityDurationVibrationPattern*, int, int). * @since 2.0 - * - * @deprecated This method is deprecated. Instead of using this method, use Start(IntensityDurationVibrationPattern[] patterns, int length, int repeatCount). - * * @privlevel public * @privilege %http://tizen.org/privilege/vibrator * * @return An error code - * @param[in] onPeriod The period in milliseconds when the vibrator is on @n - * It should be greater than @c 0. - * @param[in] offPeriod The period in milliseconds when the vibrator is off @n - * It should be equal to or greater than @c 0. - * @param[in] count The number of times to execute the given pattern @n - * It should be greater than @c 0. - * @param[in] level The vibration level @n - * Ranges from [@c 0~ @c 100], where '@c 0' is a special case indicating the system default level. + * @param[in] onPeriod The period in milliseconds when the vibrator is on @n + * It should be greater than @c 0. + * @param[in] offPeriod The period in milliseconds when the vibrator is off @n + * It should be equal to or greater than @c 0. + * @param[in] count The number of times to execute the given pattern @n + * It should be greater than @c 0. + * @param[in] level The vibration level @n + * It ranges from [@c 0~ @c 100], where '@c 0' is a special case indicating the system default level. * @exception E_SUCCESS The method is successful. * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. * @exception E_INVALID_ARG A specified input parameter is invalid. * @exception E_DEVICE_BUSY The device cannot be approached because of other operations. * @exception E_DEVICE_FAILED The device operation has failed. - * @remarks Various devices may have different vibration capabilities. - * If the device supports only one level of vibration, then a level value between [@c 0~ @c 100] results in the default vibration. - * If the device supports many levels of vibration, then a level value @c 0 results in the system default vibration, value @c 1 results in the lowest frequency vibration, value @c 100 results in the highest frequency vibration, and intermediate values result in intermediate vibration levels. @n - * Devices have implementation-specific limits for the total duration of the vibration, and vibration cuts off at that limit even if the duration parameter is greater than the limit. + * @remarks Various devices may have different vibration capabilities. @n + * If the device supports only one level of vibration, then a level value between [@c 0~ @c 100] results in the default vibration. @n + * If the device supports many levels of vibration, then a level value @c 0 results in the system default vibration, + * value @c 1 results in the lowest frequency vibration, value @c 100 results in the highest frequency vibration, and intermediate values result in + * intermediate vibration levels. @n + * Devices have implementation-specific limits for the total duration of the vibration, and vibration cuts off at that limit even if the duration parameter is + * greater than the limit. * */ result Start(long onPeriod, long offPeriod, int count, int level = 0); /** - * Vibrates the device for the specified duration at the specified @c level. @n + * Vibrates the device for the specified duration at the specified level. @n * The %Start() method returns the result immediately so that the vibration occurs simultaneously as the device runs. - * If this method is called again before the previous vibration stops, the previous vibration is canceled and the new vibration starts immediately. + * If this method is called again before the previous vibration stops, the previous vibration is cancelled and the new vibration starts immediately. * + * @brief [Deprecated] + * @deprecated This method is deprecated. Instead of using this method, use Start(IntensityDurationVibrationPattern*, int, int). * @since 2.0 - * - * @deprecated This method is deprecated. Instead of using this method, use Start(IntensityDurationVibrationPattern[] patterns, int length, int repeatCount). - * * @privlevel public * @privilege %http://tizen.org/privilege/vibrator * * @return An error code - * @param[in] milliseconds The duration for the vibration in milliseconds @n - * It should be greater than @c 0. - * @param[in] level The vibration level @n - * Ranges from [@c 0~ @c 100], where ' @c 0' is a special case indicating the system default level. - * @exception E_SUCCESS The method is successful. + * @param[in] milliseconds The duration for the vibration in milliseconds @n + * It should be greater than @c 0. + * @param[in] level The vibration level @n + * It ranges from [@c 0~ @c 100], where ' @c 0' is a special case indicating the system default level. + * @exception E_SUCCESS The method is successful. * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. * @exception E_INVALID_ARG A specified input parameter is invalid. * @exception E_DEVICE_BUSY The device cannot be approached because of other operations. * @exception E_DEVICE_FAILED The device operation has failed. * @remarks Various devices have different vibration capabilities. @n - * If the device supports only one level of vibration, then a level value between [@c 0~ @c 100] results in the default vibration. - * If the device supports many levels of vibration, then a level value @c 0 results in the system default vibration, value @c 1 results in the lowest frequency vibration, value @c 100 results in the highest frequency vibration, and intermediate values result in intermediate vibration levels. @n - * Devices have implementation-specific limits for the total duration of the vibration, and vibration cuts off at that limit even if the duration parameter is greater than the limit. + * If the device supports only one level of vibration, then a level value between [@c 0~ @c 100] results in the default vibration. @n + * If the device supports many levels of vibration, then a level value @c 0 results in the system default vibration, value @c 1 results in the lowest + * frequency vibration, value @c 100 results in the highest frequency vibration, and intermediate values result in intermediate vibration levels. @n + * Devices have implementation-specific limits for the total duration of the vibration, and vibration cuts off at that limit even if the duration parameter is + * greater than the limit. * */ result Start(long milliseconds, int level = 0); @@ -235,8 +238,7 @@ public: /** * Turns the vibrator off. * - * @since 2.0 - * + * @since 2.0 * @privlevel public * @privilege %http://tizen.org/privilege/vibrator *