dali/internal/adaptor/common/framework.h

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