dali/public-api/adaptor-framework/application.h

   1 #ifndef DALI_APPLICATION_H
   2 #define DALI_APPLICATION_H
   3
   4 /*
   5  * Copyright (c) 2022 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <dali/public-api/object/base-handle.h>
  23 #include <dali/public-api/signals/callback.h>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/public-api/adaptor-framework/device-status.h>
  27 #include <dali/public-api/adaptor-framework/window.h>
  28
  29 namespace Dali
  30 {
  31 class ObjectRegistry;
  32
  33 /**
  34  * @addtogroup dali_adaptor_framework
  35  * @{
  36  */
  37
  38 namespace Internal DALI_INTERNAL
  39 {
  40 namespace Adaptor
  41 {
  42 class Application;
  43 }
  44 } // namespace DALI_INTERNAL
  45 /**
  46  * @brief An Application class object should be created by every application
  47  * that wishes to use Dali.
  48  *
  49  * It provides a means for initializing the
  50  * resources required by the Dali::Core.
  51  *
  52  * The Application class emits several signals which the user can
  53  * connect to.  The user should not create any Dali objects in the main
  54  * function and instead should connect to the Init signal of the
  55  * Application and create the Dali objects in the connected callback.
  56  *
  57  * Applications should follow the example below:
  58  *
  59  * @code
  60  * class ExampleController: public ConnectionTracker
  61  * {
  62  * public:
  63  *   ExampleController( Application& application )
  64  *   : mApplication( application )
  65  *   {
  66  *     mApplication.InitSignal().Connect( this, &ExampleController::Create );
  67  *   }
  68  *
  69  *   void Create( Application& application )
  70  *   {
  71  *     // Create Dali components...
  72  *   }
  73  *  ...
  74  * private:
  75  *   Application& mApplication;
  76  * };
  77  *
  78  * int main (int argc, char **argv)
  79  * {
  80  *   Application app = Application::New(&argc, &argv);
  81  *   ExampleController example( app );
  82  *   app.MainLoop();
  83  * }
  84  * @endcode
  85  *
  86  * If required, you can also connect class member functions to a signal:
  87  *
  88  * @code
  89  * MyApplication app;
  90  * app.ResumeSignal().Connect(&app, &MyApplication::Resume);
  91  * @endcode
  92  *
  93  *
  94  * #### UI thread
  95  * There is the UI thread feature.
  96  * UI thread is an additional thread that an Application object creates. The thread is for UI events.
  97  *
  98  * When the UI thread feature is enabled, you can use the task signals(TaskInit, TaskTerminate, TaskAppControl, TaskLanguageChanged, TaskLowBattery, and TaskLowMemory).
  99  * The task signals are emitted on the main thread,
 100  * and the normal signals(Init, Terminate, Pause, Resume, Reset, AppControl, LanguageChanged, Region, LowBattery, and LowMemory) are emitted on the UI thread.
 101  *
 102  * If you want to handle windows or actors in cases like when the memory level of the device is low, you have to use the normal signals, not the task signals.
 103  * Callbacks of all signals in DALi except the task signals are emitted on the UI thread. (e.g., Timer callbacks are emitted on the UI thread.)
 104  *
 105  * To enable the UI Thread, you can use this method. you have to set True to the useUiThread.
 106  * Dali::Application::New(int *argc, char **argv[], const std::string &stylesheet, Application::WINDOW_MODE windowMode, PositionSize positionSize, bool useUiThread)
 107  *
 108  *
 109  * This class accepts command line arguments as well. The following options are supported:
 110  *
 111  * @code
 112  *  -w|--width          Stage Width
 113  *  -h|--height         Stage Height
 114  *  -d|--dpi            Emulated DPI
 115  *     --help           Help
 116  * @endcode
 117  *
 118  * When the above options are found, they are stripped from argv, and argc is updated appropriately.
 119  * @SINCE_1_0.0
 120  */
 121 class DALI_ADAPTOR_API Application : public BaseHandle
 122 {
 123 public:
 124   typedef Signal<void(DeviceStatus::Battery::Status)> LowBatterySignalType; ///< Application device signal type @SINCE_1_2.62
 125   typedef Signal<void(DeviceStatus::Memory::Status)>  LowMemorySignalType;  ///< Application device signal type @SINCE_1_2.62
 126   typedef Signal<void(Application&)>                  AppSignalType;        ///< Application lifecycle signal and system signal callback type @SINCE_1_0.0
 127   typedef Signal<void(Application&, void*)>           AppControlSignalType; ///< Application control signal callback type @SINCE_1_0.0
 128
 129   /**
 130    * @brief Enumeration for deciding whether a Dali application window is opaque or transparent.
 131    * @SINCE_1_0.0
 132    */
 133   enum WINDOW_MODE
 134   {
 135     OPAQUE      = 0, ///< The window will be opaque @SINCE_1_0.0
 136     TRANSPARENT = 1  ///< The window transparency will match the alpha value set in Dali::Stage::SetBackgroundcolor() @SINCE_1_0.0
 137   };
 138
 139 public:
 140   /**
 141    * @brief This is the constructor for applications without an argument list.
 142    * @SINCE_1_0.0
 143    * @PRIVLEVEL_PUBLIC
 144    * @PRIVILEGE_DISPLAY
 145    * @return A handle to the Application
 146    */
 147   static Application New();
 148
 149   /**
 150    * @brief This is the constructor for applications.
 151    *
 152    * @SINCE_1_0.0
 153    * @PRIVLEVEL_PUBLIC
 154    * @PRIVILEGE_DISPLAY
 155    * @param[in,out]  argc        A pointer to the number of arguments
 156    * @param[in,out]  argv        A pointer to the argument list
 157    * @return A handle to the Application
 158    */
 159   static Application New(int* argc, char** argv[]);
 160
 161   /**
 162    * @brief This is the constructor for applications with a name.
 163    *
 164    * @SINCE_1_0.0
 165    * @PRIVLEVEL_PUBLIC
 166    * @PRIVILEGE_DISPLAY
 167    * @param[in,out]  argc        A pointer to the number of arguments
 168    * @param[in,out]  argv        A pointer to the argument list
 169    * @param[in]      stylesheet  The path to user defined theme file
 170    * @return A handle to the Application
 171    * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.
 172    */
 173   static Application New(int* argc, char** argv[], const std::string& stylesheet);
 174
 175   /**
 176    * @brief This is the constructor for applications with a name.
 177    *
 178    * @SINCE_1_0.0
 179    * @PRIVLEVEL_PUBLIC
 180    * @PRIVILEGE_DISPLAY
 181    * @param[in,out]  argc        A pointer to the number of arguments
 182    * @param[in,out]  argv        A pointer to the argument list
 183    * @param[in]      stylesheet  The path to user defined theme file
 184    * @param[in]      windowMode  A member of WINDOW_MODE
 185    * @return A handle to the Application
 186    * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.
 187    */
 188   static Application New(int* argc, char** argv[], const std::string& stylesheet, WINDOW_MODE windowMode);
 189
 190   /**
 191    * @brief This is the constructor for applications.
 192    *
 193    * @SINCE_1_2.60
 194    * @PRIVLEVEL_PUBLIC
 195    * @PRIVILEGE_DISPLAY
 196    * @param[in,out]  argc         A pointer to the number of arguments
 197    * @param[in,out]  argv         A pointer to the argument list
 198    * @param[in]      stylesheet   The path to user defined theme file
 199    * @param[in]      windowMode   A member of WINDOW_MODE
 200    * @param[in]      positionSize A position and a size of the window
 201    * @return A handle to the Application
 202    * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.
 203    */
 204   static Application New(int* argc, char** argv[], const std::string& stylesheet, Application::WINDOW_MODE windowMode, PositionSize positionSize);
 205
 206   /**
 207    * @brief This is the constructor for applications.
 208    *
 209    * @SINCE_2_1.20
 210    * @PRIVLEVEL_PUBLIC
 211    * @PRIVILEGE_DISPLAY
 212    * @param[in,out]  argc         A pointer to the number of arguments
 213    * @param[in,out]  argv         A pointer to the argument list
 214    * @param[in]      stylesheet   The path to user defined theme file
 215    * @param[in]      windowMode   A member of WINDOW_MODE
 216    * @param[in]      positionSize A position and a size of the window
 217    * @param[in]      useUiThread  True if the application would create a UI thread
 218    * @return A handle to the Application
 219    * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.<BR>
 220    * UI thread is an additional thread that DALi creates for UI events.
 221    * The UI thread isn't blocked from the system events(AppControl, LanguageChanged, RegionChanged, LowMemory, LowBattery task signals).
 222    */
 223   static Application New(int* argc, char** argv[], const std::string& stylesheet, Application::WINDOW_MODE windowMode, PositionSize positionSize, bool useUiThread);
 224
 225   /**
 226    * @brief Constructs an empty handle.
 227    * @SINCE_1_0.0
 228    */
 229   Application();
 230
 231   /**
 232    * @brief Copy Constructor.
 233    * @SINCE_1_0.0
 234    * @param[in] application Handle to an object
 235    */
 236   Application(const Application& application);
 237
 238   /**
 239    * @brief Assignment operator.
 240    * @SINCE_1_0.0
 241    * @param[in] application Handle to an object
 242    * @return A reference to this
 243    */
 244   Application& operator=(const Application& application);
 245
 246   /**
 247    * @brief Move constructor.
 248    *
 249    * @SINCE_1_9.24
 250    * @param[in] rhs A reference to the moved handle
 251    */
 252   Application(Application&& rhs);
 253
 254   /**
 255    * @brief Move assignment operator.
 256    *
 257    * @SINCE_1_9.24
 258    * @param[in] rhs A reference to the moved handle
 259    * @return A reference to this handle
 260    */
 261   Application& operator=(Application&& rhs);
 262
 263   /**
 264    * @brief Destructor.
 265    *
 266    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 267    * @SINCE_1_0.0
 268    */
 269   ~Application();
 270
 271 public:
 272   /**
 273    * @brief This starts the application.
 274    *
 275    * On platforms where context loss can occur, the application is responsible for tearing down and
 276    * re-loading UI.  The application should listen to Stage::ContextLostSignal and
 277    * Stage::ContextRegainedSignal.
 278    *
 279    * @SINCE_1_0.0
 280    */
 281   void MainLoop();
 282
 283   /**
 284    * @brief This lowers the application to bottom without actually quitting it.
 285    * @SINCE_1_0.0
 286    */
 287   void Lower();
 288
 289   /**
 290    * @brief This quits the application.  Tizen applications should use Lower to improve re-start performance unless they need to Quit completely.
 291    * @SINCE_1_0.0
 292    */
 293   void Quit();
 294
 295   /**
 296    * @brief Ensures that the function passed in is called from the main loop when it is idle.
 297    * @SINCE_1_0.0
 298    * @param[in] callback The function to call
 299    * @return @c true if added successfully, @c false otherwise
 300    *
 301    * @note Function must be called from main event thread only
 302    *
 303    * A callback of the following type may be used:
 304    * @code
 305    *   void MyFunction();
 306    * @endcode
 307    * This callback will be deleted once it is called.
 308    *
 309    * @note Ownership of the callback is passed onto this class.
 310    */
 311   bool AddIdle(CallbackBase* callback);
 312
 313   /**
 314    * @brief Retrieves the main window used by the Application class.
 315    *
 316    * The application writer can use the window to change indicator and orientation
 317    * properties.
 318    * @SINCE_1_0.0
 319    * @return A handle to the window
 320    */
 321   Window GetWindow();
 322
 323   /**
 324    * @brief Get path application resources are stored at
 325    *
 326    * @SINCE_1_2.2
 327    * @return the full path of the resources
 328    */
 329   static std::string GetResourcePath();
 330
 331   /**
 332    * @brief This is used to get region information from device.
 333    *
 334    * @SINCE_1_2.62
 335    * @return Region information
 336    */
 337   std::string GetRegion() const;
 338
 339   /**
 340    * @brief This is used to get language information from device.
 341    *
 342    * @SINCE_1_2.62
 343    * @return Language information
 344    */
 345   std::string GetLanguage() const;
 346
 347   /**
 348    * @brief Gets the Object registry.
 349    *
 350    * @SINCE_1_9.21
 351    * @return The object registry
 352    * @note This will only be a valid handle after the InitSignal has been emitted.
 353    */
 354   ObjectRegistry GetObjectRegistry() const;
 355
 356 public: // Signals
 357   /**
 358    * @brief The user should connect to this signal to determine when they should initialize
 359    * their application.
 360    * Only when the user uses the UiThread, this signal is emitted on the UI thread.
 361    * Otherwise, it is emitted on the main thread.
 362    * @SINCE_1_0.0
 363    * @return The signal to connect to
 364    */
 365   AppSignalType& InitSignal();
 366
 367   /**
 368    * @brief The user should connect to this signal to determine when they should terminate
 369    * their application.
 370    * Only when the user uses the UiThread, this signal is emitted on the UI thread.
 371    * Otherwise, it is emitted on the main thread.
 372    * @SINCE_1_0.0
 373    * @return The signal to connect to
 374    */
 375   AppSignalType& TerminateSignal();
 376
 377   /**
 378    * @brief The user should connect to this signal if they need to perform any special
 379    * activities when the application is about to be paused.
 380    * Only when the user uses the UiThread, this signal is emitted on the UI thread.
 381    * Otherwise, it is emitted on the main thread.
 382    * @SINCE_1_0.0
 383    * @return The signal to connect to
 384    */
 385   AppSignalType& PauseSignal();
 386
 387   /**
 388    * @brief The user should connect to this signal if they need to perform any special
 389    * activities when the application has resumed.
 390    * Only when the user uses the UiThread, this signal is emitted on the UI thread.
 391    * Otherwise, it is emitted on the main thread.
 392    * @SINCE_1_0.0
 393    * @return The signal to connect to
 394    */
 395   AppSignalType& ResumeSignal();
 396
 397   /**
 398    * @brief This signal is sent when the system requires the user to reinitialize itself.
 399    * Only when the user uses the UiThread, this signal is emitted on the UI thread.
 400    * Otherwise, it is emitted on the main thread.
 401    * @SINCE_1_0.0
 402    * @return The signal to connect to
 403    */
 404   AppSignalType& ResetSignal();
 405
 406   /**
 407    * @brief This signal is emitted when another application sends a launch request to the application.
 408    *
 409    * When the application is launched, this signal is emitted after the main loop of the application starts up.
 410    * The passed parameter describes the launch request and contains the information about why the application is launched.
 411    * Only when the user uses the UiThread, this signal is emitted on the UI thread.
 412    * Otherwise, it is emitted on the main thread.
 413    * @SINCE_1_0.0
 414    * @return The signal to connect to
 415    */
 416   AppControlSignalType& AppControlSignal();
 417
 418   /**
 419    * @brief This signal is emitted when the language is changed on the device.
 420    * Only when the user uses the UiThread, this signal is emitted on the UI thread.
 421    * Otherwise, it is emitted on the main thread.
 422    * @SINCE_1_0.0
 423    * @return The signal to connect to
 424    */
 425   AppSignalType& LanguageChangedSignal();
 426
 427   /**
 428    * @brief This signal is emitted when the region of the device is changed.
 429    * Only when the user uses the UiThread, this signal is emitted on the UI thread.
 430    * Otherwise, it is emitted on the main thread.
 431    * @SINCE_1_0.0
 432    * @return The signal to connect to
 433    */
 434   AppSignalType& RegionChangedSignal();
 435
 436   /**
 437    * @brief This signal is emitted when the battery level of the device is low.
 438    * Only when the user uses the UiThread, this signal is emitted on the UI thread.
 439    * Otherwise, it is emitted on the main thread.
 440    * @SINCE_1_2.62
 441    * @return The signal to connect to
 442    */
 443   LowBatterySignalType& LowBatterySignal();
 444
 445   /**
 446    * @brief This signal is emitted when the memory level of the device is low.
 447    * Only when the user uses the UiThread, this signal is emitted on the UI thread.
 448    * Otherwise, it is emitted on the main thread.
 449    * @SINCE_1_2.62
 450    * @return The signal to connect to
 451    */
 452   LowMemorySignalType& LowMemorySignal();
 453
 454   // TaskSignal
 455   /**
 456    * @brief The user should connect to this signal to determine when they should initialize
 457    * their application.
 458    * Only when the user uses the UiThread, this signal is emitted on the main thread.
 459    * Otherwise, it is not emitted at all.
 460    * @return The signal to connect to
 461    */
 462   AppSignalType& TaskInitSignal();
 463
 464   /**
 465    * @brief The user should connect to this signal to determine when they should terminate
 466    * their application.
 467    * Only when the user uses the UiThread, this signal is emitted on the main thread.
 468    * Otherwise, it is not emitted at all.
 469    * @return The signal to connect to
 470    */
 471   AppSignalType& TaskTerminateSignal();
 472
 473   /**
 474    * @brief This signal is emitted when another application sends a launch request to the application.
 475    *
 476    * When the application is launched, this signal is emitted after the main loop of the application starts up.
 477    * The passed parameter describes the launch request and contains the information about why the application is launched.
 478    * Only when the user uses the UiThread, this signal is emitted on the main thread.
 479    * Otherwise, it is not emitted at all.
 480    * @return The signal to connect to
 481    */
 482   AppControlSignalType& TaskAppControlSignal();
 483
 484   /**
 485    * @brief This signal is emitted when the language is changed on the device.
 486    * Only when the user uses the UiThread, this signal is emitted on the main thread.
 487    * Otherwise, it is not emitted at all.
 488    * @return The signal to connect to
 489    */
 490   AppSignalType& TaskLanguageChangedSignal();
 491
 492   /**
 493    * @brief This signal is emitted when the region of the device is changed.
 494    * Only when the user uses the UiThread, this signal is emitted on the main thread.
 495    * Otherwise, it is not emitted at all.
 496    * @return The signal to connect to
 497    */
 498   AppSignalType& TaskRegionChangedSignal();
 499
 500   /**
 501    * @brief This signal is emitted when the battery level of the device is low.
 502    * Only when the user uses the UiThread, this signal is emitted on the main thread.
 503    * Otherwise, it is not emitted at all.
 504    * @return The signal to connect to
 505    */
 506   LowBatterySignalType& TaskLowBatterySignal();
 507
 508   /**
 509    * @brief This signal is emitted when the memory level of the device is low.
 510    * Only when the user uses the UiThread, this signal is emitted on the main thread.
 511    * Otherwise, it is not emitted at all.
 512    * @return The signal to connect to
 513    */
 514   LowMemorySignalType&  TaskLowMemorySignal();
 515
 516 public: // Not intended for application developers
 517   /// @cond internal
 518   /**
 519    * @brief Internal constructor.
 520    * @SINCE_1_0.0
 521    */
 522   explicit DALI_INTERNAL Application(Internal::Adaptor::Application* application);
 523   /// @endcond
 524 };
 525
 526 /**
 527  * @}
 528  */
 529 } // namespace Dali
 530
 531 #endif // DALI_APPLICATION_H