dali-toolkit/public-api/controls/image-view/image-view.h

   1 #ifndef DALI_TOOLKIT_IMAGE_VIEW_H
   2 #define DALI_TOOLKIT_IMAGE_VIEW_H
   3
   4 /*
   5  * Copyright (c) 2022 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 // INTERNAL INCLUDES
  22 #include <dali-toolkit/public-api/controls/control.h>
  23
  24 // EXTERNAL INCLUDES
  25 #include <dali/public-api/images/image-operations.h>
  26
  27 namespace Dali
  28 {
  29 namespace Toolkit
  30 {
  31 namespace Internal DALI_INTERNAL
  32 {
  33 class ImageView;
  34 }
  35 /**
  36  * @addtogroup dali_toolkit_controls_image_view
  37  * @{
  38  */
  39
  40 /**
  41  * @brief ImageView is a class for displaying an image resource.
  42  *
  43  * An instance of ImageView can be created using a URL or an Image instance.
  44  *
  45  * Some resources can be loaded before the ImageView is staged ( already cached ), in these cases if the connection to
  46  * ResouceReadySignal is done after the resource is set then signal will be missed.
  47  *
  48  * To protect against this, IsResourceReady() can be checked before connecting to ResourceReadySignal,
  49  * or the signal connection can be done before setting the resource.
  50  *
  51  * @code
  52  *    auto myImageView = ImageView::New( resourceUrl );
  53  *    if ( myImageView.IsResourceReady() )
  54  *    {
  55  *       // do something
  56  *    }
  57  *    else
  58  *    {
  59  *      myImageView.ResourceReadySignal.Connect( .... )
  60  *    }
  61  * @endcode
  62  *
  63  * OR Connect to signal before setting resource
  64  *
  65  * @code
  66  *    auto myImageView = ImageView::New();
  67  *    myImageView.ResourceReadySignal.Connect( .... )
  68  *    myImageView.SetProperty( ImageView::Property::IMAGE, resourceUrl );
  69  * @endcode
  70  *
  71  * @SINCE_1_0.0
  72  *
  73  */
  74 class DALI_TOOLKIT_API ImageView : public Control
  75 {
  76 public:
  77   /**
  78    * @brief Enumeration for the start and end property ranges for this control.
  79    * @SINCE_1_0.0
  80    */
  81   enum PropertyRange
  82   {
  83     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
  84     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000,             ///< Reserve property indices @SINCE_1_0.0
  85
  86     ANIMATABLE_PROPERTY_START_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX,       ///< @SINCE_1_1.18
  87     ANIMATABLE_PROPERTY_END_INDEX   = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX + 1000 ///< Reserve animatable property indices, @SINCE_1_1.18
  88   };
  89
  90   /**
  91    * @brief Enumeration for the instance of properties belonging to the ImageView class.
  92    * @SINCE_1_0.0
  93    */
  94   struct Property
  95   {
  96     /**
  97      * @brief Enumeration for the instance of properties belonging to the ImageView class.
  98      * @SINCE_1_0.0
  99      */
 100     enum
 101     {
 102       // Event side properties
 103
 104       /**
 105        * @brief name "image", type string if it is a url, map otherwise.
 106        * @SINCE_1_0.0
 107        */
 108       IMAGE = PROPERTY_START_INDEX,
 109
 110       /**
 111        * @brief name "preMultipliedAlpha", type Boolean.
 112        * @SINCE_1_1.18
 113        * @pre image must be initialized.
 114        */
 115       PRE_MULTIPLIED_ALPHA,
 116
 117       // Animatable properties
 118
 119       /**
 120        * @brief name "pixelArea", type Vector4.
 121        * @details Pixel area is a relative value with the whole image area as [0.0, 0.0, 1.0, 1.0].
 122        * @SINCE_1_1.18
 123        */
 124       PIXEL_AREA = ANIMATABLE_PROPERTY_START_INDEX,
 125     };
 126   };
 127
 128 public:
 129   /**
 130    * @brief Creates an uninitialized ImageView.
 131    * @SINCE_1_0.0
 132    */
 133   ImageView();
 134
 135   /**
 136    * @brief Create an initialized ImageView.
 137    *
 138    * @SINCE_1_0.0
 139    * @return A handle to a newly allocated Dali ImageView
 140    *
 141    * @note ImageView will not display anything.
 142    */
 143   static ImageView New();
 144
 145   /**
 146    * @brief Creates an initialized ImageView from an URL to an image resource.
 147    *
 148    * If the string is empty, ImageView will not display anything.
 149    *
 150    * @SINCE_1_0.0
 151    * @REMARK_INTERNET
 152    * @REMARK_STORAGE
 153    * @param[in] url The url of the image resource to display
 154    * @return A handle to a newly allocated ImageView
 155    */
 156   static ImageView New(const std::string& url);
 157
 158   /**
 159    * @brief Creates an initialized ImageView from a URL to an image resource.
 160    *
 161    * If the string is empty, ImageView will not display anything.
 162    *
 163    * @SINCE_1_1.10
 164    * @REMARK_INTERNET
 165    * @REMARK_STORAGE
 166    * @param[in] url The url of the image resource to display
 167    * @param [in] size The width and height to which to fit the loaded image
 168    * @return A handle to a newly allocated ImageView
 169    * @note A valid size is preferable for efficiency.
 170    *       However, do not set a size that is bigger than the actual image size, as up-scaling is not available.
 171    *       The content of the area not covered by the actual image is undefined and will not be cleared.
 172    */
 173   static ImageView New(const std::string& url, ImageDimensions size);
 174
 175   /**
 176    * @brief Create an initialized ImageView with additional behaviour.
 177    *
 178    * @SINCE_2_1.8
 179    * @param[in] additionalBehaviour Additional control behaviour
 180    * @return A handle to a newly allocated Dali ImageView
 181    *
 182    * @note ImageView will not display anything.
 183    */
 184   static ImageView New(ControlBehaviour additionalBehaviour);
 185
 186   /**
 187    * @brief Creates an initialized ImageView from an URL to an image resource with additional behaviour.
 188    *
 189    * If the string is empty, ImageView will not display anything.
 190    *
 191    * @SINCE_2_1.8
 192    * @REMARK_INTERNET
 193    * @REMARK_STORAGE
 194    * @param[in] additionalBehaviour Additional control behaviour
 195    * @param[in] url The url of the image resource to display
 196    * @return A handle to a newly allocated ImageView
 197    */
 198   static ImageView New(ControlBehaviour additionalBehaviour, const std::string& url);
 199
 200   /**
 201    * @brief Creates an initialized ImageView from a URL to an image resource with additional behaviour.
 202    *
 203    * If the string is empty, ImageView will not display anything.
 204    *
 205    * @SINCE_2_1.8
 206    * @REMARK_INTERNET
 207    * @REMARK_STORAGE
 208    * @param[in] additionalBehaviour Additional control behaviour
 209    * @param[in] url The url of the image resource to display
 210    * @param[in] size The width and height to which to fit the loaded image
 211    * @return A handle to a newly allocated ImageView
 212    * @note A valid size is preferable for efficiency.
 213    *       However, do not set a size that is bigger than the actual image size, as up-scaling is not available.
 214    *       The content of the area not covered by the actual image is undefined and will not be cleared.
 215    */
 216   static ImageView New(ControlBehaviour additionalBehaviour, const std::string& url, ImageDimensions size);
 217
 218   /**
 219    * @brief Destructor.
 220    *
 221    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 222    * @SINCE_1_0.0
 223    */
 224   ~ImageView();
 225
 226   /**
 227    * @brief Copy constructor.
 228    *
 229    * @SINCE_1_0.0
 230    * @param[in] imageView ImageView to copy. The copied ImageView will point at the same implementation
 231    */
 232   ImageView(const ImageView& imageView);
 233
 234   /**
 235    * @brief Move constructor
 236    * @SINCE_1_9.23
 237    *
 238    * @param[in] rhs A reference to the moved handle
 239    */
 240   ImageView(ImageView&& rhs);
 241
 242   /**
 243    * @brief Assignment operator.
 244    *
 245    * @SINCE_1_0.0
 246    * @param[in] imageView The ImageView to assign from
 247    * @return The updated ImageView
 248    */
 249   ImageView& operator=(const ImageView& imageView);
 250
 251   /**
 252    * @brief Move assignment
 253    * @SINCE_1_9.23
 254    *
 255    * @param[in] rhs A reference to the moved handle
 256    * @return A reference to this
 257    */
 258   ImageView& operator=(ImageView&& rhs);
 259
 260   /**
 261    * @brief Downcasts a handle to ImageView handle.
 262    *
 263    * If handle points to a ImageView, the downcast produces valid handle.
 264    * If not, the returned handle is left uninitialized.
 265    *
 266    * @SINCE_1_0.0
 267    * @param[in] handle Handle to an object
 268    * @return Handle to a ImageView or an uninitialized handle
 269    */
 270   static ImageView DownCast(BaseHandle handle);
 271
 272   /**
 273    * @brief Sets this ImageView from the given URL.
 274    *
 275    * If the URL is empty, ImageView will not display anything.
 276    *
 277    * @SINCE_1_1.4
 278    * @REMARK_INTERNET
 279    * @REMARK_STORAGE
 280    * @param[in] url The URL to the image resource to display
 281    */
 282   void SetImage(const std::string& url);
 283
 284   /**
 285    * @brief Sets this ImageView from the given URL.
 286    *
 287    * If the URL is empty, ImageView will not display anything.
 288    *
 289    * @SINCE_1_1.10
 290    * @REMARK_INTERNET
 291    * @REMARK_STORAGE
 292    * @param[in] url The URL to the image resource to display
 293    * @param [in] size The width and height to fit the loaded image to
 294    */
 295   void SetImage(const std::string& url, ImageDimensions size);
 296
 297 public: // Not intended for application developers
 298   /// @cond internal
 299   /**
 300    * @brief Creates a handle using the Toolkit::Internal implementation.
 301    *
 302    * @SINCE_1_0.0
 303    * @param[in] implementation The ImageView implementation
 304    */
 305   DALI_INTERNAL ImageView(Internal::ImageView& implementation);
 306
 307   /**
 308    * @brief Allows the creation of this ImageView from an Internal::CustomActor pointer.
 309    *
 310    * @SINCE_1_0.0
 311    * @param[in] internal A pointer to the internal CustomActor
 312    */
 313   DALI_INTERNAL ImageView(Dali::Internal::CustomActor* internal);
 314   /// @endcond
 315 };
 316
 317 /**
 318  * @}
 319  */
 320 } // namespace Toolkit
 321
 322 } // namespace Dali
 323
 324 #endif // DALI_TOOLKIT_IMAGE_VIEW_H