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

   1 #ifndef __DALI_WIDGET_H__
   2 #define __DALI_WIDGET_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 <bundle.h>
  25
  26 namespace Dali
  27 {
  28 /**
  29  * @addtogroup dali_adaptor_framework
  30  * @{
  31  */
  32
  33 namespace Internal DALI_INTERNAL
  34 {
  35
  36 namespace Adaptor
  37 {
  38 class Widget;
  39 }
  40
  41 }
  42
  43 class Window;
  44
  45 /**
  46  * @brief Widget object should be created by WidgetApplication.
  47  *
  48  * The WidgetApplication class emits several widget instance lifecycle signals
  49  * which the user can connect to.
  50  * The user should connect to the CreateSignal of the Widget and
  51  * create the Dali Widget object in the connected callback.
  52  *
  53  * Widget should follow the example below:
  54  *
  55  * @code
  56  * class ExampleController: public ConnectionTracker
  57  * {
  58  * public:
  59  *   ExampleController( WidgetApplication& widgetApplication )
  60  *   : mWidgetApplication( widgetApplication )
  61  *   {
  62  *     mWidgetApplication.InitSignal().Connect( this, &ExampleController::Create );
  63  *   }
  64  *
  65  *   void Create( WidgetApplication& widgetApplication )
  66  *   {
  67  *     Widget widget = Widget::New( WIDGET_ID );
  68  *     widget.CreateSignal( this, &ExampleController::WidgetCreate );
  69  *   }
  70  *
  71  *   void WidgetCreate( const std::string& id, bundle* content, Window window )
  72  *   {
  73  *     // Do Dali components...
  74  *   }
  75  *  ...
  76  * private:
  77  *   WidgetApplication& mWidgetApplication;
  78  * };
  79  *
  80  * int main (int argc, char **argv)
  81  * {
  82  *   WidgetApplication app = WidgetApplication::New(&argc, &argv);
  83  *   ExampleController example( app );
  84  *   app.MainLoop();
  85  * }
  86  *
  87  * @SINCE_1_2.62
  88  */
  89 class DALI_IMPORT_API Widget : public BaseHandle
  90 {
  91 public:
  92
  93   /**
  94    * @brief Enumeration for terminate type of widget instance.
  95    * @SINCE_1_2.62
  96    */
  97   typedef enum
  98   {
  99     PERMANENT, //< User deleted this widget from the viewer @SINCE_1_2.62
 100     TEMPORARY, //< Widget is deleted because of other reasons (e.g. widget process is terminated temporarily by the system) @SINCE_1_2.62
 101   } WidgetTerminateType;
 102
 103   typedef Signal< void (const std::string&, bundle*, Window) > WidgetCreateSignalType;                  ///< Widget lifecycle signal type @SINCE_1_2.62
 104   typedef Signal< void (const std::string&, bundle*, WidgetTerminateType) > WidgetTerminateSignalType;  ///< Widget lifecycle signal type @SINCE_1_2.62
 105   typedef Signal< void (const std::string&) > WidgetPauseSignalType;                                    ///< Widget lifecycle signal type @SINCE_1_2.62
 106   typedef Signal< void (const std::string&) > WidgetResumeSignalType;                                   ///< Widget lifecycle signal type @SINCE_1_2.62
 107   typedef Signal< void (const std::string&, Window) > WidgetResizeSignalType;                           ///< Widget lifecycle signal type @SINCE_1_2.62
 108   typedef Signal< void (const std::string&, bundle*, int) > WidgetUpdateSignalType;                     ///< Widget lifecycle signal type @SINCE_1_2.62
 109
 110 public:
 111
 112   /**
 113    * @brief This is the constructor for Widget.
 114    * @SINCE_1_2.62
 115    * @param[in]  id  Id for widget class
 116    * @return A handle to the Widget
 117    */
 118   static Widget New( const std::string& id );
 119
 120   /**
 121    * @brief The default constructor.
 122    *
 123    */
 124   Widget();
 125
 126   /**
 127    * @brief Copy Constructor.
 128    * @SINCE_1_2.62
 129    * @param[in] Widget Handle to an object
 130    */
 131   Widget( const Widget& widget );
 132
 133   /**
 134    * @brief Assignment operator.
 135    * @SINCE_1_2.62
 136    * @param[in] Widget Handle to an object
 137    * @return A reference to this
 138    */
 139   Widget& operator=( const Widget& widget );
 140
 141   /**
 142    * @brief Destructor
 143    * @SINCE_1_2.62
 144    */
 145   ~Widget();
 146
 147 public:  // Signals
 148
 149   /**
 150    * @brief The user should connect to this signal to determine when they create widget.
 151    * @SINCE_1_2.62
 152    * @return The signal to connect to
 153    */
 154   WidgetCreateSignalType& CreateSignal();
 155
 156   /**
 157    * @brief The user should connect to this signal to determine when they terminate widget.
 158    * @SINCE_1_2.62
 159    * @return The signal to connect to
 160    */
 161   WidgetTerminateSignalType& TerminateSignal();
 162
 163   /**
 164    * @brief The user should connect to this signal to determine when they pause widget.
 165    * @SINCE_1_2.62
 166    * @return The signal to connect to
 167    */
 168   WidgetPauseSignalType& PauseSignal();
 169
 170   /**
 171    * @brief The user should connect to this signal to determine when they resume widget.
 172    * @SINCE_1_2.62
 173    * @return The signal to connect to
 174    */
 175   WidgetResumeSignalType& ResumeSignal();
 176
 177   /**
 178    * @brief The user should connect to this signal to determine when they resize widget.
 179    * @SINCE_1_2.62
 180    * @return The signal to connect to
 181    */
 182   WidgetResizeSignalType& ResizeSignal();
 183
 184   /**
 185    * @brief The user should connect to this signal to determine when they update widget.
 186    * @SINCE_1_2.62
 187    * @return The signal to connect to
 188    */
 189   WidgetUpdateSignalType& UpdateSignal();
 190
 191 public: // Not intended for application developers
 192   /// @cond internal
 193   /**
 194    * @brief Internal constructor.
 195    */
 196   explicit DALI_INTERNAL Widget(Internal::Adaptor::Widget* widget);
 197   /// @endcond
 198 };
 199
 200 /**
 201  * @}
 202  */
 203 } // namespace Dali
 204
 205 #endif // ___DALI_WIDGET_H__