X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFAppAppResource.h;h=af96e60b3a018663e27a76ff2cd3feddad7ad2dd;hb=9646d95c0666d24d94fdefeedf94c951b9d6c812;hp=baa1d8b2fda8e37bbdb1133dfdbb07939ecd4703;hpb=5de461d8fd15a2a342d981f4fdc1b84921a89c97;p=platform%2Fframework%2Fnative%2Fappfw.git diff --git a/inc/FAppAppResource.h b/inc/FAppAppResource.h index baa1d8b..af96e60 100644 --- a/inc/FAppAppResource.h +++ b/inc/FAppAppResource.h @@ -15,8 +15,8 @@ // /** - * @file FAppAppResource.h - * @brief This is the header file for the %AppResource class. + * @file FAppAppResource.h + * @brief This is the header file for the %AppResource class. * * This header file contains the declarations of the %AppResource class. */ @@ -35,19 +35,20 @@ namespace Tizen { namespace App { /** -* @class AppResource -* @brief This class provides convenient methods to load application resources at run time. +* @class AppResource +* @brief This class provides convenient methods to load application resources at run time. * * @since 2.0 * * @final This class is not intended for extension. * * The %AppResource class provides convenient methods to load application resources at run time: @n -* - Use AppResource::GetString() to get handle and display localized strings. -* - Use AppResource::GetBitmapN() to obtain a bitmap image that matches the screen density. -* - If the matching image does not exist, the image of the baseline density folder, ScreenDensity-High is used. +* - Use the AppResource::GetString() method to get a handle and display localized strings. +* - Use the AppResource::GetBitmapN() method to obtain a bitmap image that matches the screen density. +* - If a matching image does not exist, the image of the baseline density folder, ScreenDensity-High is used. +* +* The instance of this class can be obtained through the App::GetAppResource() method. * -* The instance of this class can be obtained through App::GetAppResource(). * The following example demonstrates how to use the %AppResource class to get strings. * * @code @@ -102,129 +103,138 @@ public: * @return An error code * @param[in] resourceId The resource ID of type Tizen::Base::String that describes the resource * @param[out] loadedString The string obtained from the loaded application resource - * @exception E_SUCCESS The method is successful. - * @exception E_FAILURE The argument passed is not found. - * @exception E_INVALID_ARG The argument passed to a method contains an invalid resource ID. + * @exception E_SUCCESS The method is successful. + * @exception E_FAILURE The argument passed has not been found. + * @exception E_INVALID_ARG The argument passed to the method contains an invalid resource ID. */ result GetString(const Tizen::Base::String& resourceId, Tizen::Base::String& loadedString) const; /** * Gets the bitmap at the specified path. @n * The %GetBitmapN() method interprets the given resource path and reads the best matching image file for the current device resolution. @n - * To load the bitmap image from a file, give the name of the file as the input parameter and not the file path (For example: "img.png"). - * Then, the system will first look for the image file in the folder specific to the current device resolution, such as + * To load the bitmap image from a file, give the name of the file as the input parameter and not the file path (For example, "img.png"). + * The system will first look for the image file in the folder specific to the current device resolution, such as * '720x1280' and if the file does not exist, it will then search the folder that corresponds to the current screen density, * such as 'screen-density-xhigh'. After searching the density folder, all the other density folders are searched in the order high to low. * If the requested image file is found in a density-specific folder that is different from the current screen density, the bitmap returned from this method is pre-scaled. - * But in case of requested image file is saved as ".#.png" (For example : "img.#.png"), then a bitmap instance which is value of returned pointer is not pre-scaled. - * So, it is recommended to use ".#.png" as extension (For example : "ninePatchImg.#.png") for nine-patch image file. + * But in case the requested image file is saved as ".#.png" (For example, "img.#.png"), then the bitmap instance of the returned pointer is not pre-scaled. + * So, it is recommended to use ".#.png" as the extension (For example, "ninePatchImg.#.png") for a nine-patch image file. * Currently supported image formats are: JPEG, GIF, PNG, BMP, TIFF, and WBMP. * For more information on the features, see Resource Fallback and Prescaling. * * @since 2.0 * - * @return A pointer to the Bitmap instance generated from the specified file + * @return A pointer to the Tizen::Graphics::Bitmap instance generated from the specified file * @param[in] imagePath The relative path starting from the directory @b "res/screen-density-XXX/" or @b "res/AxB", @n - * where A and B represent the screen width and height of the supported device models, respectively. + * where A and B represent the screen width and screen height of the supported device models, respectively. * @param[in] pixelFormat The pixel format of the resulting bitmap * @exception E_SUCCESS The method is successful. * @exception E_INVALID_ARG A specified input parameter is invalid. - * @exception E_UNSUPPORTED_FORMAT The image file format or specified pixel format is not supported. + * @exception E_UNSUPPORTED_FORMAT Either the image file format or the specified @c pixelFormat is not supported. * @exception E_FILE_NOT_FOUND The specified file cannot be found. * @exception E_SYSTEM A system error has occurred. - * @remarks The specific error code can be accessed using the GetLastResult() method. - * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer here. + * @remarks + * - The specific error code can be accessed using the GetLastResult() method. + * - There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is @c E_OUT_OF_MEMORY or not. + * For more information on how to handle the out-of-memory exception, refer + * here. */ Tizen::Graphics::Bitmap* GetBitmapN(const Tizen::Base::String& imagePath, Tizen::Graphics::BitmapPixelFormat pixelFormat) const; /** * Gets the bitmap at the specified path. @n * The %GetBitmapN() method interprets the given resource path and reads the best matching image file for the current device resolution. @n - * To load the bitmap image from a file, give the name of the file as the input parameter and not the file path (For example: "img.png"). - * Then, the system will first look for the image file in the folder specific to the current device resolution, such as + * To load the bitmap image from a file, give the name of the file as the input parameter and not the file path (For example, "img.png"). + * The system will first look for the image file in the folder specific to the current device resolution, such as * '720x1280' and if the file does not exist, it will then search the folder that corresponds to the current screen density, * such as 'screen-density-xhigh'. After searching the density folder, all the other density folders are searched in the order high to low. * If the requested image file is found in a density-specific folder that is different from the current screen density, the bitmap returned from this method is pre-scaled. - * But in case of requested image file is saved as ".#.png" (For example : "img.#.png"), then a bitmap instance which is value of returned pointer is not pre-scaled. - * So, it is recommended to use ".#.png" as extension (For example : "ninePatchImg.#.png") for nine-patch image file. + * But in case the requested image file is saved as ".#.png" (For example, "img.#.png"), then the bitmap instance of the returned pointer is not pre-scaled. + * So, it is recommended to use ".#.png" as the extension (For example, "ninePatchImg.#.png") for a nine-patch image file. * Currently supported image formats are: JPEG, GIF, PNG, BMP, TIFF, and WBMP. * For more information on the features, see Resource Fallback and Prescaling. * * @since 2.0 * - * @return A pointer to the Tizen::Graphics::Bitmap instance generated from the specified file + * @return A pointer to the Tizen::Graphics::Bitmap instance generated from the specified file * @param[in] imagePath The relative path starting from the density directory @b "res/screen-density-XXX/" or @b "res/AxB", @n - * where A and B represent the width and height of the screen of the supported device models, respectively + * where A and B represent the screen width and screen height of the supported device models, respectively * @exception E_SUCCESS The method is successful. * @exception E_INVALID_ARG The specified input parameter is invalid. * @exception E_UNSUPPORTED_FORMAT The image file format is not supported. * @exception E_FILE_NOT_FOUND The specified file cannot be found. * @exception E_SYSTEM A system error has occurred. - * @remarks The specific error code can be accessed using the GetLastResult() method. - * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer here. + * @remarks + * - The specific error code can be accessed using the GetLastResult() method. + * - There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is @c E_OUT_OF_MEMORY or not. + * For more information on how to handle the out-of-memory exception, refer + * here. */ Tizen::Graphics::Bitmap* GetBitmapN(const Tizen::Base::String& imagePath) const; /** - * Gets the %AppResource instance pointer. + * Gets a pointer to the %AppResource instance. * - * @since 2.0 + * @since 2.0 * - * @return A pointer to the %AppResource instance, @n - * else @c null if it fails + * @return A pointer to the %AppResource instance, @n + * else @c null if it fails */ static AppResource* GetInstance(void); /** - * Gets the resource instance of the specified resource path. - * @since 2.0 + * Gets an %AppResource instance of the specified @c resourcePath. + * @since 2.0 * @return A pointer to the %AppResource instance, @n * else @c null if it fails * @param[in] resourcePath The relative path starting from the resource directory path of the current application * @exception E_SUCCESS The method is successful. - * @exception E_FILE_NOT_FOUND The specified resource path does not exist. - * @exception E_INVALID_ARG The length of the specified path is @c 0 or exceeds system limitations. - * @exception E_SYSTEM Initializing string and bitmap resource is failed due to system error. + * @exception E_FILE_NOT_FOUND The specified @c resourcePath does not exist. + * @exception E_INVALID_ARG Either of the following conditions has occured: + * - The length of the specified path is @c 0. + * - The length of the specified path exceeds system limitations. + * @exception E_SYSTEM Initializing the string and the bitmap resource has failed due to a system error. * @remarks The specific error code can be accessed using the GetLastResult() method. */ static AppResource* LoadAppResource(const Tizen::Base::String& resourcePath); /** - * Gets the application resource instance of the specified @c appId. + * Gets an %AppResource instance of the specified @c appId. * * @since 2.0 * * @privlevel platform - * @privilege %http://tizen.org/privilege/appsetting + * @privilege %http://tizen.org/privilege/appsetting * * @return A pointer to the %AppResource instance, @n * else @c null if it fails - * @param[in] appId The AppId of the installed application + * @param[in] appId The ID of the installed application * @exception E_SUCCESS The method is successful. - * @exception E_DATA_NOT_FOUND The instance of specified @c appId does not provide the string resource. + * @exception E_DATA_NOT_FOUND The specified @c appId does not provide the required string resource. * @exception E_OUT_OF_MEMORY The memory is insufficient. - * @exception E_APP_NOT_INSTALLED The specified @c appId is not found in the list of installed applications. - * @exception E_SYSTEM Initializing string and bitmap resource has failed due to a system error. - * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. + * @exception E_APP_NOT_INSTALLED The specified @c appId has not been found in the list of installed applications. + * @exception E_SYSTEM Initializing the string and the bitmap resource has failed due to a 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 AppResource* GetInstanceByAppId(const AppId& appId); /** - * Releases the application resource instance of the specified @c appId. + * Releases the %AppResource instance of the specified @c appId. * * @since 2.0 * - * @privlevel platform + * @privlevel platform * @privilege %http://tizen.org/privilege/appsetting * * @return An error code - * @param[in] appId The AppId of the installed application + * @param[in] appId The ID of the installed application * @exception E_SUCCESS The method is successful. - * @exception E_OBJ_NOT_FOUND The application resource instance of the specified @c appId is not found. - * @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. + * @exception E_OBJ_NOT_FOUND The application resource instance of the specified @c appId has not been found. + * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. + * @remarks + * - Individual instances are managed by the platform. + * - It is recommended to release instances to reduce memory usage. */ static result ReleaseInstanceByAppId(const AppId& appId);