X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=adaptors%2Fpublic-api%2Fadaptor-framework%2Fapplication.h;h=d36416ba1130a65957c391b2232ee12655d158a4;hb=5c4315b7016b8b754f3797d21750963721cd97a5;hp=6c7a2c38ac6d7a0dda704d9976189a23568baf61;hpb=f082b3d33300c78142eef8609f30debce30667aa;p=platform%2Fcore%2Fuifw%2Fdali-adaptor.git diff --git a/adaptors/public-api/adaptor-framework/application.h b/adaptors/public-api/adaptor-framework/application.h index 6c7a2c3..d36416b 100644 --- a/adaptors/public-api/adaptor-framework/application.h +++ b/adaptors/public-api/adaptor-framework/application.h @@ -2,7 +2,7 @@ #define __DALI_APPLICATION_H__ /* - * Copyright (c) 2014 Samsung Electronics Co., Ltd. + * Copyright (c) 2015 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -19,17 +19,22 @@ */ // EXTERNAL INCLUDES -#include #include -#include #include +#include +#include -#include "style-monitor.h" -#include "device-layout.h" + +// INTERNAL INCLUDES +#include "application-configuration.h" #include "window.h" namespace Dali { +/** + * @addtogroup dali_adaptor_framework + * @{ + */ namespace Internal DALI_INTERNAL { @@ -38,10 +43,11 @@ namespace Adaptor class Application; } } - /** - * An Application class object should be created by every application - * that wishes to use Dali. It provides a means for initialising the + * @brief An Application class object should be created by every application + * that wishes to use Dali. + * + * It provides a means for initializing the * resources required by the Dali::Core. * * The Application class emits several signals which the user can @@ -52,16 +58,28 @@ class Application; * Applications should follow the example below: * * @code - * void CreateProgram(Application app) + * class ExampleController: public ConnectionTracker * { - * // Create Dali components... - * // Can instantiate here, if required - * } + * public: + * ExampleController( Application& application ) + * : mApplication( application ) + * { + * mApplication.InitSignal().Connect( this, &ExampleController::Create ); + * } + * + * void Create( Application& application ) + * { + * // Create Dali components... + * } + * ... + * private: + * Application& mApplication; + * }; * * int main (int argc, char **argv) * { * Application app = Application::New(&argc, &argv); - * app.InitSignal().Connect(&CreateProgram); + * ExampleController example( app ); * app.MainLoop(); * } * @endcode @@ -84,232 +102,325 @@ class Application; * @endcode * * When the above options are found, they are stripped from argv, and argc is updated appropriately. + * @SINCE_1_0.0 */ class DALI_IMPORT_API Application : public BaseHandle { public: - typedef SignalV2< void (Application&) > AppSignalV2; + + typedef Signal< void (Application&) > AppSignalType; ///< Application lifecycle signal and system signal callback type @SINCE_1_0.0 + typedef Signal< void (Application&, void *) > AppControlSignalType; ///< Application control signal callback type @SINCE_1_0.0 /** - * Decides whether a Dali application window is opaque or transparent. + * @brief Enumeration for deciding whether a Dali application window is opaque or transparent. + * @SINCE_1_0.0 */ enum WINDOW_MODE { - OPAQUE = 0, ///< The window will be opaque - TRANSPARENT = 1 ///< The window transparency will match the alpha value set in Dali::Stage::SetBackgroundcolor() + OPAQUE = 0, ///< The window will be opaque @SINCE_1_0.0 + TRANSPARENT = 1 ///< The window transparency will match the alpha value set in Dali::Stage::SetBackgroundcolor() @SINCE_1_0.0 }; public: /** - * This is the constructor for applications without an argument list. - * - * @note The default base layout (DeviceLayout::DEFAULT_BASE_LAYOUT) will be used with this constructor. + * @brief This is the constructor for applications without an argument list. + * @SINCE_1_0.0 + * @PRIVLEVEL_PUBLIC + * @PRIVILEGE_DISPLAY + * @return A handle to the Application */ static Application New(); /** - * This is the constructor for applications. + * @brief This is the constructor for applications. * + * @SINCE_1_0.0 + * @PRIVLEVEL_PUBLIC + * @PRIVILEGE_DISPLAY * @param[in,out] argc A pointer to the number of arguments - * @param[in,out] argv A pointer the the argument list - * - * @note The default base layout (DeviceLayout::DEFAULT_BASE_LAYOUT) will be used with this constructor. - * @note Supported options are stripped from argv, and argc is updated appropriately. + * @param[in,out] argv A pointer to the argument list + * @return A handle to the Application */ static Application New( int* argc, char **argv[] ); /** - * This is the constructor for applications with a name - * - * @param[in,out] argc A pointer to the number of arguments - * @param[in,out] argv A pointer the the argument list - * @param[in] name A name of application - * - * @note The default base layout (DeviceLayout::DEFAULT_BASE_LAYOUT) will be used with this constructor. - * @note Supported options are stripped from argv, and argc is updated appropriately. - */ - static Application New( int* argc, char **argv[], const std::string& name ); - - /** - * This is the constructor for applications with a name, and also require a - * transparent top-level window - * - * @param[in,out] argc A pointer to the number of arguments - * @param[in,out] argv A pointer the the argument list - * @param[in] name A name of application - * @param[in] windowMode A member of WINDOW_MODE - * - * @note The default base layout (DeviceLayout::DEFAULT_BASE_LAYOUT) will be used with this constructor. - * @note Supported options are stripped from argv, and argc is updated appropriately. - */ - static Application New( int* argc, char **argv[], const std::string& name, WINDOW_MODE windowMode ); - - /** - * This is the constructor for applications when a layout for the application is specified. + * @brief This is the constructor for applications with a name. * + * @SINCE_1_0.0 + * @PRIVLEVEL_PUBLIC + * @PRIVILEGE_DISPLAY * @param[in,out] argc A pointer to the number of arguments - * @param[in,out] argv A pointer the the argument list - * @param[in] baseLayout The base layout that the application has been written for - * - * @note Supported options are stripped from argv, and argc is updated appropriately. + * @param[in,out] argv A pointer to the argument list + * @param[in] stylesheet The path to user defined theme file + * @return A handle to the Application + * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden. */ - static Application New( int* argc, char **argv[], const DeviceLayout& baseLayout ); + static Application New( int* argc, char **argv[], const std::string& stylesheet ); /** - * This is the constructor for applications with a name and when a layout for the application is specified. - * - * @param[in,out] argc A pointer to the number of arguments - * @param[in,out] argv A pointer the the argument list - * @param[in] name A name of application - * @param[in] baseLayout The base layout that the application has been written for + * @brief This is the constructor for applications with a name. * - * @note Supported options are stripped from argv, and argc is updated appropriately. + * @SINCE_1_0.0 + * @PRIVLEVEL_PUBLIC + * @PRIVILEGE_DISPLAY + * @param[in,out] argc A pointer to the number of arguments + * @param[in,out] argv A pointer to the argument list + * @param[in] stylesheet The path to user defined theme file + * @param[in] windowMode A member of WINDOW_MODE + * @return A handle to the Application + * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden. */ - static Application New( int* argc, char **argv[], const std::string& name, const DeviceLayout& baseLayout ); + static Application New( int* argc, char **argv[], const std::string& stylesheet, WINDOW_MODE windowMode ); /** - * Construct an empty handle + * @brief Constructs an empty handle. + * @SINCE_1_0.0 */ Application(); /** - * Copy Constructor + * @brief Copy Constructor. + * @SINCE_1_0.0 + * @param[in] application Handle to an object */ Application( const Application& application ); /** - * Assignment operator + * @brief Assignment operator. + * @SINCE_1_0.0 + * @param[in] application Handle to an object + * @return A reference to this */ - Application& operator=( const Application& applicaton ); + Application& operator=( const Application& application ); /** - * @brief Destructor + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~Application(); public: /** - * This starts the application. + * @brief This starts the application. + * + * Choosing this form of main loop indicates that the default + * application configuration of APPLICATION_HANDLES_CONTEXT_LOSS is used. On platforms where + * context loss can occur, the application is responsible for tearing down and re-loading UI. + * The application should listen to Stage::ContextLostSignal and Stage::ContextRegainedSignal. + * @SINCE_1_0.0 */ void MainLoop(); /** - * This lowers the application to bottom without actually quitting it + * @brief This starts the application, and allows the app to choose a different configuration. + * + * If the application plans on using the ReplaceSurface or ReplaceWindow API, then this will + * trigger context loss & regain. + * The application should listen to Stage::ContextLostSignal and Stage::ContextRegainedSignal. + * @SINCE_1_0.0 + * @param[in] configuration The context loss configuration */ - void Lower(); + void MainLoop(Configuration::ContextLoss configuration); /** - * This quits the application. Tizen applications should use Lower to improve re-start performance unless they need to Quit completely. + * @brief This lowers the application to bottom without actually quitting it. + * @SINCE_1_0.0 */ - void Quit(); + void Lower(); /** - * This returns a handle to the Orientation object used by Application which allows - * the user to determine the orientation of the device and connect to a - * signal emitted whenever the orientation changes. - * @return A handle to the Orientation object used by the Application + * @brief This quits the application. Tizen applications should use Lower to improve re-start performance unless they need to Quit completely. + * @SINCE_1_0.0 */ - Orientation GetOrientation(); + void Quit(); /** - * Ensures that the function passed in is called from the main loop when it is idle. + * @brief Ensures that the function passed in is called from the main loop when it is idle. + * @SINCE_1_0.0 + * @param[in] callback The function to call + * @return @c true if added successfully, @c false otherwise + * + * @note Function must be called from main event thread only * * A callback of the following type may be used: * @code * void MyFunction(); * @endcode * - * @param[in] callBack The function to call. - * @return true if added successfully, false otherwise + * @note Ownership of the callback is passed onto this class. */ - bool AddIdle(boost::function callBack); + bool AddIdle( CallbackBase* callback ); /** - * Retrieves the window used by the Application class. + * @brief Retrieves the window used by the Application class. + * * The application writer can use the window to change indicator and orientation * properties. + * @SINCE_1_0.0 * @return A handle to the window */ Window GetWindow(); + /** + * @brief Replaces the current window. + * + * This will force context loss. + * If you plan on using this API in your application, then you should configure + * it to prevent discard behavior when handling the Init signal. + * @SINCE_1_0.0 + * @param[in] windowPosition The position and size parameters of the new window + * @param[in] name The name of the new window + */ + void ReplaceWindow(PositionSize windowPosition, const std::string& name); + + /** + * @brief Get path application resources are stored at + * + * @SINCE_1_2.2 + * @return the full path of the resources + */ + static std::string GetResourcePath(); + public: // Stereoscopy /** - * Set the viewing mode for the application. - * @param[in] viewMode The new viewing mode. + * @brief Sets the viewing mode for the application. + * @SINCE_1_0.0 + * @param[in] viewMode The new viewing mode */ void SetViewMode( ViewMode viewMode ); /** - * Get the current viewing mode. - * @return The current viewing mode. + * @brief Gets the current viewing mode. + * @SINCE_1_0.0 + * @return The current viewing mode */ ViewMode GetViewMode() const; /** - * Set the stereo base (eye seperation) for stereoscopic 3D - * @param[in] stereoBase The stereo base (eye seperation) for stereoscopic 3D + * @brief Sets the stereo base (eye separation) for Stereoscopic 3D. + * + * The stereo base is the distance in millimetres between the eyes. Typical values are + * between 50mm and 70mm. The default value is 65mm. + * @SINCE_1_0.0 + * @param[in] stereoBase The stereo base (eye separation) for Stereoscopic 3D */ void SetStereoBase( float stereoBase ); /** - * Get the stereo base (eye seperation) for stereoscopic 3D - * @return The stereo base (eye seperation) for stereoscopic 3D + * @brief Gets the stereo base (eye separation) for Stereoscopic 3D. + * + * @SINCE_1_0.0 + * @return The stereo base (eye separation) for Stereoscopic 3D */ float GetStereoBase() const; public: // Signals /** - * The user should connect to this signal to determine when they should initialise - * their application + * @brief The user should connect to this signal to determine when they should initialize + * their application. + * @SINCE_1_0.0 + * @return The signal to connect to */ - AppSignalV2& InitSignal(); + AppSignalType& InitSignal(); /** - * The user should connect to this signal to determine when they should terminate - * their application + * @brief The user should connect to this signal to determine when they should terminate + * their application. + * @SINCE_1_0.0 + * @return The signal to connect to */ - AppSignalV2& TerminateSignal(); + AppSignalType& TerminateSignal(); /** - * The user should connect to this signal if they need to perform any special + * @brief The user should connect to this signal if they need to perform any special * activities when the application is about to be paused. + * @SINCE_1_0.0 + * @return The signal to connect to */ - AppSignalV2& PauseSignal(); + AppSignalType& PauseSignal(); /** - * The user should connect to this signal if they need to perform any special + * @brief The user should connect to this signal if they need to perform any special * activities when the application has resumed. + * @SINCE_1_0.0 + * @return The signal to connect to */ - AppSignalV2& ResumeSignal(); + AppSignalType& ResumeSignal(); /** - * This signal is sent when the system requires the user to reinitialise itself. + * @brief This signal is sent when the system requires the user to reinitialize itself. + * @SINCE_1_0.0 + * @return The signal to connect to */ - AppSignalV2& ResetSignal(); + AppSignalType& ResetSignal(); /** - * This signal is emitted when the window the application is rendering on is resized. + * @DEPRECATED_1_1.43 Use Window::ResizedSignal() instead. + * @brief This signal is emitted when the window application rendering on is resized. + * @SINCE_1_0.0 + * @return The signal to connect to */ - AppSignalV2& ResizeSignal(); + AppSignalType& ResizeSignal(); /** - * This signal is emitted when the language is changed on the device. + * @brief This signal is emitted when another application sends a launch request to the application. + * + * When the application is launched, this signal is emitted after the main loop of the application starts up. + * The passed parameter describes the launch request and contains the information about why the application is launched. + * @SINCE_1_0.0 + * @return The signal to connect to + */ + AppControlSignalType& AppControlSignal(); + + /** + * @brief This signal is emitted when the language is changed on the device. + * @SINCE_1_0.0 + * @return The signal to connect to */ - AppSignalV2& LanguageChangedSignal(); + AppSignalType& LanguageChangedSignal(); + + /** + * @brief This signal is emitted when the region of the device is changed. + * @SINCE_1_0.0 + * @return The signal to connect to + */ + AppSignalType& RegionChangedSignal(); + + /** + * @DEPRECATED_1_2.58 Use LowBatterySignal() instead. + * @brief This signal is emitted when the battery level of the device is low. + * @SINCE_1_0.0 + * @return The signal to connect to + */ + AppSignalType& BatteryLowSignal() DALI_DEPRECATED_API; + + /** + * @DEPRECATED_1_2.58 Use LowMemorySignal() instead. + * @brief This signal is emitted when the memory level of the device is low. + * @SINCE_1_0.0 + * @return The signal to connect to + */ + AppSignalType& MemoryLowSignal() DALI_DEPRECATED_API; public: // Not intended for application developers + /// @cond internal /** - * Internal constructor + * @brief Internal constructor. + * @SINCE_1_0.0 */ explicit DALI_INTERNAL Application(Internal::Adaptor::Application* application); + /// @endcond }; +/** + * @} + */ } // namespace Dali #endif // __DALI_APPLICATION_H__