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] period 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 period );
  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 Get the id of the widget.
 110    *
 111    * @since_tizen 3.0
 112    * @privlevel public
 113    * @privilege %http://tizen.org/privilege/widget.viewer
 114    * @return The widget id on success, otherwise an empty string.
 115    */
 116   const std::string& GetWidgetId() const;
 117
 118   /**
 119    * @brief Get the instance id of the widget.
 120    *
 121    * @since_tizen 3.0
 122    * @privlevel public
 123    * @privilege %http://tizen.org/privilege/widget.viewer
 124    * @return The instance id on success, otherwise an empty string.
 125    */
 126   const std::string& GetInstanceId() const;
 127
 128   /**
 129    * @brief Get the content string of the widget.
 130    * This string can be used for creating contents of widget again after reboot a device or recovered from crash(abnormal status).
 131    *
 132    * @since_tizen 3.0
 133    * @privlevel public
 134    * @privilege %http://tizen.org/privilege/widget.viewer
 135    * @return The content string to be recognize content of the widget or an empty string if there is no specific content string.
 136    */
 137   const std::string& GetContentInfo();
 138
 139   /**
 140    * @brief Get the summarized string of the widget content for accessibility.
 141    * If the accessibility feature is turned on, a viewer can use this text to describe the widget.
 142    *
 143    * @since_tizen 3.0
 144    * @privlevel public
 145    * @privilege %http://tizen.org/privilege/widget.viewer
 146    * @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.
 147    */
 148   const std::string& GetTitle();
 149
 150   /**
 151    * @brief Get the update period of the widget.
 152    *
 153    * @since_tizen 3.0
 154    * @privlevel public
 155    * @privilege %http://tizen.org/privilege/widget.viewer
 156    * @return The update period of the widget.
 157    */
 158   double GetPeriod() const;
 159
 160   /**
 161    * @brief Shows the widget.
 162    *
 163    * @since_tizen 3.0
 164    * @privlevel public
 165    * @privilege %http://tizen.org/privilege/widget.viewer
 166    * @note Use this function instead of Dali::Actor::SetVisible() to restart updating widget content.
 167    */
 168   void Show();
 169
 170   /**
 171    * @brief Hides the widget.
 172    *
 173    * @since_tizen 3.0
 174    * @privlevel public
 175    * @privilege %http://tizen.org/privilege/widget.viewer
 176    * @note Use this function instead of Dali::Actor::SetVisible() to stop updating widget content.
 177    */
 178   void Hide();
 179
 180   /**
 181    * @brief Cancels touch event procedure.
 182    * If you call this function after feed the touch down event, the widget will get ON_HOLD events.
 183    * If a widget gets ON_HOLD event, it will not do anything even if you feed touch up event.
 184    *
 185    * @since_tizen 3.0
 186    * @privlevel public
 187    * @privilege %http://tizen.org/privilege/widget.viewer
 188    * @return true on success, false otherwise.
 189    */
 190   bool CancelTouchEvent();
 191
 192   /**
 193    * @brief Sets whether to enable or disable the preview of the widget
 194    *
 195    * @since_tizen 3.0
 196    * @privlevel public
 197    * @privilege %http://tizen.org/privilege/widget.viewer
 198    * @param[in] enable Whether to enable the preview of the widget or not
 199    */
 200   void SetPreviewEnabled( bool enabled );
 201
 202   /**
 203    * @brief Checks if the preview of the widget has been enabled or not.
 204    *
 205    * @since_tizen 3.0
 206    * @privlevel public
 207    * @privilege %http://tizen.org/privilege/widget.viewer
 208    * @return Whether the preview of the widget is enabled
 209    */
 210   bool GetPreviewEnabled() const;
 211
 212   /**
 213    * @brief Sets whether to enable or disable the state message 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 state message of the widget or not
 219    */
 220   void SetStateTextEnabled( bool enabled );
 221
 222   /**
 223    * @brief Checks if the state message 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 state message of the widget is enabled
 229    */
 230   bool GetStateTextEnabled() const;
 231
 232   /**
 233    * @brief Activate a widget in faulted state.
 234    * A widget in faulted state MUST be activated before adding the widget.
 235    *
 236    * @since_tizen 3.0
 237    * @privlevel public
 238    * @privilege %http://tizen.org/privilege/widget.viewer
 239    */
 240   void ActivateFaultedWidget();
 241
 242   /**
 243    * @brief Check whether the widget is faulted.
 244    *
 245    * @since_tizen 3.0
 246    * @privlevel public
 247    * @privilege %http://tizen.org/privilege/widget.viewer
 248    * @return true for faulted state, otherwise false.
 249    */
 250   bool IsWidgetFaulted();
 251
 252   /**
 253    * @brief Set the deletion mode.
 254    *
 255    * @since_tizen 3.0
 256    * @privlevel public
 257    * @privilege %http://tizen.org/privilege/widget.viewer
 258    * @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.
 259    */
 260   void SetPermanentDelete( bool permanentDelete );
 261
 262 public: //Signals
 263
 264   typedef Signal< void ( WidgetView ) > WidgetViewSignalType;   ///< WidgetView signal type @since_tizen 3.0
 265
 266   /**
 267    * @brief This signal is emitted when the widget is added.
 268    *
 269    * @since_tizen 3.0
 270    * @return The signal to connect to.
 271    */
 272   WidgetViewSignalType& WidgetAddedSignal();
 273
 274   /**
 275    * @brief This signal is emitted when the widget is deleted.
 276    *
 277    * @since_tizen 3.0
 278    * @return The signal to connect to.
 279    */
 280   WidgetViewSignalType& WidgetDeletedSignal();
 281
 282 public: // Not intended for application developers
 283
 284   /**
 285    * @brief Creates a handle using the WidgetView::Internal implementation.
 286    *
 287    * @since_tizen 3.0
 288    * @param[in] implementation The WidgetView implementation.
 289    */
 290   DALI_INTERNAL WidgetView( Internal::WidgetView& implementation );
 291
 292   /**
 293    * @brief Allows the creation of this control from an Internal::CustomActor pointer.
 294    *
 295    * @since_tizen 3.0
 296    * @param[in] internal A pointer to the internal CustomActor.
 297    */
 298   DALI_INTERNAL WidgetView( Dali::Internal::CustomActor* internal );
 299 };
 300
 301 /**
 302  * @}
 303  */
 304 } // namespace WidgetView
 305
 306 } // namespace Dali
 307
 308 #endif // __DALI_WIDGET_VIEW_WIDGET_VIEW_H__