X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;ds=sidebyside;f=dali-toolkit%2Fpublic-api%2Fcontrols%2Fimage-view%2Fimage-view.h;h=78178faebe73084b3a66faa34922ce78c89c2513;hb=b3f769e350cf3c159ab22bd947f1e98d47cb4038;hp=bc401f1246d404f33bd6faa790616f590959e7bc;hpb=1b0a5f5931b61343586de7cd62fd44793c79ae73;p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git diff --git a/dali-toolkit/public-api/controls/image-view/image-view.h b/dali-toolkit/public-api/controls/image-view/image-view.h index bc401f1..78178fa 100644 --- a/dali-toolkit/public-api/controls/image-view/image-view.h +++ b/dali-toolkit/public-api/controls/image-view/image-view.h @@ -1,8 +1,8 @@ -#ifndef __DALI_TOOLKIT_IMAGE_VIEW_H__ -#define __DALI_TOOLKIT_IMAGE_VIEW_H__ +#ifndef DALI_TOOLKIT_IMAGE_VIEW_H +#define DALI_TOOLKIT_IMAGE_VIEW_H /* - * Copyright (c) 2015 Samsung Electronics Co., Ltd. + * Copyright (c) 2022 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -26,10 +26,8 @@ namespace Dali { - namespace Toolkit { - namespace Internal DALI_INTERNAL { class ImageView; @@ -44,61 +42,82 @@ class ImageView; * * An instance of ImageView can be created using a URL or an Image instance. * + * Some resources can be loaded before the ImageView is staged ( already cached ), in these cases if the connection to + * ResouceReadySignal is done after the resource is set then signal will be missed. + * + * To protect against this, IsResourceReady() can be checked before connecting to ResourceReadySignal, + * or the signal connection can be done before setting the resource. + * + * @code + * auto myImageView = ImageView::New( resourceUrl ); + * if ( myImageView.IsResourceReady() ) + * { + * // do something + * } + * else + * { + * myImageView.ResourceReadySignal.Connect( .... ) + * } + * @endcode + * + * OR Connect to signal before setting resource + * + * @code + * auto myImageView = ImageView::New(); + * myImageView.ResourceReadySignal.Connect( .... ) + * myImageView.SetProperty( ImageView::Property::IMAGE, resourceUrl ); + * @endcode + * * @SINCE_1_0.0 * */ -class DALI_IMPORT_API ImageView : public Control +class DALI_TOOLKIT_API ImageView : public Control { public: - /** - * @brief The start and end property ranges for this control. + * @brief Enumeration for the start and end property ranges for this control. * @SINCE_1_0.0 */ enum PropertyRange { - PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0 - PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000, ///< Reserve property indices @SINCE_1_0.0 + PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0 + PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000, ///< Reserve property indices @SINCE_1_0.0 - ANIMATABLE_PROPERTY_START_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX, ///< @SINCE_1_1.18 - ANIMATABLE_PROPERTY_END_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX + 1000 ///< Reserve animatable property indices, @SINCE_1_1.18 + ANIMATABLE_PROPERTY_START_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX, ///< @SINCE_1_1.18 + ANIMATABLE_PROPERTY_END_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX + 1000 ///< Reserve animatable property indices, @SINCE_1_1.18 }; /** - * @brief An enumeration of properties belonging to the ImageView class. + * @brief Enumeration for the instance of properties belonging to the ImageView class. * @SINCE_1_0.0 */ struct Property { + /** + * @brief Enumeration for the instance of properties belonging to the ImageView class. + * @SINCE_1_0.0 + */ enum { // Event side properties /** - * @DEPRECATED_1_1.16. Use IMAGE instead. - * @brief name "resourceUrl", type string - * @SINCE_1_0.0 - */ - RESOURCE_URL = PROPERTY_START_INDEX, - - /** - * @brief name "image", type string if it is a url, map otherwise + * @brief name "image", type string if it is a url, map otherwise. * @SINCE_1_0.0 */ - IMAGE, + IMAGE = PROPERTY_START_INDEX, /** - * @brief name "preMultipliedAlpha", type Boolean + * @brief name "preMultipliedAlpha", type Boolean. * @SINCE_1_1.18 * @pre image must be initialized. */ PRE_MULTIPLIED_ALPHA, - // Animatable properties /** - * @brief name "pixelArea", type Vector4 + * @brief name "pixelArea", type Vector4. * @details Pixel area is a relative value with the whole image area as [0.0, 0.0, 1.0, 1.0]. * @SINCE_1_1.18 */ @@ -107,9 +126,8 @@ public: }; public: - /** - * @brief Create an uninitialized ImageView. + * @brief Creates an uninitialized ImageView. * @SINCE_1_0.0 */ ImageView(); @@ -118,52 +136,87 @@ public: * @brief Create an initialized ImageView. * * @SINCE_1_0.0 - * @return A handle to a newly allocated Dali ImageView. + * @return A handle to a newly allocated Dali ImageView * * @note ImageView will not display anything. */ static ImageView New(); /** - * @brief Create an initialized ImageView from an Image instance. + * @brief Creates an initialized ImageView from an URL to an image resource. * - * If the handle is empty, ImageView will not display anything. + * If the string is empty, ImageView will not display anything. * * @SINCE_1_0.0 - * @param[in] image The Image instance to display. - * @return A handle to a newly allocated ImageView. + * @REMARK_INTERNET + * @REMARK_STORAGE + * @param[in] url The url of the image resource to display + * @return A handle to a newly allocated ImageView */ - static ImageView New( Image image ); + static ImageView New(const std::string& url); /** - * @brief Create an initialized ImageView from an URL to an image resource. + * @brief Creates an initialized ImageView from a URL to an image resource. * * If the string is empty, ImageView will not display anything. * - * @SINCE_1_0.0 - * @param[in] url The url of the image resource to display. - * @return A handle to a newly allocated ImageView. + * @SINCE_1_1.10 + * @REMARK_INTERNET + * @REMARK_STORAGE + * @param[in] url The url of the image resource to display + * @param [in] size The width and height to which to fit the loaded image + * @return A handle to a newly allocated ImageView + * @note A valid size is preferable for efficiency. + * However, do not set a size that is bigger than the actual image size, as up-scaling is not available. + * The content of the area not covered by the actual image is undefined and will not be cleared. */ - static ImageView New( const std::string& url ); + static ImageView New(const std::string& url, ImageDimensions size); /** - * @brief Create an initialized ImageView from a URL to an image resource. + * @brief Create an initialized ImageView with additional behaviour. + * + * @SINCE_2_1.8 + * @param[in] additionalBehaviour Additional control behaviour + * @return A handle to a newly allocated Dali ImageView + * + * @note ImageView will not display anything. + */ + static ImageView New(ControlBehaviour additionalBehaviour); + + /** + * @brief Creates an initialized ImageView from an URL to an image resource with additional behaviour. * * If the string is empty, ImageView will not display anything. * - * @SINCE_1_1.10 - * @param[in] url The url of the image resource to display. - * @param [in] size The width and height to which to fit the loaded image. - * @return A handle to a newly allocated ImageView. + * @SINCE_2_1.8 + * @REMARK_INTERNET + * @REMARK_STORAGE + * @param[in] additionalBehaviour Additional control behaviour + * @param[in] url The url of the image resource to display + * @return A handle to a newly allocated ImageView + */ + static ImageView New(ControlBehaviour additionalBehaviour, const std::string& url); + + /** + * @brief Creates an initialized ImageView from a URL to an image resource with additional behaviour. + * + * If the string is empty, ImageView will not display anything. * + * @SINCE_2_1.8 + * @REMARK_INTERNET + * @REMARK_STORAGE + * @param[in] additionalBehaviour Additional control behaviour + * @param[in] url The url of the image resource to display + * @param[in] size The width and height to which to fit the loaded image + * @return A handle to a newly allocated ImageView * @note A valid size is preferable for efficiency. * However, do not set a size that is bigger than the actual image size, as up-scaling is not available. * The content of the area not covered by the actual image is undefined and will not be cleared. */ - static ImageView New( const std::string& url, ImageDimensions size ); + static ImageView New(ControlBehaviour additionalBehaviour, const std::string& url, ImageDimensions size); /** - * @brief Destructor + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. * @SINCE_1_0.0 @@ -176,37 +229,45 @@ public: * @SINCE_1_0.0 * @param[in] imageView ImageView to copy. The copied ImageView will point at the same implementation */ - ImageView( const ImageView& imageView ); + ImageView(const ImageView& imageView); + + /** + * @brief Move constructor + * @SINCE_1_9.23 + * + * @param[in] rhs A reference to the moved handle + */ + ImageView(ImageView&& rhs); /** * @brief Assignment operator. * * @SINCE_1_0.0 - * @param[in] imageView The ImageView to assign from. - * @return The updated ImageView. + * @param[in] imageView The ImageView to assign from + * @return The updated ImageView */ - ImageView& operator=( const ImageView& imageView ); + ImageView& operator=(const ImageView& imageView); /** - * @brief Downcast a handle to ImageView handle. - * - * If handle points to a ImageView the downcast produces valid - * handle. If not the returned handle is left uninitialized. + * @brief Move assignment + * @SINCE_1_9.23 * - * @SINCE_1_0.0 - * @param[in] handle Handle to an object - * @return handle to a ImageView or an uninitialized handle + * @param[in] rhs A reference to the moved handle + * @return A reference to this */ - static ImageView DownCast( BaseHandle handle ); + ImageView& operator=(ImageView&& rhs); /** - * @brief Sets this ImageView from an Image instance. + * @brief Downcasts a handle to ImageView handle. + * + * If handle points to a ImageView, the downcast produces valid handle. + * If not, the returned handle is left uninitialized. * - * If the handle is empty, ImageView will display nothing * @SINCE_1_0.0 - * @param[in] image The Image instance to display. + * @param[in] handle Handle to an object + * @return Handle to a ImageView or an uninitialized handle */ - void SetImage( Image image ); + static ImageView DownCast(BaseHandle handle); /** * @brief Sets this ImageView from the given URL. @@ -214,9 +275,11 @@ public: * If the URL is empty, ImageView will not display anything. * * @SINCE_1_1.4 - * @param[in] url The URL to the image resource to display. + * @REMARK_INTERNET + * @REMARK_STORAGE + * @param[in] url The URL to the image resource to display */ - void SetImage( const std::string& url ); + void SetImage(const std::string& url); /** * @brief Sets this ImageView from the given URL. @@ -224,40 +287,31 @@ public: * If the URL is empty, ImageView will not display anything. * * @SINCE_1_1.10 - * @param[in] url The URL to the image resource to display. - * @param [in] size The width and height to fit the loaded image to. - */ - void SetImage( const std::string& url, ImageDimensions size ); - - /** - * @DEPRECATED_1_1.4 - * @brief Gets the Image instance handle used by the ImageView. - * - * A valid handle will be returned only if this instance was created with New(Image) or SetImage(Image) was called. - * - * @SINCE_1_0.0 - * @return The Image instance currently used by the ImageView. + * @REMARK_INTERNET + * @REMARK_STORAGE + * @param[in] url The URL to the image resource to display + * @param [in] size The width and height to fit the loaded image to */ - Image GetImage() const; + void SetImage(const std::string& url, ImageDimensions size); public: // Not intended for application developers - + /// @cond internal /** * @brief Creates a handle using the Toolkit::Internal implementation. * * @SINCE_1_0.0 - * @param[in] implementation The ImageView implementation. + * @param[in] implementation The ImageView implementation */ - DALI_INTERNAL ImageView( Internal::ImageView& implementation ); + DALI_INTERNAL ImageView(Internal::ImageView& implementation); /** * @brief Allows the creation of this ImageView from an Internal::CustomActor pointer. * * @SINCE_1_0.0 - * @param[in] internal A pointer to the internal CustomActor. + * @param[in] internal A pointer to the internal CustomActor */ - DALI_INTERNAL ImageView( Dali::Internal::CustomActor* internal ); - + DALI_INTERNAL ImageView(Dali::Internal::CustomActor* internal); + /// @endcond }; /** @@ -267,4 +321,4 @@ public: // Not intended for application developers } // namespace Dali -#endif // __DALI_TOOLKIT_IMAGE_VIEW_H__ +#endif // DALI_TOOLKIT_IMAGE_VIEW_H