//
-// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
*
* @final This class is not intended for extension.
*
- * The %AppSetting class lets an application to save or restore its settings.
- *
- *
- * The following example demonstrates how to use the %AppSetting class.
- *
- * @code
- * void
- * AppSettingForm::RefreshSetting(void)
- * {
- * AppSetting* pAppSetting = AppSetting::GetInstance();
- * AppAssert(pAppSetting);
- *
- * bool valueBool = false;
- * int valueInt = 0;
- * const String strLn(L"\n");
- * String valueString;
- * String settingText;
- *
- * AppAssert(pAppSetting->GetValue(L"checkbox1", valueBool) == E_SUCCESS);
- * settingText += L"checkbox1: ";
- * settingText += strFalseTrue[valueBool ? 1 : 0];
- * settingText += strLn;
- *
- * AppAssert(pAppSetting->GetValue(L"slider1", valueInt) == E_SUCCESS);
- * settingText += L"slider1: ";
- * settingText += Integer(valueInt).ToString();
- * settingText += strLn;
- *
- * AppAssert(pAppSetting->GetValue(L"editbox1", valueString) == E_SUCCESS);
- * settingText += L"editbox1: ";
- * settingText += valueString;
- * settingText += strLn;
- * // . . .
- * }
- *
- * void
- * AppSettingForm::SetSettingValueSet1(void)
- * {
- * AppSetting* pAppSetting = AppSetting::GetInstance();
- * AppAssert(pAppSetting);
- *
- * AppAssert(pAppSetting->SetValue(L"checkbox1", false) == E_SUCCESS);
- * AppAssert(pAppSetting->SetValue(L"slider1", 100) == E_SUCCESS);
- * AppAssert(pAppSetting->SetValue(L"editbox1", String(L"AppSetting working!")) == E_SUCCESS);
- * AppAssert(pAppSetting->SetValue(L"expanditem1", String(L"1 minute")) == E_SUCCESS);
- * AppAssert(pAppSetting->SetValue(L"expanditem1", false) == E_SUCCESS);
- * AppAssert(pAppSetting->SetValue(L"slider2", 0) == E_SUCCESS);
- * AppAssert(pAppSetting->SetValue(L"editbox2", String(L"AppSetting running!")) == E_SUCCESS);
- * // . . .
- * }
- * @endcode
+ * The %AppSetting class is a helper class for an application to save or restore its settings.
+ * A setting entity is composed of a string-typed key and a value. The value type must only be of three types: @c int, @c bool, and @c String.
+ * The settings are pre-defined at setting/setting.xml in the application's base directory
+ * and they can be easily set with %Tizen IDE (<a href="../org.tizen.native.appprogramming/html/ide_sdk_tools/creating_running_app_setting.htm">Creating and Using Application Settings</a>, <a href="../org.tizen.native.appprogramming/html/ide_sdk_tools/application_settings_editor.htm">Application Settings Editor</a>).
+ * (setting.xml is a symbolic link to the currently used setting file, which is related to the current version of the application.) @n
+ * The %AppSetting class is basically used for specific applications which have no UI, such as IME.
+ * Because the applications have no external way to modify their settings, users can adjust the setting values through the setting application, which is delegated to manage the settings.
+ * For supporting the consistency between the setting values of two applications, that is, the target application and the setting application, the setting application notifies the target application through
+ * the IAppSettingEventListener::OnAppSettingChanged() method when setting a value.
*
+ * For a detailed example on the %AppSetting class, see <a href="../org.tizen.native.appprogramming/html/tutorials/app_tutorial/task_app_settings.htm?resultof=%22%41%70%70%53%65%74%74%69%6e%67%22%20%22%61%70%70%73%65%74%74%69%6e%67%22%20">Task: App Setting</a>.
+ *
+ * @see IAppSettingEventListener
*/
class _OSP_EXPORT_ AppSetting
: public Tizen::Base::Object
{
public:
/**
- * Gets the application setting instance.
+ * Gets the pointer to the %AppSetting instance.
*
* @since 2.0
*
- * @return A pointer to the %AppSetting instance, @n
+ * @return The pointer to the %AppSetting instance for the last setting, @n
* else @c null if it fails
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @remarks It returns an instance for the latest setting. @n
- * The specific error code can be accessed using the GetLastResult() method.
+ * @remarks The specific error code can be accessed using the GetLastResult() method.
*/
static AppSetting* GetInstance(void);
/**
- * Gets the application setting instance of the specified version.
+ * Gets the pointer to the %AppSetting instance of the specified version.
*
* @since 2.0
*
- * @return A pointer to the %AppSetting instance, @n
+ * @return The pointer to the %AppSetting instance, @n
* else @c null if it fails
- * @param[in] settingVersion The version of setting is retrieved from GetAppSettingVersionListN()
+ * @param[in] settingVersion The version of the setting which is retrieved from GetAppSettingVersionListN()
* @exception E_SUCCESS The method is successful.
- * @exception E_OBJ_NOT_FOUND The specified version is not found.
+ * @exception E_OBJ_NOT_FOUND The specified version has not been found.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
* @remarks The specific error code can be accessed using the GetLastResult() method.
- * @see GetAppSettingVersionListN()
*/
static AppSetting* GetInstance(const Tizen::Base::String& settingVersion);
/**
- * Gets the application setting instance of the specified AppId.
+ * Gets an %AppSetting instance of the specified ID.
*
* @since 2.0
*
- * @privlevel partner
+ * @privlevel platform
* @privilege %http://tizen.org/privilege/appsetting
*
* @return A pointer to the %AppSetting instance, @n
* else @c null if it fails
- * @param[in] appId The AppId of the application that has a valid application setting
+ * @param[in] appId The ID of the application that has a valid application setting
* @exception E_SUCCESS The method is successful.
- * @exception E_OBJ_NOT_FOUND The instance of specified AppId does not have setting information.
+ * @exception E_OBJ_NOT_FOUND The specified @c appId does not have the required setting information.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
* @exception E_INVALID_ARG The specified input parameter is invalid.
- * @exception E_APP_NOT_INSTALLED The AppId is not found.
+ * @exception E_APP_NOT_INSTALLED The @c appId has not been found.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
* @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
* @remarks The specific error code can be accessed using the GetLastResult() method.
static AppSetting* GetInstanceByAppId(const AppId& appId);
/**
- * Releases the specified application setting instance.
+ * Releases the specified %AppSetting instance.
*
* @since 2.0
*
- * @privlevel partner
+ * @privlevel platform
* @privilege %http://tizen.org/privilege/appsetting
*
* @return An error code
- * @param[in] appId The AppId of the application that has a valid application setting
+ * @param[in] appId The ID of the application that has a valid application setting
* @exception E_SUCCESS The method is successful.
- * @exception E_OBJ_NOT_FOUND The specified instance of AppId is not found or already released.
+ * @exception E_OBJ_NOT_FOUND Either of the following conditions has occurred:
+ * - The specified @c appId has not been found.
+ * - The specified @c appId is already released.
* @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
- * @remarks Individual instances are managed by the platform. @n
- * It is recommended to release instances to reduce memory usage.
+ * @remarks
+ * - Individual instances are managed by the platform.
+ * - It is recommended to release instances to reduce memory usage.
* @see GetInstanceByAppId()
*/
static result ReleaseInstanceByAppId(const AppId& appId);
/**
- * Gets a list of all the versions that existed prior to the current version. @n
- * The versions listed are based on the setting.xml file, which is generated when an application is installed.
+ * Gets the list of all the versions that existed prior to the current version. @n
+ * The versions are listed based on the setting.xml file, which is generated when an application is installed.
*
* @since 2.0
*
- * @return A pointer to the list that contains the Tizen::Base::String instances of version list
+ * @return A pointer to the list that contains the Tizen::Base::String instances of the version list @n
+ * The latest version string is located at the first position @n
+ * If the old version does not exist then an empty collection is returned.
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @remarks The latest version string is located in the first position.
- * If the old version does not exist then return empty collection. @n
- * The specific error code can be accessed using the GetLastResult() method.
+ * @remarks The specific error code can be accessed using the GetLastResult() method.
*/
static Tizen::Base::Collection::IList* GetAppSettingVersionListN(void);
/**
- * Gets a @c bool value associated with the specified @c id.
+ * Gets the @c bool value associated with the specified @c id.
*
* @since 2.0
*
* @return An error code
- * @param[in] id The ID of the value to retrieve
- * @param[out] value A boolean value to retrieve
+ * @param[in] id The ID of the boolean value to retrieve
+ * @param[out] value The boolean value to retrieve
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
- * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting.
+ * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting.
* @exception E_INVALID_ARG A specified input parameter is invalid.
- * @exception E_TYPE_MISMATCH The operation has attempted to access different types.
+ * @exception E_TYPE_MISMATCH The types accessed by the method do not match.
*/
result GetValue(const Tizen::Base::String& id, bool& value) const;
/**
- * Gets an integer value associated with the specified @c id.
+ * Gets the integer value associated with the specified @c id.
*
* @since 2.0
*
* @return An error code
- * @param[in] id The ID of the value to retrieve
- * @param[out] value An integer value to retrieve
+ * @param[in] id The ID of the integer value to retrieve
+ * @param[out] value The integer value to retrieve
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
- * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting.
+ * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting.
* @exception E_INVALID_ARG A specified input parameter is invalid.
- * @exception E_TYPE_MISMATCH The operation has attempted to access different types.
+ * @exception E_TYPE_MISMATCH The types accessed by the method do not match.
*/
result GetValue(const Tizen::Base::String& id, int& value) const;
/**
- * Gets a string value associated with the specified @c id.
+ * Gets the string value associated with the specified @c id.
*
* @since 2.0
*
* @return An error code
- * @param[in] id The id of the value to retrieve
- * @param[out] value A string value to retrieve
+ * @param[in] id The ID of the string value to retrieve
+ * @param[out] value The string value to retrieve
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
- * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting.
+ * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting.
* @exception E_INVALID_ARG A specified input parameter is invalid.
- * @exception E_TYPE_MISMATCH The operation has attempted to access different types.
+ * @exception E_TYPE_MISMATCH The types accessed by the method do not match.
*/
result GetValue(const Tizen::Base::String& id, Tizen::Base::String& value) const;
/**
- * Sets a @c bool value associated with the specified @c id.
+ * Sets the @c bool value associated with the specified @c id.
*
* @since 2.0
*
* @return An error code
- * @param[in] id The ID of the value to modify
- * @param[in] value A boolean value
+ * @param[in] id The ID of the boolean value to modify
+ * @param[in] value The boolean value
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
- * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting.
+ * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting.
* @exception E_INVALID_ARG A specified input parameter is invalid.
- * @exception E_TYPE_MISMATCH The operation has attempted to access different types.
+ * @exception E_TYPE_MISMATCH The types accessed by the method do not match.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
*/
result SetValue(const Tizen::Base::String& id, bool value);
/**
- * Sets an integer value associated with the specified @c id.
+ * Sets the integer value associated with the specified @c id.
*
* @since 2.0
*
* @return An error code
- * @param[in] id The ID of the value to modify
- * @param[in] value An integer value
+ * @param[in] id The ID of the integer value to modify
+ * @param[in] value The integer value
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
- * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting.
- * @exception E_OUT_OF_RANGE The specified @c value is out of range.
+ * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting.
+ * @exception E_OUT_OF_RANGE The specified @c value is out of the valid range.
* @exception E_INVALID_ARG A specified input parameter is invalid.
- * @exception E_TYPE_MISMATCH The operation has attempted to access different types.
+ * @exception E_TYPE_MISMATCH The types accessed by the method do not match.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
*/
result SetValue(const Tizen::Base::String& id, int value);
/**
- * Sets a string value associated with the specified @c id.
+ * Sets the string value associated with the specified @c id.
*
* @since 2.0
*
* @return An error code
- * @param[in] id The ID of the value to modify
- * @param[in] value A string value
+ * @param[in] id The ID of the string value to modify
+ * @param[in] value The string value
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
- * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting.
- * @exception E_OUT_OF_RANGE The specified string length is out of range.
+ * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting.
+ * @exception E_OUT_OF_RANGE The specified string length is out of the valid range.
* @exception E_INVALID_ARG A specified input parameter is invalid.
- * @exception E_TYPE_MISMATCH The operation has attempted to access different types.
+ * @exception E_TYPE_MISMATCH The types accessed by the method do not match.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
*/
result SetValue(const Tizen::Base::String& id, const Tizen::Base::String& value);
/**
- * Sets a setting event listener.
+ * Sets the setting event listener.
*
* @since 2.0
*