dali-extension/devel-api/evas-plugin/evas-plugin.h

   1 #ifndef __DALI_EXTENSION_EVAS_PLUGIN_H__
   2 #define __DALI_EXTENSION_EVAS_PLUGIN_H__
   3
   4 /*
   5  * Copyright (c) 2019 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 /**
  22  * @addtogroup CAPI_DALI_EXTENSION_FRAMEWORK_MODULE
  23  * @{
  24  */
  25
  26 // EXTERNAL INCLUDES
  27 #include <Evas.h>
  28
  29 #include <dali/public-api/object/base-handle.h>
  30 #include <dali/public-api/signals/dali-signal.h>
  31
  32 namespace Dali
  33 {
  34
  35 namespace Extension
  36 {
  37
  38 namespace Internal
  39 {
  40 class EvasPlugin;
  41 }
  42
  43 /**
  44  * @brief Application class used by EFL applications that wish to use Dali
  45  *
  46  * An EvasPlugin class object should be created by EFL applications
  47  * that wish to use Dali. It provides a means for initializing the
  48  * resources required by the Dali::Core.
  49  *
  50  * The EvasPlugin class emits several signals which the user can
  51  * connect to.  The user should not create any Dali objects in the main
  52  * function and instead should connect to the Init signal of the
  53  * EvasPlugin and create the Dali objects in the connected callback.
  54  *
  55  * Tizen and EFL applications should follow the example below:
  56  *
  57  * @code
  58  * #include <app.h>
  59  * #include <app_extension.h>
  60  * #include <Elementary.h>
  61  *
  62  * #include <dali/dali.h>
  63  * #include <dali-toolkit/public-api/controls/default-controls/solid-color-actor.h>
  64  * #include <dali-extension/dali-extension.h>
  65  *
  66  * using namespace Dali;
  67  * using namespace Dali::Toolkit;
  68  * using namespace Dali::Extension;
  69  *
  70  * namespace
  71  * {
  72  * const char* const APPLICATION_TITLE = "EvasPluginExample";
  73  * const int EVAS_PLUGIN_WIDTH = 480;
  74  * const int EVAS_PLUGIN_HEIGHT = 800;
  75  * }
  76  *
  77  * class DaliApplication : public ConnectionTracker
  78  * {
  79  * public:
  80  *   DaliApplication(EvasPlugin evasPlugin)
  81  *   : mEvasPlugin(evasPlugin)
  82  *   {
  83  *     mEvasPlugin.InitSignal().Connect(this, &DaliApplication::OnInitialize);
  84  *     mEvasPlugin.Run();
  85  *   }
  86  *
  87  *   ~DaliApplication()
  88  *   {
  89  *     mEvasPlugin.Stop();
  90  *   }
  91  *
  92  *   void OnInitialize(EvasPlugin& evasPlugin)
  93  *   {
  94  *     Stage stage = Stage::GetCurrent();
  95  *
  96  *     TextLabel textLabel = TextLabel::New( "Hello World" );
  97  *     textLabel.SetAnchorPoint( AnchorPoint::TOP_LEFT );
  98  *     textLabel.SetName( "helloWorldLabel" );
  99  *     stage.Add( textLabel );
 100  *   }
 101  *
 102  * private:
 103  *   EvasPlugin mEvasPlugin;
 104  * };
 105  *
 106  * struct app_data
 107  * {
 108  *   Evas_Object* elm_win;
 109  *   DaliApplication* daliApplication;
 110  * };
 111  *
 112  * static void win_del(void *data, Evas_Object * obj, void *event_info)
 113  * {
 114  * }
 115  *
 116  * static bool app_create(void *data)
 117  * {
 118  *   struct app_data* ad = (struct app_data*)data;
 119  *
 120  *   // Sets the GL backend for rendering
 121  *   elm_config_accel_preference_set("3d");
 122  *
 123  *   // Creates the elm window
 124  *   ad->elm_win = elm_win_add(NULL, APPLICATION_TITLE, ELM_WIN_BASIC);
 125  *
 126  *   DALI_ASSERT_ALWAYS(ad->elm_win != NULL && "Fail to create elm window.");
 127  *
 128  *   elm_win_title_set(ad->elm_win, APPLICATION_TITLE);
 129  *   elm_win_rotation_with_resize_set(ad->elm_win, 0);
 130  *   evas_object_smart_callback_add(ad->elm_win, "delete,request", win_del, ad->elm_win);
 131  *   evas_object_show(ad->elm_win);
 132  *
 133  *   // Adds the background
 134  *   Evas_Object* bg = elm_bg_add(ad->elm_win);
 135  *   elm_bg_color_set(bg, 255, 255, 255);
 136  *   evas_object_size_hint_weight_set(bg, 0,0);
 137  *   elm_win_resize_object_add(ad->elm_win, bg);
 138  *   evas_object_show(bg);
 139  *
 140  *   // Creates an Evas plugin
 141  *   EvasPlugin evasPlugin = EvasPlugin::New(ad->elm_win, EVAS_PLUGIN_WIDTH, EVAS_PLUGIN_HEIGHT, true);
 142  *
 143  *   // Creates a Dali application
 144  *   ad->daliApplication = new DaliApplication(evasPlugin);
 145  *
 146  *   return true;
 147  * }
 148  *
 149  * static void app_terminate(void *data)
 150  * {
 151  *   struct app_data* ad = (struct app_data*)data;
 152  *
 153  *   delete ad->daliApplication;
 154  *   ad->daliApplication = NULL;
 155  * }
 156  *
 157  * static void app_pause(void *data)
 158  * {
 159  * }
 160  *
 161  * static void app_resume(void *data)
 162  * {
 163  * }
 164  *
 165  * static void app_control(app_control_h service, void *data)
 166  * {
 167  * }
 168  *
 169  * int main(int argc, char *argv[])
 170  * {
 171  *   // Initializes the Tizen application framework
 172  *   ui_app_lifecycle_callback_s event_callback;
 173  *
 174  *   event_callback.create = app_create;
 175  *   event_callback.terminate = app_terminate;
 176  *   event_callback.pause = app_pause;
 177  *   event_callback.resume = app_resume;
 178  *   event_callback.app_control = app_control;
 179  *
 180  *   struct app_data ad;
 181  *   memset(&ad, 0x0, sizeof(ad));
 182  *
 183  *   // Runs the Tizen application framework
 184  *   return ui_app_main(argc, argv, &event_callback, &ad);
 185  * }
 186  * @endcode
 187  */
 188 class DALI_IMPORT_API EvasPlugin : public BaseHandle
 189 {
 190 public:
 191
 192   typedef Signal<void (void)> EvasPluginSignalType;
 193
 194 public:
 195
 196   /**
 197    * @brief This is the constructor for Tizen EFL applications
 198    *
 199    * @param[in] parentEvasObject Parent of the new Evas object
 200    * @param[in] width The initial width of the Dali view port
 201    * @param[in] height The initial height of the Dali view port
 202    * @param[in] transparent Whether the Evas object is transparent or not
 203    */
 204   static EvasPlugin New(Evas_Object* parentEvasObject, int width, int height, bool transparent);
 205
 206   /**
 207    * @brief Constructs an empty handle
 208    */
 209   EvasPlugin();
 210
 211   /**
 212    * @brief Copy constructor
 213    */
 214   EvasPlugin(const EvasPlugin& evasPlugin);
 215
 216   /**
 217    * @brief Assignment operator
 218    */
 219   EvasPlugin& operator=(const EvasPlugin& evasPlugin);
 220
 221   /**
 222    * @brief Destructor
 223    */
 224   ~EvasPlugin();
 225
 226 public:
 227
 228   /**
 229    * @brief Runs the Evas plugin (rendering, event handling, etc)
 230    */
 231   void Run();
 232
 233   /**
 234    * @brief Pauses the Evas plugin
 235    */
 236   void Pause();
 237
 238   /**
 239    * @brief Resumes the Evas plugin
 240    */
 241   void Resume();
 242
 243   /**
 244    * @brief Stops the Evas plugin
 245    */
 246   void Stop();
 247
 248   /**
 249    * @brief This returns the Evas_Object* which is created internally for accessibility.
 250    *
 251    * Applications should append this access object to custom focus chain for accessibility
 252    *
 253    * e.g., elm_object_focus_custom_chain_append(layout, dali_access_object, NULL);
 254    *
 255    * @return Evas_Object* Elm access object which Dali image Evas object is registered
 256    */
 257   Evas_Object* GetDaliAccessEvasObject();
 258
 259   /**
 260    * @brief This returns the Evas_Object* which is created internally
 261    *
 262    * @return Evas_Object* Evas object which is rendered by Dali
 263    */
 264   Evas_Object* GetDaliEvasObject();
 265
 266 public:  // Signals
 267
 268   /**
 269    * @brief Signal to notify the client when the application is ready to be initialized
 270    *
 271    * @return The signal
 272    */
 273   EvasPluginSignalType& InitSignal();
 274
 275   /**
 276    * @brief Signal to notify the user when the application is about to be terminated
 277    *
 278    * @return The signal
 279    */
 280   EvasPluginSignalType& TerminateSignal();
 281
 282   /**
 283    * @brief Signal to notify the client when the adaptor is about to be paused
 284    *
 285    * The user should connect to this signal if the user needs to perform any special
 286    * activities when the application is about to be paused.
 287    * @return The signal
 288    */
 289   EvasPluginSignalType& PauseSignal();
 290
 291   /**
 292    * @brief Signal to notify the client when the adpator has resumed
 293    *
 294    * The user should connect to this signal if the user needs to perform any special
 295    * activities when the application has resumed.
 296    * @return The signal
 297    */
 298   EvasPluginSignalType& ResumeSignal();
 299
 300   /**
 301    * @brief Signal to notify the client when the Evas object is resized
 302    *
 303    * @return The signal
 304    */
 305   EvasPluginSignalType& ResizeSignal();
 306
 307   /**
 308    * @brief Signal to notify the client when the Evas object gets the keyboard focus
 309    *
 310    * @return The signal
 311    */
 312   EvasPluginSignalType& FocusedSignal();
 313
 314   /**
 315    * @brief Signal to notify the client when the Evas object loses the keyboard focus
 316    *
 317    * @return The signal
 318    */
 319   EvasPluginSignalType& UnFocusedSignal();
 320
 321 public: // Not intended for application developers
 322   /**
 323    * @brief Internal constructor
 324    */
 325   explicit DALI_INTERNAL EvasPlugin(Internal::EvasPlugin* evasPlugin);
 326 };
 327
 328 /**
 329  * @}
 330  */
 331
 332 }  // namespace Extension
 333
 334 }  // namespace Dali
 335
 336 #endif // __DALI_EXTENSION_EVAS_PLUGIN_H__