dali/internal/adaptor/common/framework.h

   1 #ifndef DALI_INTERNAL_ADAPTOR_COMMON_FRAMEWORK_H
   2 #define DALI_INTERNAL_ADAPTOR_COMMON_FRAMEWORK_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/signals/callback.h>
  23 #include <functional>
  24 #include <string>
  25 #ifdef APPCORE_WATCH_AVAILABLE
  26 #include <dali/public-api/watch/watch-application.h>
  27 #endif
  28
  29 // INTERNAL INCLUDES
  30 #include <dali/internal/system/common/abort-handler.h>
  31 #include <dali/public-api/adaptor-framework/device-status.h>
  32
  33 #ifdef COMPONENT_APPLICATION_SUPPORT
  34 #include <dali/devel-api/adaptor-framework/component-application.h>
  35 #endif
  36
  37 namespace Dali
  38 {
  39 namespace Internal
  40 {
  41 namespace Adaptor
  42 {
  43 /**
  44  * The Framework class is ideally placed to provide key API required by Applications.
  45  *
  46  * The class is also used to register callbacks with the TIZEN platform so that
  47  * we know when any of the application lifecycle events occur.  This includes events
  48  * like when our application is to be initialised, terminated, paused, resumed etc.
  49  */
  50 class Framework
  51 {
  52 public:
  53   enum Type
  54   {
  55     NORMAL,   ///< normal appFramework
  56     WATCH,    ///< watch appFramework
  57     WIDGET,   ///< widget appFramework
  58     COMPONENT ///< component appFramework
  59   };
  60
  61   /**
  62    * Observer class for the framework.
  63    * @brief When the UI thread is enabled, the events are emitted on the UI thread.
  64    * When it is disabled, the events are emitted on the main thread.
  65    */
  66   class Observer
  67   {
  68   public:
  69     /**
  70      * Invoked when the application is to be initialised.
  71      */
  72     virtual void OnInit()
  73     {
  74     }
  75
  76     /**
  77      * Invoked when the application is to be terminated.
  78      */
  79     virtual void OnTerminate()
  80     {
  81     }
  82
  83     /**
  84      * Invoked when the application is to be paused.
  85      */
  86     virtual void OnPause()
  87     {
  88     }
  89
  90     /**
  91      * Invoked when the application is to be resumed.
  92      */
  93     virtual void OnResume()
  94     {
  95     }
  96
  97     /**
  98      * Invoked when the application is to be reset.
  99      */
 100     virtual void OnReset()
 101     {
 102     }
 103
 104     /**
 105      * Invoked when the AppControl message is received.
 106      * @param[in] The bundle data of AppControl message.
 107      */
 108     virtual void OnAppControl(void*)
 109     {
 110     }
 111
 112 #ifdef APPCORE_WATCH_AVAILABLE
 113     /**
 114      * Invoked at every second
 115      */
 116     virtual void OnTimeTick(WatchTime&)
 117     {
 118     }
 119
 120     /**
 121      * Invoked at every second in ambient mode
 122      */
 123     virtual void OnAmbientTick(WatchTime&)
 124     {
 125     }
 126
 127     /**
 128      * Invoked when the device enters or exits ambient mode
 129      */
 130     virtual void OnAmbientChanged(bool ambient)
 131     {
 132     }
 133 #endif
 134
 135     /**
 136      * Invoked when the language of the device is changed.
 137      */
 138     virtual void OnLanguageChanged()
 139     {
 140     }
 141
 142     /**
 143      * Invoked when the region is changed.
 144      */
 145     virtual void OnRegionChanged()
 146     {
 147     }
 148
 149     /**
 150      * Invoked when the battery level of the device is low.
 151      */
 152     virtual void OnBatteryLow(Dali::DeviceStatus::Battery::Status status)
 153     {
 154     }
 155
 156     /**
 157      * Invoked when the memory level of the device is low.
 158      */
 159     virtual void OnMemoryLow(Dali::DeviceStatus::Memory::Status status)
 160     {
 161     }
 162
 163     /**
 164      * Invoked when the device orientation is changed.
 165      */
 166     virtual void OnDeviceOrientationChanged(Dali::DeviceStatus::Orientation::Status status)
 167     {
 168     }
 169
 170     /**
 171      * Invoked when the platform surface is created.
 172      */
 173     virtual void OnSurfaceCreated(Any newSurface)
 174     {
 175     }
 176
 177     /**
 178      * Invoked when the platform surface is destroyed.
 179      */
 180     virtual void OnSurfaceDestroyed(Any newSurface)
 181     {
 182     }
 183
 184 #ifdef COMPONENT_APPLICATION_SUPPORT
 185     /**
 186      * Invoked when the component application is created.
 187      */
 188     virtual Any OnCreate()
 189     {
 190       return nullptr;
 191     }
 192 #endif
 193   };
 194
 195   /**
 196    * TaskObserver class for the framework.
 197    * @brief This is used only when UiThread is enabled. the events are emitted on the main thread.
 198    */
 199   class TaskObserver
 200   {
 201   public:
 202     /**
 203      * Invoked when the application is to be initialised.
 204      */
 205     virtual void OnTaskInit()
 206     {
 207     }
 208
 209     /**
 210      * Invoked when the application is to be terminated.
 211      */
 212     virtual void OnTaskTerminate()
 213     {
 214     }
 215
 216     /**
 217      * Invoked when the AppControl message is received.
 218      * @param[in] The bundle data of AppControl message.
 219      */
 220     virtual void OnTaskAppControl(void*)
 221     {
 222     }
 223
 224     /**
 225      * Invoked when the language of the device is changed.
 226      */
 227     virtual void OnTaskLanguageChanged()
 228     {
 229     }
 230
 231     /**
 232      * Invoked when the region is changed.
 233      */
 234     virtual void OnTaskRegionChanged()
 235     {
 236     }
 237
 238     /**
 239      * Invoked when the battery level of the device is low.
 240      */
 241     virtual void OnTaskBatteryLow(Dali::DeviceStatus::Battery::Status status)
 242     {
 243     }
 244
 245     /**
 246      * Invoked when the memory level of the device is low.
 247      */
 248     virtual void OnTaskMemoryLow(Dali::DeviceStatus::Memory::Status status)
 249     {
 250     }
 251
 252     /**
 253      * Invoked when the device orientation is changed.
 254      *
 255      * Device orientation changed event is from Application Framework(Sensor Framework), it means it is system event.
 256      * If UIThreading is enable, DALI application has the main thread and UI thread.
 257      * This event is emitted in main thread, then it is posted to the UI thread in this callback function.
 258      */
 259     virtual void OnTaskDeviceOrientationChanged(Dali::DeviceStatus::Orientation::Status status)
 260     {
 261     }
 262   };
 263
 264 public:
 265   /**
 266    * Constructor
 267    * @param[in]  observer      The observer of the Framework.
 268    * @param[in]  taskObserver  The task observer of the Framework.
 269    * @param[in]  argc          A pointer to the number of arguments.
 270    * @param[in]  argv          A pointer the the argument list.
 271    * @param[in]  type          The type of application
 272    * @param[in]  useUiThread   True if the application would create a UI thread
 273    */
 274   Framework(Observer& observer, TaskObserver& taskObserver, int* argc, char*** argv, Type type, bool useUiThread);
 275
 276   /**
 277    * Destructor
 278    */
 279   virtual ~Framework();
 280
 281 public:
 282   /**
 283    * Runs the main loop of framework
 284    */
 285   virtual void Run() = 0;
 286
 287   /**
 288    * Quits the main loop
 289    */
 290   virtual void Quit() = 0;
 291
 292   /**
 293    * Gets system language.
 294    */
 295   virtual std::string GetLanguage() const;
 296
 297   /**
 298    * Gets system region.
 299    */
 300   virtual std::string GetRegion() const;
 301
 302   /**
 303    * Gets the context of the main loop
 304    * @return Platform dependent context handle
 305    */
 306   virtual Any GetMainLoopContext() const;
 307
 308   /**
 309    * Checks whether the main loop of the framework is running.
 310    * @return true, if the main loop is running, false otherwise.
 311    */
 312   bool IsMainLoopRunning();
 313
 314   /**
 315    * If the main loop aborts unexpectedly, then the connected callback function is called.
 316    * @param[in]  callBack  The function to call.
 317    * @note Only one callback can be registered.  The last callback to be set will be called on abort.
 318    * @note The ownership of callback is passed onto this class.
 319    */
 320   void AddAbortCallback(CallbackBase* callback);
 321
 322   /**
 323    * Sets a command line options.
 324    * This is used in case of the preinitialized application.
 325    * @param[in] argc A pointer to the number of arguments
 326    * @param[in] argv A pointer to the argument list
 327    */
 328   void SetCommandLineOptions(int* argc, char** argv[])
 329   {
 330     mArgc = argc;
 331     mArgv = argv;
 332   }
 333
 334 private:
 335   /**
 336    * Called if the application is aborted.
 337    */
 338   void AbortCallback();
 339
 340 private:
 341   // Undefined
 342   Framework(const Framework&) = delete;
 343   Framework& operator=(Framework&) = delete;
 344
 345 protected:
 346   Observer&                     mObserver;
 347   TaskObserver&                 mTaskObserver;
 348   AbortHandler                  mAbortHandler;
 349   int*                          mArgc;
 350   char***                       mArgv;
 351   std::unique_ptr<CallbackBase> mAbortCallBack;
 352   bool                          mRunning;
 353 };
 354
 355 class UIThreadLoader
 356 {
 357 public:
 358   using Runner = std::function<void()>;
 359
 360   /**
 361    * Constructor
 362    * @param[in] argc A pointer to the number of arguments.
 363    * @param[in] argv A pointer the the argument list.
 364    */
 365   UIThreadLoader(int* argc, char*** argv);
 366
 367   /**
 368    * Destructor
 369    */
 370   ~UIThreadLoader();
 371
 372 public:
 373   /**
 374    * Runs the main loop of framework
 375    */
 376   void Run(Runner runner);
 377
 378 private:
 379   // Undefined
 380   UIThreadLoader(const UIThreadLoader&) = delete;
 381   UIThreadLoader& operator=(UIThreadLoader&) = delete;
 382
 383 private:
 384   int*    mArgc;
 385   char*** mArgv;
 386
 387 private: // impl members
 388   struct Impl;
 389   Impl* mImpl;
 390 };
 391
 392 } // namespace Adaptor
 393
 394 } // namespace Internal
 395
 396 } // namespace Dali
 397
 398 #endif // DALI_INTERNAL_ADAPTOR_COMMON_FRAMEWORK_H