dali/internal/adaptor/common/framework.h

   1 #ifndef DALI_INTERNAL_FRAMEWORK_H
   2 #define DALI_INTERNAL_FRAMEWORK_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/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
  32 #ifdef COMPONENT_APPLICATION_SUPPORT
  33 #include <dali/devel-api/adaptor-framework/component-application.h>
  34 #endif
  35
  36 namespace Dali
  37 {
  38 namespace Internal
  39 {
  40 namespace Adaptor
  41 {
  42 /**
  43  * The Framework class is ideally placed to provide key API required by Applications.
  44  *
  45  * The class is also used to register callbacks with the TIZEN platform so that
  46  * we know when any of the application lifecycle events occur.  This includes events
  47  * like when our application is to be initialised, terminated, paused, resumed etc.
  48  *
  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   ~Framework();
 280
 281 public:
 282   /**
 283    * Runs the main loop of framework
 284    */
 285   void Run();
 286
 287   /**
 288    * Quits the main loop
 289    */
 290   void Quit();
 291
 292   /**
 293    * Checks whether the main loop of the framework is running.
 294    * @return true, if the main loop is running, false otherwise.
 295    */
 296   bool IsMainLoopRunning();
 297
 298   /**
 299    * If the main loop aborts unexpectedly, then the connected callback function is called.
 300    * @param[in]  callBack  The function to call.
 301    * @note Only one callback can be registered.  The last callback to be set will be called on abort.
 302    * @note The ownership of callback is passed onto this class.
 303    */
 304   void AddAbortCallback(CallbackBase* callback);
 305
 306   /**
 307    * Gets bundle name which was passed in app_reset callback.
 308    */
 309   std::string GetBundleName() const;
 310
 311   /**
 312    * Gets bundle id which was passed in app_reset callback.
 313    */
 314   std::string GetBundleId() const;
 315
 316   /**
 317    * Sets a command line options.
 318    * This is used in case of the preinitialized application.
 319    * @param[in] argc A pointer to the number of arguments
 320    * @param[in] argv A pointer to the argument list
 321    */
 322   void SetCommandLineOptions(int* argc, char** argv[])
 323   {
 324     mArgc = argc;
 325     mArgv = argv;
 326   }
 327
 328   /**
 329    *  Gets the path at which application resources are stored.
 330    */
 331   static std::string GetResourcePath();
 332
 333   /**
 334    *  Gets the path at which application data are stored.
 335    */
 336   static std::string GetDataPath();
 337
 338   /**
 339    * Sets system language.
 340    */
 341   void SetLanguage(const std::string& language);
 342
 343   /**
 344    * Sets system region.
 345    */
 346   void SetRegion(const std::string& region);
 347
 348   /**
 349    * Gets system language.
 350    */
 351   std::string GetLanguage() const;
 352
 353   /**
 354    * Gets system region.
 355    */
 356   std::string GetRegion() const;
 357
 358   /**
 359    * Called by the App framework when an application lifecycle event occurs.
 360    * @param[in] type The type of event occurred.
 361    * @param[in] data The data of event occurred.
 362    */
 363   bool AppStatusHandler(int type, void* data);
 364
 365   /**
 366    * Called by the adaptor when an idle callback is added.
 367    * @param[in] timeout The timeout of the callback.
 368    * @param[in] data The data of of the callback.
 369    * @param[in] callback The callback.
 370    * @return The callback id.
 371    */
 372   unsigned int AddIdle(int timeout, void* data, bool (*callback)(void* data));
 373
 374   /**
 375    * Called by the adaptor when an idle callback is removed.
 376    * @param[in] id The callback id.
 377    */
 378   void RemoveIdle(unsigned int id);
 379
 380 private:
 381   // Undefined
 382   Framework(const Framework&);
 383   Framework& operator=(Framework&);
 384
 385 private:
 386   /**
 387    * Called when the application is created.
 388    */
 389   bool Create();
 390
 391   /**
 392    * Called app_reset callback was called with bundle.
 393    */
 394   void SetBundleName(const std::string& name);
 395
 396   /**
 397    * Called app_reset callback was called with bundle.
 398    */
 399   void SetBundleId(const std::string& id);
 400
 401   /**
 402    * Called if the application is aborted.
 403    */
 404   void AbortCallback();
 405
 406   /**
 407    * Called for initializing on specified backend. (X11 or Wayland)
 408    */
 409   void InitThreads();
 410
 411 private:
 412   Observer&     mObserver;
 413   TaskObserver& mTaskObserver;
 414   bool          mInitialised;
 415   bool          mPaused;
 416   bool          mRunning;
 417   int*          mArgc;
 418   char***       mArgv;
 419   std::string   mBundleName;
 420   std::string   mBundleId;
 421   AbortHandler  mAbortHandler;
 422
 423 private: // impl members
 424   struct Impl;
 425   Impl* mImpl;
 426 };
 427
 428 } // namespace Adaptor
 429
 430 } // namespace Internal
 431
 432 } // namespace Dali
 433
 434 #endif // DALI_INTERNAL_FRAMEWORK_H