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

   1 #ifndef __DALI_APPLICATION_H__
   2 #define __DALI_APPLICATION_H__
   3
   4 /*
   5  * Copyright (c) 2015 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 <string>
  23 #include <dali/public-api/common/view-mode.h>
  24 #include <dali/public-api/object/base-handle.h>
  25 #include <dali/public-api/signals/callback.h>
  26
  27
  28 // INTERNAL INCLUDES
  29 #include "application-configuration.h"
  30 #include "device-layout.h"
  31 #include "window.h"
  32
  33 namespace Dali
  34 {
  35
  36 namespace Internal DALI_INTERNAL
  37 {
  38 namespace Adaptor
  39 {
  40 class Application;
  41 }
  42 }
  43
  44 /**
  45  * An Application class object should be created by every application
  46  * that wishes to use Dali.  It provides a means for initialising the
  47  * resources required by the Dali::Core.
  48  *
  49  * The Application class emits several signals which the user can
  50  * connect to.  The user should not create any Dali objects in the main
  51  * function and instead should connect to the Init signal of the
  52  * Application and create the Dali objects in the connected callback.
  53  *
  54  * Applications should follow the example below:
  55  *
  56  * @code
  57  * void CreateProgram(Application app)
  58  * {
  59  *   // Create Dali components...
  60  *   // Can instantiate here, if required
  61  * }
  62  *
  63  * int main (int argc, char **argv)
  64  * {
  65  *   Application app = Application::New(&argc, &argv);
  66  *   app.InitSignal().Connect(&CreateProgram);
  67  *   app.MainLoop();
  68  * }
  69  * @endcode
  70  *
  71  * If required, you can also connect class member functions to a signal:
  72  *
  73  * @code
  74  * MyApplication app;
  75  * app.ResumeSignal().Connect(&app, &MyApplication::Resume);
  76  * @endcode
  77  *
  78  * This class accepts command line arguments as well. The following options are supported:
  79  *
  80  * @code
  81  *     --no-vsync       Disable VSync on Render
  82  *  -w|--width          Stage Width
  83  *  -h|--height         Stage Height
  84  *  -d|--dpi            Emulated DPI
  85  *     --help           Help
  86  * @endcode
  87  *
  88  * When the above options are found, they are stripped from argv, and argc is updated appropriately.
  89  */
  90 class DALI_IMPORT_API Application : public BaseHandle
  91 {
  92 public:
  93
  94   typedef Signal< void (Application&) > AppSignalType;
  95   typedef Signal< void (Application&, void *) > AppControlSignalType;
  96
  97   /**
  98    * Decides whether a Dali application window is opaque or transparent.
  99    */
 100   enum WINDOW_MODE
 101   {
 102     OPAQUE = 0,       ///< The window will be opaque
 103     TRANSPARENT = 1   ///< The window transparency will match the alpha value set in Dali::Stage::SetBackgroundcolor()
 104   };
 105
 106 public:
 107
 108   /**
 109    * This is the constructor for applications without an argument list.
 110    *
 111    * @note The default base layout (DeviceLayout::DEFAULT_BASE_LAYOUT) will be used with this constructor.
 112    */
 113   static Application New();
 114
 115   /**
 116    * This is the constructor for applications.
 117    *
 118    * @param[in,out]  argc        A pointer to the number of arguments
 119    * @param[in,out]  argv        A pointer the the argument list
 120    *
 121    * @note The default base layout (DeviceLayout::DEFAULT_BASE_LAYOUT) will be used with this constructor.
 122    * @note Supported options are stripped from argv, and argc is updated appropriately.
 123    */
 124   static Application New( int* argc, char **argv[] );
 125
 126   /**
 127    * This is the constructor for applications with a name
 128    *
 129    * @param[in,out]  argc  A pointer to the number of arguments
 130    * @param[in,out]  argv  A pointer the the argument list
 131    * @param[in]  name  A name of application
 132    *
 133    * @note The default base layout (DeviceLayout::DEFAULT_BASE_LAYOUT) will be used with this constructor.
 134    * @note Supported options are stripped from argv, and argc is updated appropriately.
 135    */
 136   static Application New( int* argc, char **argv[], const std::string& name );
 137
 138   /**
 139    * This is the constructor for applications with a name, and also require a
 140    * transparent top-level window
 141    *
 142    * @param[in,out]  argc  A pointer to the number of arguments
 143    * @param[in,out]  argv  A pointer the the argument list
 144    * @param[in]  name  A name of application
 145    * @param[in]  windowMode A member of WINDOW_MODE
 146    *
 147    * @note The default base layout (DeviceLayout::DEFAULT_BASE_LAYOUT) will be used with this constructor.
 148    * @note Supported options are stripped from argv, and argc is updated appropriately.
 149    */
 150   static Application New( int* argc, char **argv[], const std::string& name, WINDOW_MODE windowMode );
 151
 152   /**
 153    * This is the constructor for applications when a layout for the application is specified.
 154    *
 155    * @param[in,out]  argc        A pointer to the number of arguments
 156    * @param[in,out]  argv        A pointer the the argument list
 157    * @param[in]  baseLayout  The base layout that the application has been written for
 158    *
 159    * @note Supported options are stripped from argv, and argc is updated appropriately.
 160    */
 161   static Application New( int* argc, char **argv[], const DeviceLayout& baseLayout );
 162
 163   /**
 164    * This is the constructor for applications with a name and when a layout for the application is specified.
 165    *
 166    * @param[in,out]  argc  A pointer to the number of arguments
 167    * @param[in,out]  argv  A pointer the the argument list
 168    * @param[in]  name  A name of application
 169    * @param[in]  baseLayout  The base layout that the application has been written for
 170    *
 171    * @note Supported options are stripped from argv, and argc is updated appropriately.
 172    */
 173   static Application New( int* argc, char **argv[], const std::string& name, const DeviceLayout& baseLayout );
 174
 175   /**
 176    * Construct an empty handle
 177    */
 178   Application();
 179
 180   /**
 181    * Copy Constructor
 182    */
 183   Application( const Application& application );
 184
 185   /**
 186    * Assignment operator
 187    */
 188   Application& operator=( const Application& applicaton );
 189
 190   /**
 191    * @brief Destructor
 192    *
 193    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 194    */
 195   ~Application();
 196
 197 public:
 198   /**
 199    * This starts the application. Choosing this form of main loop indicates that the default
 200    * application configuration of APPLICATION_HANDLES_CONTEXT_LOSS is used. On platforms where
 201    * context loss can occur, the application is responsible for tearing down and re-loading UI.
 202    * The application should listen to Stage::ContextLostSignal and Stage::ContextRegainedSignal.
 203    */
 204   void MainLoop();
 205
 206   /**
 207    * This starts the application, and allows the app to choose a different configuration.
 208    * If the application plans on using the ReplaceSurface or ReplaceWindow API, then this will
 209    * trigger context loss & regain.
 210    * The application should listen to Stage::ContextLostSignal and Stage::ContextRegainedSignal.
 211    */
 212   void MainLoop(Configuration::ContextLoss configuration);
 213
 214   /**
 215    * This lowers the application to bottom without actually quitting it
 216    */
 217   void Lower();
 218
 219   /**
 220    * This quits the application.  Tizen applications should use Lower to improve re-start performance unless they need to Quit completely.
 221    */
 222   void Quit();
 223
 224   /**
 225    * Ensures that the function passed in is called from the main loop when it is idle.
 226    *
 227    * A callback of the following type may be used:
 228    * @code
 229    *   void MyFunction();
 230    * @endcode
 231    *
 232    * @param[in]  callback  The function to call.
 233    * @return true if added successfully, false otherwise
 234    *
 235    * @note Ownership of the callback is passed onto this class.
 236    */
 237   bool AddIdle( CallbackBase* callback );
 238
 239   /**
 240    * Retrieves the window used by the Application class.
 241    * The application writer can use the window to change indicator and orientation
 242    * properties.
 243    * @return A handle to the window
 244    */
 245   Window GetWindow();
 246
 247   /**
 248    * Replace the current window.
 249    * This will force context loss.
 250    * If you plan on using this API in your application, then you should configure
 251    * it to prevent discard behaviour when handling the Init signal.
 252    * @param[in] windowPosition The position and size parameters of the new window
 253    * @param[in] name The name of the new window
 254    */
 255   void ReplaceWindow(PositionSize windowPosition, const std::string& name);
 256
 257 public: // Stereoscopy
 258
 259   /**
 260    * Set the viewing mode for the application.
 261    * @param[in] viewMode The new viewing mode.
 262    */
 263   void SetViewMode( ViewMode viewMode );
 264
 265   /**
 266    * Get the current viewing mode.
 267    * @return The current viewing mode.
 268    */
 269   ViewMode GetViewMode() const;
 270
 271   /**
 272    * Set the stereo base (eye separation) for Stereoscopic 3D
 273    *
 274    * @param[in] stereoBase The stereo base (eye separation) for Stereoscopic 3D
 275    */
 276   void SetStereoBase( float stereoBase );
 277
 278   /**
 279    * Get the stereo base (eye separation) for Stereoscopic 3D
 280    *
 281    * @return The stereo base (eye separation) for Stereoscopic 3D
 282    */
 283   float GetStereoBase() const;
 284
 285 public:  // Signals
 286
 287   /**
 288    * The user should connect to this signal to determine when they should initialise
 289    * their application.
 290    */
 291   AppSignalType& InitSignal();
 292
 293   /**
 294    * The user should connect to this signal to determine when they should terminate
 295    * their application
 296    */
 297   AppSignalType& TerminateSignal();
 298
 299   /**
 300    * The user should connect to this signal if they need to perform any special
 301    * activities when the application is about to be paused.
 302    */
 303   AppSignalType& PauseSignal();
 304
 305   /**
 306    * The user should connect to this signal if they need to perform any special
 307    * activities when the application has resumed.
 308    */
 309   AppSignalType& ResumeSignal();
 310
 311   /**
 312    * This signal is sent when the system requires the user to reinitialise itself.
 313    */
 314   AppSignalType& ResetSignal();
 315
 316   /**
 317    * This signal is emitted when the window the application is rendering on is resized.
 318    */
 319   AppSignalType& ResizeSignal();
 320
 321   /**
 322   * This signal is emitted when another application sends a launch request to the application.
 323   * When the application is launched, this signal is emitted after the main loop of the application starts up.
 324   * The passed parameter describes the launch request and contains the information about why the application is launched.
 325   */
 326   AppControlSignalType& AppControlSignal();
 327
 328   /**
 329    * This signal is emitted when the language is changed on the device.
 330    */
 331   AppSignalType& LanguageChangedSignal();
 332
 333   /**
 334   * This signal is emitted when the region of the device is changed.
 335   */
 336   AppSignalType& RegionChangedSignal();
 337
 338   /**
 339   * This signal is emitted when the battery level of the device is low.
 340   */
 341   AppSignalType& BatteryLowSignal();
 342
 343   /**
 344   * This signal is emitted when the memory level of the device is low.
 345   */
 346   AppSignalType& MemoryLowSignal();
 347
 348 public: // Not intended for application developers
 349   /**
 350    * Internal constructor
 351    */
 352   explicit DALI_INTERNAL Application(Internal::Adaptor::Application* application);
 353 };
 354
 355 } // namespace Dali
 356
 357 #endif // __DALI_APPLICATION_H__