public_api/widget_view/widget_view.h

   1 #ifndef __DALI_WIDGET_VIEW_WIDGET_VIEW_H__
   2 #define __DALI_WIDGET_VIEW_WIDGET_VIEW_H__
   3
   4 /*
   5  * Samsung API
   6  * Copyright (c) 2016 Samsung Electronics Co., Ltd.
   7  *
   8  * Licensed under the Flora License, Version 1.1 (the License);
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://floralicense.org/license/
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an AS IS BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <dali-toolkit/public-api/controls/control.h>
  23
  24 namespace Dali
  25 {
  26
  27 namespace WidgetView
  28 {
  29
  30 namespace Internal DALI_INTERNAL
  31 {
  32 class WidgetView;
  33 }
  34
  35 /**
  36  * @addtogroup dali_widget_view
  37  * @{
  38  */
  39
  40 /**
  41  * @brief WidgetView is a class for displaying the widget image and controlling the widget.
  42  * Input events that WidgetView gets are delivered to the widget.
  43  *
  44  * Signals
  45  * | %Signal Name                | Method                                 |
  46  * |-----------------------------|----------------------------------------|
  47  * | widgetAdded                 | @ref WidgetAddedSignal()               |
  48  * | widgetDeleted               | @ref WidgetDeletedSignal()             |
  49  * | widgetCreationAborted       | @ref WidgetCreationAbortedSignal()     |
  50  * | widgetContentUpdated        | @ref WidgetContentUpdatedSignal()      |
  51  * | widgetUpdatePeriodChanged   | @ref WidgetUpdatePeriodChangedSignal() |
  52  * | widgetFaulted               | @ref WidgetFaultedSignal()             |
  53  *
  54  * @since_tizen 3.0
  55  */
  56 class DALI_IMPORT_API WidgetView : public Toolkit::Control
  57 {
  58 public:
  59
  60   /**
  61    * @brief The start and end property ranges for this control.
  62    * @SINCE_1_0.0
  63    */
  64   enum PropertyRange
  65   {
  66     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,  ///< @SINCE_1_0.0
  67     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000,              ///< Reserve property indices @SINCE_1_0.0
  68   };
  69
  70   /**
  71    * @brief An enumeration of properties belonging to the WidgetView class.
  72    * @privlevel public
  73    * @privilege %http://tizen.org/privilege/widget.viewer
  74    * @SINCE_1_0.0
  75    */
  76   struct Property
  77   {
  78     enum
  79     {
  80       // Event side properties
  81
  82       /**
  83        * @brief name "widgetId", Get the id of the widget, type string, read-only
  84        * @SINCE_1_0.0
  85        */
  86       WIDGET_ID = PROPERTY_START_INDEX,
  87
  88       /**
  89        * @brief name "instanceId", type string, read-only
  90        * @SINCE_1_0.0
  91        */
  92       INSTANCE_ID,
  93
  94       /**
  95        * @brief name "contentInfo", type string, read-only
  96        * @SINCE_1_0.0
  97        */
  98       CONTENT_INFO,
  99
 100       /**
 101        * @brief name "title", type string, read-only
 102        * @SINCE_1_0.0
 103        */
 104       TITLE,
 105
 106       /**
 107        * @brief name "updatePeriod", type float, read-only
 108        * @SINCE_1_0.0
 109        */
 110       UPDATE_PERIOD,
 111
 112       /**
 113        * @brief name "preview", type boolean if it is a show/hide flag, map otherwise
 114        * @SINCE_1_0.0
 115        */
 116       PREVIEW,
 117
 118       /**
 119        * @brief name "loadingText", type boolean if it is a show/hide flag, map otherwise
 120        * @SINCE_1_0.0
 121        */
 122       LOADING_TEXT,
 123
 124       /**
 125        * @brief name "widgetStateFaulted", type boolean
 126        * @SINCE_1_0.0
 127        */
 128       WIDGET_STATE_FAULTED,
 129
 130       /**
 131        * @brief name "permanentDelete", type boolean
 132        * @SINCE_1_0.0
 133        */
 134       PERMANENT_DELETE,
 135
 136     };
 137   };
 138
 139
 140   /**
 141    * @brief Create widget view.
 142    *
 143    * @since_tizen 3.0
 144    * @privlevel public
 145    * @privilege %http://tizen.org/privilege/widget.viewer
 146    * @param[in] widgetId The widget id.
 147    * @param[in] contentInfo Contents that will be given to the widget instance.
 148    * @param[in] width The widget width.
 149    * @param[in] height The widget height.
 150    * @param[in] updatePeriod The period of updating contents of the widget.
 151    * @return A handle to WidgetView.
 152    */
 153   static WidgetView New( const std::string& widgetId, const std::string& contentInfo, int width, int height, float updatePeriod );
 154
 155   /**
 156    * @brief Downcast a handle to WidgetView handle.
 157    *
 158    * If the BaseHandle points is a WidgetView the downcast returns a valid handle.
 159    * If not the returned handle is left empty.
 160    *
 161    * @since_tizen 3.0
 162    * @param[in] handle Handle to an object
 163    * @return handle to a WidgetView or an empty handle
 164    */
 165   static WidgetView DownCast( BaseHandle handle );
 166
 167   /**
 168    * @brief Creates an empty handle.
 169    * @since_tizen 3.0
 170    */
 171   WidgetView();
 172
 173   /**
 174    * @brief Copy constructor.
 175    *
 176    * @since_tizen 3.0
 177    * @param[in] handle The handle to copy from.
 178    */
 179   WidgetView( const WidgetView& handle );
 180
 181   /**
 182    * @brief Assignment operator.
 183    *
 184    * @since_tizen 3.0
 185    * @param[in] handle The handle to copy from.
 186    * @return A reference to this.
 187    */
 188   WidgetView& operator=( const WidgetView& handle );
 189
 190   /**
 191    * @brief Destructor
 192    *
 193    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 194    * @since_tizen 3.0
 195    */
 196   ~WidgetView();
 197
 198   /**
 199    * @brief Pauses a given widget.
 200    *
 201    * @since_tizen 3.0
 202    * @privlevel public
 203    * @privilege %http://tizen.org/privilege/widget.viewer
 204    * @return true on success, false otherwise.
 205    */
 206   bool PauseWidget();
 207
 208   /**
 209    * @brief Resume a given widget.
 210    *
 211    * @since_tizen 3.0
 212    * @privlevel public
 213    * @privilege %http://tizen.org/privilege/widget.viewer
 214    * @return true on success, false otherwise.
 215    */
 216   bool ResumeWidget();
 217
 218   /**
 219    * @brief Cancels touch event procedure.
 220    * If you call this function after feed the touch down event, the widget will get ON_HOLD events.
 221    * If a widget gets ON_HOLD event, it will not do anything even if you feed touch up event.
 222    *
 223    * @since_tizen 3.0
 224    * @privlevel public
 225    * @privilege %http://tizen.org/privilege/widget.viewer
 226    * @return true on success, false otherwise.
 227    */
 228   bool CancelTouchEvent();
 229
 230   /**
 231    * @brief Activate a widget in faulted state.
 232    * A widget in faulted state MUST be activated before adding the widget.
 233    *
 234    * @since_tizen 3.0
 235    * @privlevel public
 236    * @privilege %http://tizen.org/privilege/widget.viewer
 237    */
 238   void ActivateFaultedWidget();
 239
 240 public: //Signals
 241
 242   typedef Signal< void ( WidgetView ) > WidgetViewSignalType;   ///< WidgetView signal type @since_tizen 3.0
 243
 244   /**
 245    * @brief This signal is emitted when the widget is added.
 246    *
 247    * @since_tizen 3.0
 248    * @privlevel public
 249    * @privilege %http://tizen.org/privilege/widget.viewer
 250    * @return The signal to connect to.
 251    */
 252   WidgetViewSignalType& WidgetAddedSignal();
 253
 254   /**
 255    * @brief This signal is emitted when the widget is deleted.
 256    *
 257    * @since_tizen 3.0
 258    * @privlevel public
 259    * @privilege %http://tizen.org/privilege/widget.viewer
 260    * @return The signal to connect to.
 261    */
 262   WidgetViewSignalType& WidgetDeletedSignal();
 263
 264   /**
 265    * @brief This signal is emitted when the widget creation is aborted.
 266    *
 267    * @since_tizen 3.0
 268    * @privlevel public
 269    * @privilege %http://tizen.org/privilege/widget.viewer
 270    * @return The signal to connect to.
 271    */
 272   WidgetViewSignalType& WidgetCreationAbortedSignal();
 273
 274   /**
 275    * @brief This signal is emitted when the widget content is updated.
 276    *
 277    * @since_tizen 3.0
 278    * @privlevel public
 279    * @privilege %http://tizen.org/privilege/widget.viewer
 280    * @return The signal to connect to.
 281    */
 282   WidgetViewSignalType& WidgetContentUpdatedSignal();
 283
 284   /**
 285    * @brief This signal is emitted when the widget update period is changed.
 286    *
 287    * @since_tizen 3.0
 288    * @privlevel public
 289    * @privilege %http://tizen.org/privilege/widget.viewer
 290    * @return The signal to connect to.
 291    */
 292   WidgetViewSignalType& WidgetUpdatePeriodChangedSignal();
 293
 294   /**
 295    * @brief This signal is emitted when the widget process is not running.
 296    *
 297    * @since_tizen 3.0
 298    * @privlevel public
 299    * @privilege %http://tizen.org/privilege/widget.viewer
 300    * @return The signal to connect to.
 301    */
 302   WidgetViewSignalType& WidgetFaultedSignal();
 303
 304 public: // Not intended for application developers
 305
 306   /**
 307    * @internal
 308    * @brief Creates a handle using the WidgetView::Internal implementation.
 309    *
 310    * @since_tizen 3.0
 311    * @param[in] implementation The WidgetView implementation.
 312    */
 313   DALI_INTERNAL WidgetView( Internal::WidgetView& implementation );
 314
 315   /**
 316    * @internal
 317    * @brief Allows the creation of this control from an Internal::CustomActor pointer.
 318    *
 319    * @since_tizen 3.0
 320    * @param[in] internal A pointer to the internal CustomActor.
 321    */
 322   DALI_INTERNAL WidgetView( Dali::Internal::CustomActor* internal );
 323 };
 324
 325 /**
 326  * @}
 327  */
 328 } // namespace WidgetView
 329
 330 } // namespace Dali
 331
 332 #endif // __DALI_WIDGET_VIEW_WIDGET_VIEW_H__