*
* The %App class is the base class of a %Tizen native application.
* A %Tizen native application must be inherited from the UiApp or ServiceApp class. These classes are inherited from the %App class. This class provides the basic features necessary to define an application.
- * @n
+ *
* For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/app_namespace.htm">App Guide</a>, <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/tizen_app_model/application_lifecycle.htm">Application Life-cycle</a>, and <a href="../org.tizen.native.appprogramming/html/guide/app/app_system_events.htm">System Events</a>.
*
*/
/**
* @if OSPDEPREC
- * Gets the list of the launch arguments. @n
+ * Gets the list of launch arguments. @n
* For more information on the launch arguments, see <a href="../org.tizen.native.appprogramming/html/guide/app/launching_other_apps_within_apps.htm">Launching Other Applications</a>.
*
- * @brief <i> [Deprecated] </i>
+ * @brief <i> [Deprecated] </i>
* @deprecated This method is deprecated. Instead of using this method, it is recommended to use IAppControlProviderEventListener
- * to acquire delivered arguments list.
+ * to acquire the delivered arguments list.
* @since 2.0
*
* @return A pointer to the list that contains the Tizen::Base::String instances of the launch arguments
* Gets the locale-independent name of the application.
*
* @if OSPCOMPAT
- * @brief <i> [Compatibility] </i>
+ * @brief <i> [Compatibility] </i>
* @endif
* @since 2.0
* @if OSPCOMPAT
* @section CompGetAppNamePageIssue Issues
* Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
*
- * -# GetAppName() returns the localized name of the application while the meaning of the application name is ambiguous.
- * There are different use cases for locale-dependent name and localized name and the platform does not provide
- * a method for obtaining language-neutral name.
+ * -# The GetAppName() method returns the localized name of the application while the meaning of the application name is ambiguous.
+ * There are different use cases for the locale-dependent name and the localized name. The platform does not provide
+ * any method for obtaining the language-neutral name.
*
* @section CompGetAppNamePageResolution Resolutions
* The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
*
- * -# GetAppDisplayName() is introduced to acquire localized name and GetAppName() returns locale-independent application name.
+ * -# The GetAppDisplayName() method is introduced to acquire the localized application name and the GetAppName() method returns the locale-independent application name.
*/
/**
* Gets the display name of the application. @n
* If the system language setting is changed, the %GetAppDisplayName() method returns the localized application name.
- * The display name is displayed in applications like Launcher, Setting, Task Manager, and so on.
+ * The display name is displayed in applications like Launcher, Setting, Task Switcher, and so on.
*
* @since 2.0
*
AppId GetAppId(void) const;
/**
- * Gets the path of the application's root directory where the application is installed.
+ * Gets the path to the application's root directory where the application is installed.
*
* @since 2.0
*
Tizen::Base::String GetAppRootPath(void) const;
/**
- * Gets the path of the application's data directory used to store its own private data.
+ * Gets the path to the application's data directory where its private data is stored.
*
* @since 2.0
*
Tizen::Base::String GetAppDataPath(void) const;
/**
- * Gets the path of the application's resource directory that ships resource files delivered with the application
- * package.
+ * Gets the path to the application's resource directory that ships the resource files that are delivered with the application package.
*
* @since 2.0
*
Tizen::Base::String GetAppResourcePath(void) const;
/**
- * Gets the path of the application's shared directory to export data to other applications.
+ * Gets the path to the application's shared directory to export data to other applications.
*
* @since 2.1
*
/**
* Terminates the application while it is running. @n
- * The OnAppTerminating() method is called after the %Terminate() method is executed successfully.
+ * The %Terminate() method can be called explicitly by the application. The OnAppTerminating() method is called after this method is executed successfully.
*
* @since 2.0
*
- * @return An error code
+ * @return An error code
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_STATE This instance is in an invalid state.
*/
* including restoring the application's states, must be done in the %OnAppInitializing() method.
* If this method fails, the application's state changes to App::TERMINATED.
*
- * @since 2.0
+ * @since 2.0
*
- * @return @c true if the method is successful, @n
- * else @c false
+ * @return @c true if the method is successful, @n
+ * else @c false
* @param[in] appRegistry The instance of AppRegistry that manages the application's states
* @remarks Introducing the modal dialogs (for example, MessageBox) in this method is not allowed,
- * because it blocks the initialization procedure.
+ * because it blocks the initialization procedure.
*/
virtual bool OnAppInitializing(AppRegistry& appRegistry) = 0;
/**
* Called when the application's initialization is finished. @n
* After the %OnAppInitialized() method succeeds, the application's state changes to App::RUNNING.
- * If this method fails, the application's state changes to App::TERMINATING and the App::OnAppTerminating() method is called.
+ * If this method fails, the application's state changes to App::TERMINATING and the OnAppTerminating() method is called.
*
* @since 2.0
*
/**
* Called when the application is requested to terminate. @n
* The %OnAppWillTerminate() method returns @c false to prevent the application from getting terminated.
- * If this method returns @c true, the application's state changes to App::TERMINATING and the App::OnAppTerminating() method is called.
+ * If this method returns @c true, the application's state changes to App::TERMINATING and the OnAppTerminating() method is called.
*
* @since 2.0
*
/**
* Called when the application's state changes to App::TERMINATING. @n
- * All the activities involved in terminating the application, including saving the application's states, must be done in the %OnAppTerminating() method.
+ * All the activities involved in terminating the application, including saving the application's states, must be done by the %OnAppTerminating() method.
* After this method, the application code cannot be executed. The application is destroyed subsequently. @n
*
- * An application can be terminated by either system, such as power-off and OOM, or others, such as self and other applications. @n
- * When the termination by system, called an “urgent termination”, occurs, the method, %OnAppTerminating(), cannot be executed properly.
- * For more details, while power-off, even if %OnAppTerminating() is called, it has a short time for executing. If the application is killed by OOM, %OnAppTerminating() is not called. @n
- * Because %OnAppTerminating() is not likely to be called due to urgent termination, the application should save the critical data as they can do.
- * For example, the application can set the check point or use the callback for low memory. @n
- * When the termination by self or other applications, called a “normal termination”, occurs, the method, %OnAppTerminating(), can be executed properly.
- * It provides more time for executing than urgent termination, but limits to the time to 3 or 5 seconds. @n
- * The main loop is already quitted when %OnAppTerminating() is called.
- * Thus, the application should not use a kind of asynchronous API of which the callback is triggered by the main loop.
+ * An application's termination is triggered either by the system or by other applications. @n
+ * When the termination is triggered by the system because of conditions, such as power-off, and OOM, it is called "urgent termination" and during these terminations the %OnAppTerminating() method cannot be executed properly.
+ * When an application is terminated because of a power-off, although this method is called, it should be executed in a short duration. And when an application is killed by OOM, this method is not called. @n
+ * This implies that this method is not likely to be called during an urgent termination, and hence the application should save its critical data as often as possible.
+ * For example, the application can set a check point or use a callback for low memory issues.
+ * When an application terminates itself or is terminated by other applications, it is called "normal termination" and during these terminations this method is executed properly because more time is provided for execution as compared to an urgent termination (however, it does have a limit of 3-5 seconds). @n
+ * When this method is called, the main loop has already been quit.
+ * Thus, the application should not use any kind of asynchronous API that has callbacks triggered by the main loop.
*
* @since 2.0
*
- * @return @c true if the method is successful, @n
- * else @c false
+ * @return @c true if the method is successful, @n
+ * else @c false
* @param[in] appRegistry The instance that manages the application's states
* @param[in] urgentTermination Set to @c true if the application is terminated by the system, @n
* else @c false
virtual bool OnAppTerminating(AppRegistry& appRegistry, bool urgentTermination = false) = 0;
/**
- * Called when the system detects that the system wide memory or application heap memory is insufficient to run the application any further. @n
+ * Called when the system detects that the system wide memory or the application heap memory is insufficient to run the application any further. @n
* Resources that are not in use currently can be released using the %OnLowMemory() method.
*
* @since 2.0
/**
* Called when the battery level changes. @n
- * It is recommended that the application consuming more battery power must be terminated if the battery level is Tizen::System::BATTERY_LEVEL_CRITICAL.
+ * It is recommended that the application decides whether to terminate itself by considering its own battery power consumption, if the battery level is Tizen::System::BATTERY_LEVEL_CRITICAL.
*
* @since 2.0
*
*
* @return An error code
* @param[in] requestId The user defined event ID
- * @param[in] pArgs A pointer to an argument list of type Tizen::Base::String
+ * @param[in] pArgs A pointer to the argument list of type Tizen::Base::String
* @exception E_SUCCESS The method is successful.
* @see OnUserEventReceivedN()
*/
result SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs);
/**
- * Called asynchronously when the user event is sent by the SendUserEvent() method. @n
- * The request ID and argument format for the user event can be defined as per the requirement.
+ * Called asynchronously when the user event is sent by the SendUserEvent() method.
*
* @since 2.0
*
* @param[in] requestId The user defined event ID
- * @param[in] pArgs A pointer to an argument list of type Tizen::Base::String
+ * @param[in] pArgs A pointer to the argument list of type Tizen::Base::String
*/
virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
/**
- * Gets the %App instance's pointer.
+ * Gets a pointer to the %App instance.
*
* @since 2.0
*
projects / platform / framework / native / appfw.git / blobdiff