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(DeviceStatus::Orientation::Status)> DeviceOrientationChangedSignalType; ///< Application device orientation changed signal type @SINCE_2_2.1
 127   typedef Signal<void(Application&)>                      AppSignalType;                      ///< Application lifecycle signal and system signal callback type @SINCE_1_0.0
 128   typedef Signal<void(Application&, void*)>               AppControlSignalType;               ///< Application control signal callback type @SINCE_1_0.0
 129
 130   /**
 131    * @brief Enumeration for deciding whether a Dali application window is opaque or transparent.
 132    * @SINCE_1_0.0
 133    */
 134   enum WINDOW_MODE
 135   {
 136     OPAQUE      = 0, ///< The window will be opaque @SINCE_1_0.0
 137     TRANSPARENT = 1  ///< The window transparency will match the alpha value set in Dali::Stage::SetBackgroundcolor() @SINCE_1_0.0
 138   };
 139
 140 public:
 141   /**
 142    * @brief This is the constructor for applications without an argument list.
 143    * @SINCE_1_0.0
 144    * @PRIVLEVEL_PUBLIC
 145    * @PRIVILEGE_DISPLAY
 146    * @return A handle to the Application
 147    */
 148   static Application New();
 149
 150   /**
 151    * @brief This is the constructor for applications.
 152    *
 153    * @SINCE_1_0.0
 154    * @PRIVLEVEL_PUBLIC
 155    * @PRIVILEGE_DISPLAY
 156    * @param[in,out]  argc        A pointer to the number of arguments
 157    * @param[in,out]  argv        A pointer to the argument list
 158    * @return A handle to the Application
 159    */
 160   static Application New(int* argc, char** argv[]);
 161
 162   /**
 163    * @brief This is the constructor for applications with a name.
 164    *
 165    * @SINCE_1_0.0
 166    * @PRIVLEVEL_PUBLIC
 167    * @PRIVILEGE_DISPLAY
 168    * @param[in,out]  argc        A pointer to the number of arguments
 169    * @param[in,out]  argv        A pointer to the argument list
 170    * @param[in]      stylesheet  The path to user defined theme file
 171    * @return A handle to the Application
 172    * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.
 173    */
 174   static Application New(int* argc, char** argv[], const std::string& stylesheet);
 175
 176   /**
 177    * @brief This is the constructor for applications with a name.
 178    *
 179    * @SINCE_1_0.0
 180    * @PRIVLEVEL_PUBLIC
 181    * @PRIVILEGE_DISPLAY
 182    * @param[in,out]  argc        A pointer to the number of arguments
 183    * @param[in,out]  argv        A pointer to the argument list
 184    * @param[in]      stylesheet  The path to user defined theme file
 185    * @param[in]      windowMode  A member of WINDOW_MODE
 186    * @return A handle to the Application
 187    * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.
 188    */
 189   static Application New(int* argc, char** argv[], const std::string& stylesheet, WINDOW_MODE windowMode);
 190
 191   /**
 192    * @brief This is the constructor for applications.
 193    *
 194    * @SINCE_1_2.60
 195    * @PRIVLEVEL_PUBLIC
 196    * @PRIVILEGE_DISPLAY
 197    * @param[in,out]  argc         A pointer to the number of arguments
 198    * @param[in,out]  argv         A pointer to the argument list
 199    * @param[in]      stylesheet   The path to user defined theme file
 200    * @param[in]      windowMode   A member of WINDOW_MODE
 201    * @param[in]      positionSize A position and a size of the window
 202    * @return A handle to the Application
 203    * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.
 204    */
 205   static Application New(int* argc, char** argv[], const std::string& stylesheet, Application::WINDOW_MODE windowMode, PositionSize positionSize);
 206
 207   /**
 208    * @brief This is the constructor for applications.
 209    *
 210    * @SINCE_2_1.20
 211    * @PRIVLEVEL_PUBLIC
 212    * @PRIVILEGE_DISPLAY
 213    * @param[in,out]  argc         A pointer to the number of arguments
 214    * @param[in,out]  argv         A pointer to the argument list
 215    * @param[in]      stylesheet   The path to user defined theme file
 216    * @param[in]      windowMode   A member of WINDOW_MODE
 217    * @param[in]      positionSize A position and a size of the window
 218    * @param[in]      useUiThread  True if the application would create a UI thread
 219    * @return A handle to the Application
 220    * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.<BR>
 221    * UI thread is an additional thread that DALi creates for UI events.
 222    * The UI thread isn't blocked from the system events(AppControl, LanguageChanged, RegionChanged, LowMemory, LowBattery task signals).
 223    */
 224   static Application New(int* argc, char** argv[], const std::string& stylesheet, Application::WINDOW_MODE windowMode, PositionSize positionSize, bool useUiThread);
 225
 226   /**
 227    * @brief Constructs an empty handle.
 228    * @SINCE_1_0.0
 229    */
 230   Application();
 231
 232   /**
 233    * @brief Copy Constructor.
 234    * @SINCE_1_0.0
 235    * @param[in] application Handle to an object
 236    */
 237   Application(const Application& application);
 238
 239   /**
 240    * @brief Assignment operator.
 241    * @SINCE_1_0.0
 242    * @param[in] application Handle to an object
 243    * @return A reference to this
 244    */
 245   Application& operator=(const Application& application);
 246
 247   /**
 248    * @brief Move constructor.
 249    *
 250    * @SINCE_1_9.24
 251    * @param[in] rhs A reference to the moved handle
 252    */
 253   Application(Application&& rhs) noexcept;
 254
 255   /**
 256    * @brief Move assignment operator.
 257    *
 258    * @SINCE_1_9.24
 259    * @param[in] rhs A reference to the moved handle
 260    * @return A reference to this handle
 261    */
 262   Application& operator=(Application&& rhs) noexcept;
 263
 264   /**
 265    * @brief Destructor.
 266    *
 267    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 268    * @SINCE_1_0.0
 269    */
 270   ~Application();
 271
 272 public:
 273   /**
 274    * @brief This starts the application.
 275    *
 276    * On platforms where context loss can occur, the application is responsible for tearing down and
 277    * re-loading UI.  The application should listen to Stage::ContextLostSignal and
 278    * Stage::ContextRegainedSignal.
 279    *
 280    * @SINCE_1_0.0
 281    */
 282   void MainLoop();
 283
 284   /**
 285    * @brief This lowers the application to bottom without actually quitting it.
 286    * @SINCE_1_0.0
 287    */
 288   void Lower();
 289
 290   /**
 291    * @brief This quits the application.  Tizen applications should use Lower to improve re-start performance unless they need to Quit completely.
 292    * @SINCE_1_0.0
 293    */
 294   void Quit();
 295
 296   /**
 297    * @brief Ensures that the function passed in is called from the main loop when it is idle.
 298    * @SINCE_1_0.0
 299    * @param[in] callback The function to call
 300    * @return @c true if added successfully, @c false otherwise
 301    *
 302    * @note Function must be called from main event thread only
 303    *
 304    * A callback of the following type may be used:
 305    * @code
 306    *   void MyFunction();
 307    * @endcode
 308    * This callback will be deleted once it is called.
 309    *
 310    * @note Ownership of the callback is passed onto this class.
 311    */
 312   bool AddIdle(CallbackBase* callback);
 313
 314   /**
 315    * @brief Retrieves the main window used by the Application class.
 316    *
 317    * The application writer can use the window to change indicator and orientation
 318    * properties.
 319    * @SINCE_1_0.0
 320    * @return A handle to the window
 321    */
 322   Window GetWindow();
 323
 324   /**
 325    * @brief Get path application resources are stored at
 326    *
 327    * @SINCE_1_2.2
 328    * @return the full path of the resources
 329    */
 330   static std::string GetResourcePath();
 331
 332   /**
 333    * @brief This is used to get region information from device.
 334    *
 335    * @SINCE_1_2.62
 336    * @return Region information
 337    */
 338   std::string GetRegion() const;
 339
 340   /**
 341    * @brief This is used to get language information from device.
 342    *
 343    * @SINCE_1_2.62
 344    * @return Language information
 345    */
 346   std::string GetLanguage() const;
 347
 348   /**
 349    * @brief Gets the Object registry.
 350    *
 351    * @SINCE_1_9.21
 352    * @return The object registry
 353    * @note This will only be a valid handle after the InitSignal has been emitted.
 354    */
 355   ObjectRegistry GetObjectRegistry() const;
 356
 357 public: // Signals
 358   /**
 359    * @brief The user should connect to this signal to determine when they should initialize
 360    * their application.
 361    * Only when the user uses the UI thread, this signal is emitted on the UI thread.
 362    * Otherwise, it is emitted on the main thread.
 363    * @SINCE_1_0.0
 364    * @return The signal to connect to
 365    */
 366   AppSignalType& InitSignal();
 367
 368   /**
 369    * @brief The user should connect to this signal to determine when they should terminate
 370    * their application.
 371    * Only when the user uses the UI thread, this signal is emitted on the UI thread.
 372    * Otherwise, it is emitted on the main thread.
 373    * @SINCE_1_0.0
 374    * @return The signal to connect to
 375    */
 376   AppSignalType& TerminateSignal();
 377
 378   /**
 379    * @brief The user should connect to this signal if they need to perform any special
 380    * activities when the application is about to be paused.
 381    * Only when the user uses the UI thread, this signal is emitted on the UI thread.
 382    * Otherwise, it is emitted on the main thread.
 383    * @SINCE_1_0.0
 384    * @return The signal to connect to
 385    */
 386   AppSignalType& PauseSignal();
 387
 388   /**
 389    * @brief The user should connect to this signal if they need to perform any special
 390    * activities when the application has resumed.
 391    * Only when the user uses the UI thread, this signal is emitted on the UI thread.
 392    * Otherwise, it is emitted on the main thread.
 393    * @SINCE_1_0.0
 394    * @return The signal to connect to
 395    */
 396   AppSignalType& ResumeSignal();
 397
 398   /**
 399    * @brief This signal is sent when the system requires the user to reinitialize itself.
 400    * Only when the user uses the UI thread, this signal is emitted on the UI thread.
 401    * Otherwise, it is emitted on the main thread.
 402    * @SINCE_1_0.0
 403    * @return The signal to connect to
 404    */
 405   AppSignalType& ResetSignal();
 406
 407   /**
 408    * @brief This signal is emitted when another application sends a launch request to the application.
 409    *
 410    * When the application is launched, this signal is emitted after the main loop of the application starts up.
 411    * The passed parameter describes the launch request and contains the information about why the application is launched.
 412    * Only when the user uses the UI thread, this signal is emitted on the UI thread.
 413    * Otherwise, it is emitted on the main thread.
 414    * @SINCE_1_0.0
 415    * @return The signal to connect to
 416    */
 417   AppControlSignalType& AppControlSignal();
 418
 419   /**
 420    * @brief This signal is emitted when the language is changed on the device.
 421    * Only when the user uses the UI thread, this signal is emitted on the UI thread.
 422    * Otherwise, it is emitted on the main thread.
 423    * @SINCE_1_0.0
 424    * @return The signal to connect to
 425    */
 426   AppSignalType& LanguageChangedSignal();
 427
 428   /**
 429    * @brief This signal is emitted when the region of the device is changed.
 430    * Only when the user uses the UI thread, this signal is emitted on the UI thread.
 431    * Otherwise, it is emitted on the main thread.
 432    * @SINCE_1_0.0
 433    * @return The signal to connect to
 434    */
 435   AppSignalType& RegionChangedSignal();
 436
 437   /**
 438    * @brief This signal is emitted when the battery level of the device is low.
 439    * Only when the user uses the UI thread, this signal is emitted on the UI thread.
 440    * Otherwise, it is emitted on the main thread.
 441    * @SINCE_1_2.62
 442    * @return The signal to connect to
 443    */
 444   LowBatterySignalType& LowBatterySignal();
 445
 446   /**
 447    * @brief This signal is emitted when the memory level of the device is low.
 448    * Only when the user uses the UI thread, this signal is emitted on the UI thread.
 449    * Otherwise, it is emitted on the main thread.
 450    * @SINCE_1_2.62
 451    * @return The signal to connect to
 452    */
 453   LowMemorySignalType& LowMemorySignal();
 454
 455   /**
 456    * @brief This signal is emitted when the device orientation is changed
 457    * Only when the user uses the UI thread, this signal is emitted on the UI thread.
 458    * Otherwise, it is emitted on the main thread.
 459    *
 460    * This signal is only used in Application, it is different to Window's orientation signal.
 461    * @SINCE_2_2.1
 462    * @return The signal to connect to
 463    */
 464   DeviceOrientationChangedSignalType& DeviceOrientationChangedSignal();
 465
 466   // TaskSignal
 467   /**
 468    * @brief The user should connect to this signal to determine when they should initialize
 469    * their application.
 470    * Only when the user uses the UI thread, this signal is emitted on the main thread.
 471    * Otherwise, it is not emitted at all.
 472    * @return The signal to connect to
 473    */
 474   AppSignalType& TaskInitSignal();
 475
 476   /**
 477    * @brief The user should connect to this signal to determine when they should terminate
 478    * their application.
 479    * Only when the user uses the UI thread, this signal is emitted on the main thread.
 480    * Otherwise, it is not emitted at all.
 481    * @return The signal to connect to
 482    */
 483   AppSignalType& TaskTerminateSignal();
 484
 485   /**
 486    * @brief This signal is emitted when another application sends a launch request to the application.
 487    *
 488    * When the application is launched, this signal is emitted after the main loop of the application starts up.
 489    * The passed parameter describes the launch request and contains the information about why the application is launched.
 490    * Only when the user uses the UI thread, this signal is emitted on the main thread.
 491    * Otherwise, it is not emitted at all.
 492    * @return The signal to connect to
 493    */
 494   AppControlSignalType& TaskAppControlSignal();
 495
 496   /**
 497    * @brief This signal is emitted when the language is changed on the device.
 498    * Only when the user uses the UI thread, this signal is emitted on the main thread.
 499    * Otherwise, it is not emitted at all.
 500    * @return The signal to connect to
 501    */
 502   AppSignalType& TaskLanguageChangedSignal();
 503
 504   /**
 505    * @brief This signal is emitted when the region of the device is changed.
 506    * Only when the user uses the UI thread, this signal is emitted on the main thread.
 507    * Otherwise, it is not emitted at all.
 508    * @return The signal to connect to
 509    */
 510   AppSignalType& TaskRegionChangedSignal();
 511
 512   /**
 513    * @brief This signal is emitted when the battery level of the device is low.
 514    * Only when the user uses the UI thread, this signal is emitted on the main thread.
 515    * Otherwise, it is not emitted at all.
 516    * @return The signal to connect to
 517    */
 518   LowBatterySignalType& TaskLowBatterySignal();
 519
 520   /**
 521    * @brief This signal is emitted when the memory level of the device is low.
 522    * Only when the user uses the UI thread, this signal is emitted on the main thread.
 523    * Otherwise, it is not emitted at all.
 524    * @return The signal to connect to
 525    */
 526   LowMemorySignalType& TaskLowMemorySignal();
 527
 528   /**
 529    * @brief This signal is emitted when the device orientation is changed.
 530    * Only when the user uses the UI thread, this signal is emitted on the main thread.
 531    * Otherwise, it is not emitted at all.
 532    * @SINCE_2_2.1
 533    * @return The signal to connect to
 534    */
 535   DeviceOrientationChangedSignalType& TaskDeviceOrientationChangedSignal();
 536
 537 public: // Not intended for application developers
 538   /// @cond internal
 539   /**
 540    * @brief Internal constructor.
 541    * @SINCE_1_0.0
 542    */
 543   explicit DALI_INTERNAL Application(Internal::Adaptor::Application* application);
 544   /// @endcond
 545 };
 546
 547 /**
 548  * @}
 549  */
 550 } // namespace Dali
 551
 552 #endif // DALI_APPLICATION_H