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

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