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     /**
  79      * @brief An enumeration of properties belonging to the WidgetView class.
  80      * @privlevel public
  81      * @privilege %http://tizen.org/privilege/widget.viewer
  82      * @SINCE_1_0.0
  83      */
  84     enum
  85     {
  86       // Event side properties
  87
  88       /**
  89        * @brief name "widgetId", Get the id of the widget, type string, read-only
  90        * @SINCE_1_0.0
  91        */
  92       WIDGET_ID = PROPERTY_START_INDEX,
  93
  94       /**
  95        * @brief name "instanceId", type string, read-only
  96        * @SINCE_1_0.0
  97        */
  98       INSTANCE_ID,
  99
 100       /**
 101        * @brief name "contentInfo", type string, read-only
 102        * @SINCE_1_0.0
 103        */
 104       CONTENT_INFO,
 105
 106       /**
 107        * @brief name "title", type string, read-only
 108        * @SINCE_1_0.0
 109        */
 110       TITLE,
 111
 112       /**
 113        * @brief name "updatePeriod", type float, read-only
 114        * @SINCE_1_0.0
 115        */
 116       UPDATE_PERIOD,
 117
 118       /**
 119        * @brief name "preview", type boolean if it is a show/hide flag, map otherwise
 120        * @SINCE_1_0.0
 121        */
 122       PREVIEW,
 123
 124       /**
 125        * @brief name "loadingText", type boolean if it is a show/hide flag, map otherwise
 126        * @SINCE_1_0.0
 127        */
 128       LOADING_TEXT,
 129
 130       /**
 131        * @brief name "widgetStateFaulted", type boolean
 132        * @SINCE_1_0.0
 133        */
 134       WIDGET_STATE_FAULTED,
 135
 136       /**
 137        * @brief name "permanentDelete", type boolean
 138        * @SINCE_1_0.0
 139        */
 140       PERMANENT_DELETE,
 141
 142     };
 143   };
 144
 145
 146   /**
 147    * @brief Create widget view.
 148    *
 149    * @since_tizen 3.0
 150    * @privlevel public
 151    * @privilege %http://tizen.org/privilege/widget.viewer
 152    * @param[in] widgetId The widget id.
 153    * @param[in] contentInfo Contents that will be given to the widget instance.
 154    * @param[in] width The widget width.
 155    * @param[in] height The widget height.
 156    * @param[in] updatePeriod The period of updating contents of the widget.
 157    * @return A handle to WidgetView.
 158    */
 159   static WidgetView New( const std::string& widgetId, const std::string& contentInfo, int width, int height, float updatePeriod );
 160
 161   /**
 162    * @brief Downcast a handle to WidgetView handle.
 163    *
 164    * If the BaseHandle points is a WidgetView the downcast returns a valid handle.
 165    * If not the returned handle is left empty.
 166    *
 167    * @since_tizen 3.0
 168    * @param[in] handle Handle to an object
 169    * @return handle to a WidgetView or an empty handle
 170    */
 171   static WidgetView DownCast( BaseHandle handle );
 172
 173   /**
 174    * @brief Creates an empty handle.
 175    * @since_tizen 3.0
 176    */
 177   WidgetView();
 178
 179   /**
 180    * @brief Copy constructor.
 181    *
 182    * @since_tizen 3.0
 183    * @param[in] handle The handle to copy from.
 184    */
 185   WidgetView( const WidgetView& handle );
 186
 187   /**
 188    * @brief Assignment operator.
 189    *
 190    * @since_tizen 3.0
 191    * @param[in] handle The handle to copy from.
 192    * @return A reference to this.
 193    */
 194   WidgetView& operator=( const WidgetView& handle );
 195
 196   /**
 197    * @brief Destructor
 198    *
 199    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 200    * @since_tizen 3.0
 201    */
 202   ~WidgetView();
 203
 204   /**
 205    * @brief Pauses a given widget.
 206    *
 207    * @since_tizen 3.0
 208    * @privlevel public
 209    * @privilege %http://tizen.org/privilege/widget.viewer
 210    * @return true on success, false otherwise.
 211    */
 212   bool PauseWidget();
 213
 214   /**
 215    * @brief Resume a given widget.
 216    *
 217    * @since_tizen 3.0
 218    * @privlevel public
 219    * @privilege %http://tizen.org/privilege/widget.viewer
 220    * @return true on success, false otherwise.
 221    */
 222   bool ResumeWidget();
 223
 224   /**
 225    * @brief Cancels touch event procedure.
 226    * If you call this function after feed the touch down event, the widget will get ON_HOLD events.
 227    * If a widget gets ON_HOLD event, it will not do anything even if you feed touch up event.
 228    *
 229    * @since_tizen 3.0
 230    * @privlevel public
 231    * @privilege %http://tizen.org/privilege/widget.viewer
 232    * @return true on success, false otherwise.
 233    */
 234   bool CancelTouchEvent();
 235
 236   /**
 237    * @brief Activate a widget in faulted state.
 238    * A widget in faulted state MUST be activated before adding the widget.
 239    *
 240    * @since_tizen 3.0
 241    * @privlevel public
 242    * @privilege %http://tizen.org/privilege/widget.viewer
 243    */
 244   void ActivateFaultedWidget();
 245
 246 public: //Signals
 247
 248   typedef Signal< void ( WidgetView ) > WidgetViewSignalType;   ///< WidgetView signal type @since_tizen 3.0
 249
 250   /**
 251    * @brief This signal is emitted when the widget is added.
 252    *
 253    * @since_tizen 3.0
 254    * @privlevel public
 255    * @privilege %http://tizen.org/privilege/widget.viewer
 256    * @return The signal to connect to.
 257    */
 258   WidgetViewSignalType& WidgetAddedSignal();
 259
 260   /**
 261    * @brief This signal is emitted when the widget is deleted.
 262    *
 263    * @since_tizen 3.0
 264    * @privlevel public
 265    * @privilege %http://tizen.org/privilege/widget.viewer
 266    * @return The signal to connect to.
 267    */
 268   WidgetViewSignalType& WidgetDeletedSignal();
 269
 270   /**
 271    * @brief This signal is emitted when the widget creation is aborted.
 272    *
 273    * @since_tizen 3.0
 274    * @privlevel public
 275    * @privilege %http://tizen.org/privilege/widget.viewer
 276    * @return The signal to connect to.
 277    */
 278   WidgetViewSignalType& WidgetCreationAbortedSignal();
 279
 280   /**
 281    * @brief This signal is emitted when the widget content is updated.
 282    *
 283    * @since_tizen 3.0
 284    * @privlevel public
 285    * @privilege %http://tizen.org/privilege/widget.viewer
 286    * @return The signal to connect to.
 287    */
 288   WidgetViewSignalType& WidgetContentUpdatedSignal();
 289
 290   /**
 291    * @brief This signal is emitted when the widget update period is changed.
 292    *
 293    * @since_tizen 3.0
 294    * @privlevel public
 295    * @privilege %http://tizen.org/privilege/widget.viewer
 296    * @return The signal to connect to.
 297    */
 298   WidgetViewSignalType& WidgetUpdatePeriodChangedSignal();
 299
 300   /**
 301    * @brief This signal is emitted when the widget process is not running.
 302    *
 303    * @since_tizen 3.0
 304    * @privlevel public
 305    * @privilege %http://tizen.org/privilege/widget.viewer
 306    * @return The signal to connect to.
 307    */
 308   WidgetViewSignalType& WidgetFaultedSignal();
 309
 310 public: // Not intended for application developers
 311
 312   /**
 313    * @internal
 314    * @brief Creates a handle using the WidgetView::Internal implementation.
 315    *
 316    * @since_tizen 3.0
 317    * @param[in] implementation The WidgetView implementation.
 318    */
 319   DALI_INTERNAL WidgetView( Internal::WidgetView& implementation );
 320
 321   /**
 322    * @internal
 323    * @brief Allows the creation of this control from an Internal::CustomActor pointer.
 324    *
 325    * @since_tizen 3.0
 326    * @param[in] internal A pointer to the internal CustomActor.
 327    */
 328   DALI_INTERNAL WidgetView( Dali::Internal::CustomActor* internal );
 329 };
 330
 331 /**
 332  * @}
 333  */
 334 } // namespace WidgetView
 335
 336 } // namespace Dali
 337
 338 #endif // __DALI_WIDGET_VIEW_WIDGET_VIEW_H__