X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFAppAppSetting.h;h=303b4309afd22b12d15831f3b46eb60d09eb6371;hb=f6fe22fddce04f1e48556cc2e3219b292117d91f;hp=7665317d3d866fe1ccf61066e843cca6eb985fc5;hpb=ce380ff0d6dfbf0b1420e0b045f6077f2e124573;p=platform%2Fframework%2Fnative%2Fappfw.git diff --git a/inc/FAppAppSetting.h b/inc/FAppAppSetting.h index 7665317..303b430 100644 --- a/inc/FAppAppSetting.h +++ b/inc/FAppAppSetting.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); @@ -50,111 +49,70 @@ class IAppSettingEventListener; * * @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 (Creating and Using Application Settings, Application Settings Editor). + * (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 Task: App Setting. + * + * @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 - * @privilege http://tizen.org/privilege/appsetting + * @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. @@ -163,143 +121,146 @@ public: static AppSetting* GetInstanceByAppId(const AppId& appId); /** - * Releases the specified application setting instance. + * Releases the specified %AppSetting instance. * * @since 2.0 * - * @privlevel partner - * @privilege http://tizen.org/privilege/appsetting + * @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 *