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  * Copyright (c) 2016 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-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  * @since_tizen 3.0
  45  */
  46 class DALI_IMPORT_API WidgetView : public Toolkit::Control
  47 {
  48 public:
  49
  50   /**
  51    * @brief Create widget view.
  52    *
  53    * @since_tizen 3.0
  54    * @privlevel public
  55    * @privilege %http://tizen.org/privilege/widget.viewer
  56    * @param[in] widgetId The widget id.
  57    * @param[in] contentInfo Contents that will be given to the widget instance.
  58    * @param[in] width The widget width.
  59    * @param[in] height The widget height.
  60    * @param[in] updatePeriod The period of updating contents of the widget.
  61    * @return A handle to WidgetView.
  62    */
  63   static WidgetView New( const std::string& widgetId, const std::string& contentInfo, int width, int height, double updatePeriod );
  64
  65   /**
  66    * @brief Downcast a handle to WidgetView handle.
  67    *
  68    * If the BaseHandle points is a WidgetView the downcast returns a valid handle.
  69    * If not the returned handle is left empty.
  70    *
  71    * @since_tizen 3.0
  72    * @param[in] handle Handle to an object
  73    * @return handle to a WidgetView or an empty handle
  74    */
  75   static WidgetView DownCast( BaseHandle handle );
  76
  77   /**
  78    * @brief Creates an empty handle.
  79    * @since_tizen 3.0
  80    */
  81   WidgetView();
  82
  83   /**
  84    * @brief Copy constructor.
  85    *
  86    * @since_tizen 3.0
  87    * @param[in] handle The handle to copy from.
  88    */
  89   WidgetView( const WidgetView& handle );
  90
  91   /**
  92    * @brief Assignment operator.
  93    *
  94    * @since_tizen 3.0
  95    * @param[in] handle The handle to copy from.
  96    * @return A reference to this.
  97    */
  98   WidgetView& operator=( const WidgetView& handle );
  99
 100   /**
 101    * @brief Destructor
 102    *
 103    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 104    * @since_tizen 3.0
 105    */
 106   ~WidgetView();
 107
 108   /**
 109    * @brief Pauses a given widget.
 110    *
 111    * @since_tizen 3.0
 112    * @privlevel public
 113    * @privilege %http://tizen.org/privilege/widget.viewer
 114    * @return true on success, false otherwise.
 115    */
 116   bool PauseWidget();
 117
 118   /**
 119    * @brief Resume a given widget.
 120    *
 121    * @since_tizen 3.0
 122    * @privlevel public
 123    * @privilege %http://tizen.org/privilege/widget.viewer
 124    * @return true on success, false otherwise.
 125    */
 126   bool ResumeWidget();
 127
 128   /**
 129    * @brief Get the id of the widget.
 130    *
 131    * @since_tizen 3.0
 132    * @privlevel public
 133    * @privilege %http://tizen.org/privilege/widget.viewer
 134    * @return The widget id on success, otherwise an empty string.
 135    */
 136   const std::string& GetWidgetId() const;
 137
 138   /**
 139    * @brief Get the instance id of the widget.
 140    *
 141    * @since_tizen 3.0
 142    * @privlevel public
 143    * @privilege %http://tizen.org/privilege/widget.viewer
 144    * @return The instance id on success, otherwise an empty string.
 145    */
 146   const std::string& GetInstanceId() const;
 147
 148   /**
 149    * @brief Get the content string of the widget.
 150    * This string can be used for creating contents of widget again after reboot a device or recovered from crash(abnormal status).
 151    *
 152    * @since_tizen 3.0
 153    * @privlevel public
 154    * @privilege %http://tizen.org/privilege/widget.viewer
 155    * @return The content string to be recognize content of the widget or an empty string if there is no specific content string.
 156    */
 157   const std::string& GetContentInfo();
 158
 159   /**
 160    * @brief Get the summarized string of the widget content for accessibility.
 161    * If the accessibility feature is turned on, a viewer can use this text to describe the widget.
 162    *
 163    * @since_tizen 3.0
 164    * @privlevel public
 165    * @privilege %http://tizen.org/privilege/widget.viewer
 166    * @return The title string to be used for summarizing the widget or an empty string if there is no summarized text for content of given widget.
 167    */
 168   const std::string& GetTitle();
 169
 170   /**
 171    * @brief Get the update period of the widget content.
 172    *
 173    * @since_tizen 3.0
 174    * @privlevel public
 175    * @privilege %http://tizen.org/privilege/widget.viewer
 176    * @return The update period of the widget content.
 177    */
 178   double GetUpdatePeriod() const;
 179
 180   /**
 181    * @brief Shows the widget.
 182    *
 183    * @since_tizen 3.0
 184    * @privlevel public
 185    * @privilege %http://tizen.org/privilege/widget.viewer
 186    * @note Use this function instead of Dali::Actor::SetVisible() to restart updating widget content.
 187    */
 188   void Show();
 189
 190   /**
 191    * @brief Hides the widget.
 192    *
 193    * @since_tizen 3.0
 194    * @privlevel public
 195    * @privilege %http://tizen.org/privilege/widget.viewer
 196    * @note Use this function instead of Dali::Actor::SetVisible() to stop updating widget content.
 197    */
 198   void Hide();
 199
 200   /**
 201    * @brief Cancels touch event procedure.
 202    * If you call this function after feed the touch down event, the widget will get ON_HOLD events.
 203    * If a widget gets ON_HOLD event, it will not do anything even if you feed touch up event.
 204    *
 205    * @since_tizen 3.0
 206    * @privlevel public
 207    * @privilege %http://tizen.org/privilege/widget.viewer
 208    * @return true on success, false otherwise.
 209    */
 210   bool CancelTouchEvent();
 211
 212   /**
 213    * @brief Sets whether to enable or disable the preview of the widget
 214    *
 215    * @since_tizen 3.0
 216    * @privlevel public
 217    * @privilege %http://tizen.org/privilege/widget.viewer
 218    * @param[in] enable Whether to enable the preview of the widget or not
 219    */
 220   void SetPreviewEnabled( bool enabled );
 221
 222   /**
 223    * @brief Checks if the preview of the widget has been enabled or not.
 224    *
 225    * @since_tizen 3.0
 226    * @privlevel public
 227    * @privilege %http://tizen.org/privilege/widget.viewer
 228    * @return Whether the preview of the widget is enabled
 229    */
 230   bool GetPreviewEnabled() const;
 231
 232   /**
 233    * @brief Sets whether to enable or disable the state message of the widget
 234    *
 235    * @since_tizen 3.0
 236    * @privlevel public
 237    * @privilege %http://tizen.org/privilege/widget.viewer
 238    * @param[in] enable Whether to enable the state message of the widget or not
 239    */
 240   void SetStateTextEnabled( bool enabled );
 241
 242   /**
 243    * @brief Checks if the state message of the widget has been enabled or not.
 244    *
 245    * @since_tizen 3.0
 246    * @privlevel public
 247    * @privilege %http://tizen.org/privilege/widget.viewer
 248    * @return Whether the state message of the widget is enabled
 249    */
 250   bool GetStateTextEnabled() const;
 251
 252   /**
 253    * @brief Activate a widget in faulted state.
 254    * A widget in faulted state MUST be activated before adding the widget.
 255    *
 256    * @since_tizen 3.0
 257    * @privlevel public
 258    * @privilege %http://tizen.org/privilege/widget.viewer
 259    */
 260   void ActivateFaultedWidget();
 261
 262   /**
 263    * @brief Check whether the widget is faulted.
 264    *
 265    * @since_tizen 3.0
 266    * @privlevel public
 267    * @privilege %http://tizen.org/privilege/widget.viewer
 268    * @return true for faulted state, otherwise false.
 269    */
 270   bool IsWidgetFaulted();
 271
 272   /**
 273    * @brief Set the deletion mode.
 274    *
 275    * @since_tizen 3.0
 276    * @privlevel public
 277    * @privilege %http://tizen.org/privilege/widget.viewer
 278    * @param[in] permanentDelete Pass true if you want to delete this widget instance permanently, or pass false if you want to keep it and it will be re-created soon.
 279    */
 280   void SetPermanentDelete( bool permanentDelete );
 281
 282 public: //Signals
 283
 284   typedef Signal< void ( WidgetView ) > WidgetViewSignalType;   ///< WidgetView signal type @since_tizen 3.0
 285
 286   /**
 287    * @brief This signal is emitted when the widget is added.
 288    *
 289    * @since_tizen 3.0
 290    * @privlevel public
 291    * @privilege %http://tizen.org/privilege/widget.viewer
 292    * @return The signal to connect to.
 293    */
 294   WidgetViewSignalType& WidgetAddedSignal();
 295
 296   /**
 297    * @brief This signal is emitted when the widget is deleted.
 298    *
 299    * @since_tizen 3.0
 300    * @privlevel public
 301    * @privilege %http://tizen.org/privilege/widget.viewer
 302    * @return The signal to connect to.
 303    */
 304   WidgetViewSignalType& WidgetDeletedSignal();
 305
 306   /**
 307    * @brief This signal is emitted when the widget creation is aborted.
 308    *
 309    * @since_tizen 3.0
 310    * @privlevel public
 311    * @privilege %http://tizen.org/privilege/widget.viewer
 312    * @return The signal to connect to.
 313    */
 314   WidgetViewSignalType& WidgetCreationAbortedSignal();
 315
 316   /**
 317    * @brief This signal is emitted when the widget is resized.
 318    *
 319    * @since_tizen 3.0
 320    * @privlevel public
 321    * @privilege %http://tizen.org/privilege/widget.viewer
 322    * @return The signal to connect to.
 323    */
 324   WidgetViewSignalType& WidgetResizedSignal();
 325
 326   /**
 327    * @brief This signal is emitted when the widget content is updated.
 328    *
 329    * @since_tizen 3.0
 330    * @privlevel public
 331    * @privilege %http://tizen.org/privilege/widget.viewer
 332    * @return The signal to connect to.
 333    */
 334   WidgetViewSignalType& WidgetContentUpdatedSignal();
 335
 336   /**
 337    * @brief This signal is emitted when the widget extra info is updated.
 338    *
 339    * @since_tizen 3.0
 340    * @privlevel public
 341    * @privilege %http://tizen.org/privilege/widget.viewer
 342    * @return The signal to connect to.
 343    */
 344   WidgetViewSignalType& WidgetExtraInfoUpdatedSignal();
 345
 346   /**
 347    * @brief This signal is emitted when the widget update period is changed.
 348    *
 349    * @since_tizen 3.0
 350    * @privlevel public
 351    * @privilege %http://tizen.org/privilege/widget.viewer
 352    * @return The signal to connect to.
 353    */
 354   WidgetViewSignalType& WidgetUpdatePeriodChangedSignal();
 355
 356   /**
 357    * @brief This signal is emitted when the widget process is not running.
 358    *
 359    * @since_tizen 3.0
 360    * @privlevel public
 361    * @privilege %http://tizen.org/privilege/widget.viewer
 362    * @return The signal to connect to.
 363    */
 364   WidgetViewSignalType& WidgetFaultedSignal();
 365
 366 public: // Not intended for application developers
 367
 368   /**
 369    * @brief Creates a handle using the WidgetView::Internal implementation.
 370    *
 371    * @since_tizen 3.0
 372    * @param[in] implementation The WidgetView implementation.
 373    */
 374   DALI_INTERNAL WidgetView( Internal::WidgetView& implementation );
 375
 376   /**
 377    * @brief Allows the creation of this control from an Internal::CustomActor pointer.
 378    *
 379    * @since_tizen 3.0
 380    * @param[in] internal A pointer to the internal CustomActor.
 381    */
 382   DALI_INTERNAL WidgetView( Dali::Internal::CustomActor* internal );
 383 };
 384
 385 /**
 386  * @}
 387  */
 388 } // namespace WidgetView
 389
 390 } // namespace Dali
 391
 392 #endif // __DALI_WIDGET_VIEW_WIDGET_VIEW_H__