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 Sets whether to enable or disable the preview of the widget
 162    *
 163    * @since_tizen 3.0
 164    * @privlevel public
 165    * @privilege %http://tizen.org/privilege/widget.viewer
 166    * @param[in] enable Whether to enable the preview of the widget or not
 167    */
 168   void SetPreviewEnabled( bool enabled );
 169
 170   /**
 171    * @brief Checks if the preview of the widget has been enabled or not.
 172    *
 173    * @since_tizen 3.0
 174    * @privlevel public
 175    * @privilege %http://tizen.org/privilege/widget.viewer
 176    * @return Whether the preview of the widget is enabled
 177    */
 178   bool GetPreviewEnabled() const;
 179
 180   /**
 181    * @brief Sets whether to enable or disable the state message of the widget
 182    *
 183    * @since_tizen 3.0
 184    * @privlevel public
 185    * @privilege %http://tizen.org/privilege/widget.viewer
 186    * @param[in] enable Whether to enable the state message of the widget or not
 187    */
 188   void SetStateTextEnabled( bool enabled );
 189
 190   /**
 191    * @brief Checks if the state message of the widget has been enabled or not.
 192    *
 193    * @since_tizen 3.0
 194    * @privlevel public
 195    * @privilege %http://tizen.org/privilege/widget.viewer
 196    * @return Whether the state message of the widget is enabled
 197    */
 198   bool GetStateTextEnabled() const;
 199
 200   /**
 201    * @brief Activate a widget in faulted state.
 202    * A widget in faulted state MUST be activated before adding the widget.
 203    *
 204    * @since_tizen 3.0
 205    * @privlevel public
 206    * @privilege %http://tizen.org/privilege/widget.viewer
 207    */
 208   void ActivateFaultedWidget();
 209
 210   /**
 211    * @brief Check whether the widget is faulted.
 212    *
 213    * @since_tizen 3.0
 214    * @privlevel public
 215    * @privilege %http://tizen.org/privilege/widget.viewer
 216    * @return true for faulted state, otherwise false.
 217    */
 218   bool IsWidgetFaulted();
 219
 220   /**
 221    * @brief Set the deletion mode.
 222    *
 223    * @since_tizen 3.0
 224    * @privlevel public
 225    * @privilege %http://tizen.org/privilege/widget.viewer
 226    * @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.
 227    */
 228   void SetPermanentDelete( bool permanentDelete );
 229
 230 public: //Signals
 231
 232   typedef Signal< void ( WidgetView ) > WidgetViewSignalType;   ///< WidgetView signal type @since_tizen 3.0
 233
 234   /**
 235    * @brief This signal is emitted when the widget is added.
 236    *
 237    * @since_tizen 3.0
 238    * @return The signal to connect to.
 239    */
 240   WidgetViewSignalType& WidgetAddedSignal();
 241
 242   /**
 243    * @brief This signal is emitted when the widget is deleted.
 244    *
 245    * @since_tizen 3.0
 246    * @return The signal to connect to.
 247    */
 248   WidgetViewSignalType& WidgetDeletedSignal();
 249
 250 public: // Not intended for application developers
 251
 252   /**
 253    * @brief Creates a handle using the WidgetView::Internal implementation.
 254    *
 255    * @since_tizen 3.0
 256    * @param[in] implementation The WidgetView implementation.
 257    */
 258   DALI_INTERNAL WidgetView( Internal::WidgetView& implementation );
 259
 260   /**
 261    * @brief Allows the creation of this control from an Internal::CustomActor pointer.
 262    *
 263    * @since_tizen 3.0
 264    * @param[in] internal A pointer to the internal CustomActor.
 265    */
 266   DALI_INTERNAL WidgetView( Dali::Internal::CustomActor* internal );
 267 };
 268
 269 /**
 270  * @}
 271  */
 272 } // namespace WidgetView
 273
 274 } // namespace Dali
 275
 276 #endif // __DALI_WIDGET_VIEW_WIDGET_VIEW_H__