docs/content/programming-guide/dali-application.h

   1 /*! \page dali-application Dali Application and Adaptor
   2  *
   3 <h2 class="pg">Creating an Application</h2>
   4
   5 The Adaptor framework provides several classes which intialises and sets up Dali appropriately so that the application writer does not have to.  These classes also provides many platform related services (e.g. orienation change notifications, timer services etc.).
   6
   7 The simplest way to create an application that uses Dali is to utilise the Dali::Application class.  In addition to initialising the environment used by Dali, it also provides several signals which the user can connect to when certain platform related activities occur.  It also ensures that, upon system events, Dali is called in a thread-safe manner.
   8
   9 The following example shows how to create a Dali::Application instance and connect to its initialise signal (which is where a Dali::Actor hierarchy should be created).
  10
  11 @code
  12 void CreateProgram(Application& app)
  13 {
  14   // Create Dali components...
  15   Dali::Actor actor = Actor::New();
  16   ...
  17 }
  18
  19 int main (int argc, char **argv)
  20 {
  21   Application app = Application::New(&argc, &argv);
  22   app.InitSignal().Connect(&CreateProgram);
  23   app.MainLoop();
  24 }
  25 @endcode
  26
  27 Please see the Dali::Application class for other signals to which the application can connect.
  28
  29 <h2 class="pg">Using an Adaptor or EvasPlugin instead of the Application class</h2>
  30
  31 If the application requires finer grained control, an Dali::Adaptor can be created instead.  This allows the application writer to create other platform related functionality themselves (e.g managing the main loop, providing a surface to render to etc.).
  32
  33 When using the Adaptor, the application writer can specify the use of normal window creation and drawing by using the New method with an appropriate Window.
  34
  35 If the application writer wants Dali to draw to a specific surface then they need to create a Dali::RenderSurface instance and use the Adaptor constructor which takes the Dali::RenderSurface as the parameter.
  36
  37 The only signal provided by the adaptors is a <i>surface resized signal</i>; the application writer will have to handle system signals like <i>initialise, pause, terminate </i> etc. themselves.  It is also important that any calls to Dali are made in a thread-safe manner from your application when using the adaptor directly.
  38
  39 An adaptor can be created as shown below:
  40
  41 @code
  42 void CreateProgram(void* data)
  43 {
  44   // Start Adaptor
  45   Dali::Adaptor* adaptor = reinterpret_cast<Dali::Adaptor*>(data);
  46   adaptor->Start();
  47
  48   // Create Dali components...
  49   // Can instantiate here, if required
  50 }
  51
  52 int main ()
  53 {
  54   // Initialise platform
  55   MyPlatform.Init();
  56
  57   // Create an 800 by 1280 window positioned at (0,0).
  58   Dali::PositionSize positionSize(0, 0, 800, 1280);
  59   Dali::Window window = Dali::Window::New( positionSize, "My Application" );
  60   Dali::Adaptor& adaptor = Dali::Adaptor::New( window );
  61
  62   // Assuming second parameter takes in data which is passed back to the callback function
  63   MyPlatform.InitialisationConnection(&CreateProgram, &adaptor);
  64
  65   // Start Main Loop of your platform
  66   MyPlatform.StartMainLoop();
  67
  68   return 0;
  69 }
  70 @endcode
  71
  72 A Dali::EvasPlugin instance can be created by EFL applications that wish to use Dali.  Like the Adaptor, it also provides a means for initialising the resources required by the Dali::Core.
  73
  74 The Dali::EvasPlugin emits several signals which the user can connect to.  The user should not create any Dali objects in the main function and instead should connect to the Init signal of the EvasPlugin and create the Dali objects in the connected callback.
  75
  76 A Dali::EvasPlugin can be used in an EFL application as shown below:
  77
  78 @code
  79 void Created(EvasPlugin& evasPlugin)
  80 {
  81   // Create Dali components...
  82   // Can instantiate here, if required
  83 }
  84
  85 void Resized(EvasPlugin& evasPlugin)
  86 {
  87   // Set size properties of Dali components
  88   // Set screen layout
  89 }
  90
  91 int main (int argc, char **argv)
  92 {
  93   // Initialise Elementary
  94   elm_init(&argc, &argv);
  95
  96   // Create an Evas Window
  97   Evas_Object* win = elm_win_add(...);
  98
  99   // Get the actual window
 100   Evas* e = evas_object_evas_get(win);
 101
 102   // Create the EvasPlugin and pass the actual window
 103   Dali::EvasPlugin evasPlugin = Dali::EvasPlugin(e);
 104
 105   evasPlugin.SignalInit().Connect(&Created);
 106   evasPlugin.SignalResize().Connect(&Resized);
 107
 108   // Retrieve the Evas_Object from the plugin and show it.
 109   Evas_Object* evasObject = evasPlugin.GetEvasObject();
 110   evas_object_show(evasObject);
 111
 112   // add evasObject to layout such as elm_box
 113
 114   // Start main loop
 115   elm_run();
 116 }
 117 @endcode
 118
 119 <h2 class="pg">Window</h2>
 120 Dali provides a Window class to manage drawing to a default surface. It is also responsible for drawing the Indicator bar if required. The Application class automatically creates a Window which the application author can access after the SignalInit has fired.
 121
 122 @code
 123 void CreateProgram(Application& app)
 124 {
 125   app.GetWindow().ShowIndicator(Dali::Window::VISIBLE);
 126 }
 127
 128 int main (int argc, char **argv)
 129 {
 130   Application app = Application::New(argc, argv);
 131   app.SignalInit().Connect(&CreateProgram);
 132   app.MainLoop();
 133 }
 134 @endcode
 135
 136 <h2 class="pg">Orientation</h2>
 137
 138 The Adaptor Framework also provides a means of retrieving the current device orientation and connection to a signal when the orientation of the device changes.  The Dali::Application class provides access to an already created Dali::Orientation object.  If using a Dali::Adaptor, an instance of the Dali::Orientation class has to be created in the application.
 139
 140 The following example shows how to connect to an orientation changed signal through the Dali::Application class:
 141
 142 @code
 143 void OrientationChanged(const Orientation& orientation)
 144 {
 145   int degrees = orientation.GetDegrees();
 146   ...
 147 }
 148
 149 int main(int argc, char **argv)
 150 {
 151   Application app = Application::New(&argc, &argv);
 152   app.GetWindow().GetOrientation().SignalChanged().Connect(&OrientationChanged);
 153 }
 154 @endcode
 155
 156 <h2 class="pg">Timers</h2>
 157
 158 Timers are also provided by the Adaptor Framework so that the application writer can execute a portion of their code periodically or just once, after a delay.  The example below shows how a Dali::Timer can be created and used:
 159
 160 @code
 161 bool Tick()
 162 {
 163   ...
 164   return true; // Timer continues, i.e. this function will be called again after the specified time has elapsed.
 165 }
 166
 167 ...
 168
 169 // Elsewhere
 170 Timer timer = Timer::New(2000); // 2 second timeout
 171 timer.SignalTick().Connect(&Tick);
 172 ...
 173 @endcode
 174
 175  */