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) 2023 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       /**
 118        * @brief name "placeholderImage", type string.
 119        *
 120        * placeholder image is shown when image view is waiting for the image to load.
 121        * @SINCE_2_2.24
 122        */
 123       PLACEHOLDER_IMAGE,
 124
 125       /**
 126        * @brief name "enableTransitionEffect", type Boolean
 127        *
 128        * This effect is a crossfade effect when the image is replaced.
 129        * the default duration of the crossfade effect is 1.5 seconds.
 130        * if the placeholder is enabled, the cross effect applies when the image is changed from a placeholder image to a new image.
 131        * if not, the cross effect applies when a new image is shown or is changed from the previous image to a new image.
 132        * @SINCE_2_2.24
 133        */
 134       ENABLE_TRANSITION_EFFECT,
 135
 136       // Animatable properties
 137
 138       /**
 139        * @brief name "pixelArea", type Vector4.
 140        * @details Pixel area is a relative value with the whole image area as [0.0, 0.0, 1.0, 1.0].
 141        * @SINCE_1_1.18
 142        */
 143       PIXEL_AREA = ANIMATABLE_PROPERTY_START_INDEX,
 144     };
 145   };
 146
 147 public:
 148   /**
 149    * @brief Creates an uninitialized ImageView.
 150    * @SINCE_1_0.0
 151    */
 152   ImageView();
 153
 154   /**
 155    * @brief Create an initialized ImageView.
 156    *
 157    * @SINCE_1_0.0
 158    * @return A handle to a newly allocated Dali ImageView
 159    *
 160    * @note ImageView will not display anything.
 161    */
 162   static ImageView New();
 163
 164   /**
 165    * @brief Creates an initialized ImageView from an URL to an image resource.
 166    *
 167    * If the string is empty, ImageView will not display anything.
 168    *
 169    * @SINCE_1_0.0
 170    * @REMARK_INTERNET
 171    * @REMARK_STORAGE
 172    * @param[in] url The url of the image resource to display
 173    * @return A handle to a newly allocated ImageView
 174    */
 175   static ImageView New(const std::string& url);
 176
 177   /**
 178    * @brief Creates an initialized ImageView from a URL to an image resource.
 179    *
 180    * If the string is empty, ImageView will not display anything.
 181    *
 182    * @SINCE_1_1.10
 183    * @REMARK_INTERNET
 184    * @REMARK_STORAGE
 185    * @param[in] url The url of the image resource to display
 186    * @param [in] size The width and height to which to fit the loaded image
 187    * @return A handle to a newly allocated ImageView
 188    * @note A valid size is preferable for efficiency.
 189    *       However, do not set a size that is bigger than the actual image size, as up-scaling is not available.
 190    *       The content of the area not covered by the actual image is undefined and will not be cleared.
 191    */
 192   static ImageView New(const std::string& url, ImageDimensions size);
 193
 194   /**
 195    * @brief Create an initialized ImageView with additional behaviour.
 196    *
 197    * @SINCE_2_1.8
 198    * @param[in] additionalBehaviour Additional control behaviour
 199    * @return A handle to a newly allocated Dali ImageView
 200    *
 201    * @note ImageView will not display anything.
 202    */
 203   static ImageView New(ControlBehaviour additionalBehaviour);
 204
 205   /**
 206    * @brief Creates an initialized ImageView from an URL to an image resource with additional behaviour.
 207    *
 208    * If the string is empty, ImageView will not display anything.
 209    *
 210    * @SINCE_2_1.8
 211    * @REMARK_INTERNET
 212    * @REMARK_STORAGE
 213    * @param[in] additionalBehaviour Additional control behaviour
 214    * @param[in] url The url of the image resource to display
 215    * @return A handle to a newly allocated ImageView
 216    */
 217   static ImageView New(ControlBehaviour additionalBehaviour, const std::string& url);
 218
 219   /**
 220    * @brief Creates an initialized ImageView from a URL to an image resource with additional behaviour.
 221    *
 222    * If the string is empty, ImageView will not display anything.
 223    *
 224    * @SINCE_2_1.8
 225    * @REMARK_INTERNET
 226    * @REMARK_STORAGE
 227    * @param[in] additionalBehaviour Additional control behaviour
 228    * @param[in] url The url of the image resource to display
 229    * @param[in] size The width and height to which to fit the loaded image
 230    * @return A handle to a newly allocated ImageView
 231    * @note A valid size is preferable for efficiency.
 232    *       However, do not set a size that is bigger than the actual image size, as up-scaling is not available.
 233    *       The content of the area not covered by the actual image is undefined and will not be cleared.
 234    */
 235   static ImageView New(ControlBehaviour additionalBehaviour, const std::string& url, ImageDimensions size);
 236
 237   /**
 238    * @brief Destructor.
 239    *
 240    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 241    * @SINCE_1_0.0
 242    */
 243   ~ImageView();
 244
 245   /**
 246    * @brief Copy constructor.
 247    *
 248    * @SINCE_1_0.0
 249    * @param[in] imageView ImageView to copy. The copied ImageView will point at the same implementation
 250    */
 251   ImageView(const ImageView& imageView);
 252
 253   /**
 254    * @brief Move constructor
 255    * @SINCE_1_9.23
 256    *
 257    * @param[in] rhs A reference to the moved handle
 258    */
 259   ImageView(ImageView&& rhs) noexcept;
 260
 261   /**
 262    * @brief Assignment operator.
 263    *
 264    * @SINCE_1_0.0
 265    * @param[in] imageView The ImageView to assign from
 266    * @return The updated ImageView
 267    */
 268   ImageView& operator=(const ImageView& imageView);
 269
 270   /**
 271    * @brief Move assignment
 272    * @SINCE_1_9.23
 273    *
 274    * @param[in] rhs A reference to the moved handle
 275    * @return A reference to this
 276    */
 277   ImageView& operator=(ImageView&& rhs) noexcept;
 278
 279   /**
 280    * @brief Downcasts a handle to ImageView handle.
 281    *
 282    * If handle points to a ImageView, the downcast produces valid handle.
 283    * If not, the returned handle is left uninitialized.
 284    *
 285    * @SINCE_1_0.0
 286    * @param[in] handle Handle to an object
 287    * @return Handle to a ImageView or an uninitialized handle
 288    */
 289   static ImageView DownCast(BaseHandle handle);
 290
 291   /**
 292    * @brief Sets this ImageView from the given URL.
 293    *
 294    * If the URL is empty, ImageView will not display anything.
 295    *
 296    * @SINCE_1_1.4
 297    * @REMARK_INTERNET
 298    * @REMARK_STORAGE
 299    * @param[in] url The URL to the image resource to display
 300    */
 301   void SetImage(const std::string& url);
 302
 303   /**
 304    * @brief Sets this ImageView from the given URL.
 305    *
 306    * If the URL is empty, ImageView will not display anything.
 307    *
 308    * @SINCE_1_1.10
 309    * @REMARK_INTERNET
 310    * @REMARK_STORAGE
 311    * @param[in] url The URL to the image resource to display
 312    * @param [in] size The width and height to fit the loaded image to
 313    */
 314   void SetImage(const std::string& url, ImageDimensions size);
 315
 316 public: // Not intended for application developers
 317   /// @cond internal
 318   /**
 319    * @brief Creates a handle using the Toolkit::Internal implementation.
 320    *
 321    * @SINCE_1_0.0
 322    * @param[in] implementation The ImageView implementation
 323    */
 324   DALI_INTERNAL ImageView(Internal::ImageView& implementation);
 325
 326   /**
 327    * @brief Allows the creation of this ImageView from an Internal::CustomActor pointer.
 328    *
 329    * @SINCE_1_0.0
 330    * @param[in] internal A pointer to the internal CustomActor
 331    */
 332   DALI_INTERNAL ImageView(Dali::Internal::CustomActor* internal);
 333   /// @endcond
 334 };
 335
 336 /**
 337  * @}
 338  */
 339 } // namespace Toolkit
 340
 341 } // namespace Dali
 342
 343 #endif // DALI_TOOLKIT_IMAGE_VIEW_H