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) 2020 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 Destructor.
 177    *
 178    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 179    * @SINCE_1_0.0
 180    */
 181   ~ImageView();
 182
 183   /**
 184    * @brief Copy constructor.
 185    *
 186    * @SINCE_1_0.0
 187    * @param[in] imageView ImageView to copy. The copied ImageView will point at the same implementation
 188    */
 189   ImageView(const ImageView& imageView);
 190
 191   /**
 192    * @brief Move constructor
 193    * @SINCE_1_9.23
 194    *
 195    * @param[in] rhs A reference to the moved handle
 196    */
 197   ImageView(ImageView&& rhs);
 198
 199   /**
 200    * @brief Assignment operator.
 201    *
 202    * @SINCE_1_0.0
 203    * @param[in] imageView The ImageView to assign from
 204    * @return The updated ImageView
 205    */
 206   ImageView& operator=(const ImageView& imageView);
 207
 208   /**
 209    * @brief Move assignment
 210    * @SINCE_1_9.23
 211    *
 212    * @param[in] rhs A reference to the moved handle
 213    * @return A reference to this
 214    */
 215   ImageView& operator=(ImageView&& rhs);
 216
 217   /**
 218    * @brief Downcasts a handle to ImageView handle.
 219    *
 220    * If handle points to a ImageView, the downcast produces valid handle.
 221    * If not, the returned handle is left uninitialized.
 222    *
 223    * @SINCE_1_0.0
 224    * @param[in] handle Handle to an object
 225    * @return Handle to a ImageView or an uninitialized handle
 226    */
 227   static ImageView DownCast(BaseHandle handle);
 228
 229   /**
 230    * @brief Sets this ImageView from the given URL.
 231    *
 232    * If the URL is empty, ImageView will not display anything.
 233    *
 234    * @SINCE_1_1.4
 235    * @REMARK_INTERNET
 236    * @REMARK_STORAGE
 237    * @param[in] url The URL to the image resource to display
 238    */
 239   void SetImage(const std::string& url);
 240
 241   /**
 242    * @brief Sets this ImageView from the given URL.
 243    *
 244    * If the URL is empty, ImageView will not display anything.
 245    *
 246    * @SINCE_1_1.10
 247    * @REMARK_INTERNET
 248    * @REMARK_STORAGE
 249    * @param[in] url The URL to the image resource to display
 250    * @param [in] size The width and height to fit the loaded image to
 251    */
 252   void SetImage(const std::string& url, ImageDimensions size);
 253
 254 public: // Not intended for application developers
 255   /// @cond internal
 256   /**
 257    * @brief Creates a handle using the Toolkit::Internal implementation.
 258    *
 259    * @SINCE_1_0.0
 260    * @param[in] implementation The ImageView implementation
 261    */
 262   DALI_INTERNAL ImageView(Internal::ImageView& implementation);
 263
 264   /**
 265    * @brief Allows the creation of this ImageView from an Internal::CustomActor pointer.
 266    *
 267    * @SINCE_1_0.0
 268    * @param[in] internal A pointer to the internal CustomActor
 269    */
 270   DALI_INTERNAL ImageView(Dali::Internal::CustomActor* internal);
 271   /// @endcond
 272 };
 273
 274 /**
 275  * @}
 276  */
 277 } // namespace Toolkit
 278
 279 } // namespace Dali
 280
 281 #endif // DALI_TOOLKIT_IMAGE_VIEW_H