adaptors/devel-api/adaptor-framework/widget-application.h

   1 #ifndef __DALI_WIDGET_APPLICATION_H__
   2 #define __DALI_WIDGET_APPLICATION_H__
   3
   4 /*
   5  * Copyright (c) 2017 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/dali-signal.h>
  24 #include <dali/public-api/signals/callback.h>
  25 #include <bundle.h>
  26
  27 // INTERNAL INCLUDES
  28 #ifdef DALI_ADAPTOR_COMPILATION  // full path doesn't exist until adaptor is installed so we have to use relative
  29 #include <device-status.h>
  30 #else
  31 #include <dali/public-api/adaptor-framework/device-status.h>
  32 #endif
  33
  34 // INTERNAL INCLUDES
  35
  36 namespace Dali
  37 {
  38
  39 namespace Internal DALI_INTERNAL
  40 {
  41 namespace Adaptor
  42 {
  43 class WidgetApplication;
  44 }
  45 }
  46
  47 class Window;
  48
  49 /**
  50  * @brief An WidgetApplication class object should be created by every widget application
  51  * that wishes to use Dali.
  52  *
  53  * It provides a means for initializing the
  54  * resources required by the Dali::Core.
  55  *
  56  * The WidgetApplication class emits several signals which the user can
  57  * connect to.  The user should not create any Dali objects in the main
  58  * function and instead should connect to the Init signal of the
  59  * WidgetApplication and create the Dali Widget object in the connected callback.
  60  *
  61  * WidgetApplications should follow the example below:
  62  *
  63  * @code
  64  * class ExampleController: public ConnectionTracker
  65  * {
  66  * public:
  67  *   ExampleController( WidgetApplication& widgetApplication )
  68  *   : mWidgetApplication( widgetApplication )
  69  *   {
  70  *     mWidgetApplication.InitSignal().Connect( this, &ExampleController::Create );
  71  *   }
  72  *
  73  *   void Create( WidgetApplication& widgetApplication )
  74  *   {
  75  *     Widget widget = Widget::New( WIDGET_ID );
  76  *     widget.CreateSignal( this, &ExampleController::WidgetCreate );
  77  *   }
  78  *
  79  *   void WidgetCreate( const std::string& id, bundle* content, Window window )
  80  *   {
  81  *     // Do Dali components...
  82  *   }
  83  *  ...
  84  * private:
  85  *   WidgetApplication& mWidgetApplication;
  86  * };
  87  *
  88  * int main (int argc, char **argv)
  89  * {
  90  *   WidgetApplication app = WidgetApplication::New(&argc, &argv);
  91  *   ExampleController example( app );
  92  *   app.MainLoop();
  93  * }
  94  * @endcode
  95  *
  96  * If required, you can also connect class member functions to a signal:
  97  *
  98  * @code
  99  * MyWidgetApplication app;
 100  * app.ResumeSignal().Connect(&app, &MyWidgetApplication::Resume);
 101  * @endcode
 102  *
 103  * @SINCE_1_2.62
 104  */
 105 class DALI_IMPORT_API WidgetApplication : public BaseHandle
 106 {
 107 public:
 108
 109   typedef Signal< void (WidgetApplication&) > AppSignalType;                   ///< Widget application lifecycle signal and system signal callback type
 110   typedef Signal< void (DeviceStatus::Battery::Status) > LowBatterySignalType; ///< Widget application device signal type
 111   typedef Signal< void (DeviceStatus::Memory::Status) > LowMemorySignalType;   ///< Widget application device signal type
 112
 113 public:
 114
 115   /**
 116    * @brief This is the constructor for WidgetApplications with a name.
 117    *
 118    * @param[in,out]  argc        A pointer to the number of arguments
 119    * @param[in,out]  argv        A pointer to the argument list
 120    * @param[in]      stylesheet  The path to user defined theme file
 121    * @return A handle to the WidgetApplication
 122    * @note If the stylesheet is not specified, then the library's default stylesheet will not be overridden.
 123    */
 124   static WidgetApplication New( int* argc, char **argv[], const std::string& stylesheet );
 125
 126   /**
 127    * @brief The default constructor.
 128    *
 129    */
 130   WidgetApplication();
 131
 132   /**
 133    * @brief Copy Constructor.
 134    * @param[in] WidgetApplication Handle to an object
 135    */
 136   WidgetApplication( const WidgetApplication& widgetApplication );
 137
 138   /**
 139    * @brief Assignment operator.
 140    * @param[in] WidgetApplication Handle to an object
 141    * @return A reference to this
 142    */
 143   WidgetApplication& operator=( const WidgetApplication& widgetApplication );
 144
 145  /**
 146    * @brief Destructor
 147    *
 148    */
 149   ~WidgetApplication();
 150
 151   /**
 152    * @brief This starts the application.
 153    */
 154   void MainLoop();
 155
 156   /**
 157    * @brief This quits the application.  Tizen applications should use Lower to improve re-start performance unless they need to Quit completely.
 158    */
 159   void Quit();
 160
 161   /**
 162    * @brief Get path application resources are stored at
 163    * @return the full path of the resources
 164    */
 165   static std::string GetResourcePath();
 166
 167   /**
 168    * @brief this is used to get region information from device.
 169    *
 170    * @return region information
 171    */
 172   std::string GetRegion();
 173
 174   /**
 175    * @brief this is used to get language information from device.
 176    *
 177    * @return language information
 178    */
 179   std::string GetLanguage();
 180
 181 public:  // Signals
 182
 183   /**
 184    * @brief The user should connect to this signal to determine when they should initialize
 185    * their application.
 186    * @return The signal to connect to
 187    */
 188   AppSignalType& InitSignal();
 189
 190   /**
 191    * @brief The user should connect to this signal to determine when they should terminate
 192    * their application.
 193    * @return The signal to connect to
 194    */
 195   AppSignalType& TerminateSignal();
 196
 197   /**
 198    * @brief This signal is emitted when the language is changed on the device.
 199    * @return The signal to connect to
 200    */
 201   AppSignalType& LanguageChangedSignal();
 202
 203   /**
 204   * @brief This signal is emitted when the region of the device is changed.
 205   * @return The signal to connect to
 206   */
 207   AppSignalType& RegionChangedSignal();
 208
 209   /**
 210   * @brief This signal is emitted when the battery level of the device is low.
 211   * @return The signal to connect to
 212   */
 213   LowBatterySignalType& LowBatterySignal();
 214
 215   /**
 216   * @brief This signal is emitted when the memory level of the device is low.
 217   * @return The signal to connect to
 218   */
 219   LowMemorySignalType& LowMemorySignal();
 220
 221 public: // Not intended for application developers
 222   /// @cond internal
 223   /**
 224    * @brief Internal constructor.
 225    */
 226   explicit DALI_INTERNAL WidgetApplication(Internal::Adaptor::WidgetApplication* widgetApplication);
 227   /// @endcond
 228 };
 229
 230 } // namespace Dali
 231
 232 #endif // ___DALI_WIDGET_APPLICATION_H__