X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=dali-toolkit%2Fpublic-api%2Fcontrols%2Fimage-view%2Fimage-view.h;h=ac2befacbf7d56d925b9035073d452f8adb9a070;hp=4e98ccbb203c519bb738edab7916f84bb3294b34;hb=3217adaf159fc3dbed65113732fa6a72ef90dfc8;hpb=669373aecf093fe345b679b0ebe1e8056b12af2c 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 4e98ccb..ac2befa 100644 --- a/dali-toolkit/public-api/controls/image-view/image-view.h +++ b/dali-toolkit/public-api/controls/image-view/image-view.h @@ -21,6 +21,9 @@ // INTERNAL INCLUDES #include +// EXTERNAL INCLUDES +#include + namespace Dali { @@ -37,74 +40,175 @@ class ImageView; */ /** + * @brief ImageView is a class for displaying an image resource. + * + * 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 * - * @brief ImageView is a class for displaying an Image. */ class DALI_IMPORT_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, - PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000 ///< Reserve property indices + 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 }; /** - * @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 { - IMAGE = PROPERTY_START_INDEX, ///< name "image", @see SetImage(), type string if it is a url, map otherwise + // 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. + * @SINCE_1_0.0 + */ + IMAGE, + + /** + * @brief name "preMultipliedAlpha", type Boolean. + * @SINCE_1_1.18 + * @pre image must be initialized. + */ + PRE_MULTIPLIED_ALPHA, + + + // Animatable properties + + /** + * @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 + */ + PIXEL_AREA = ANIMATABLE_PROPERTY_START_INDEX, }; }; public: /** - * @brief Create an uninitialized ImageView. + * @brief Creates an uninitialized ImageView. + * @SINCE_1_0.0 */ ImageView(); /** * @brief Create an initialized ImageView. * - * @return A handle to a newly allocated Dali ImageView. + * @SINCE_1_0.0 + * @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. + * @DEPRECATED_1_2_8, use New( const std::string& ) instead. * - * If the handle is empty, ImageView will display nothing - * @param[in] image The Image to display. - * @return A handle to a newly allocated ImageView. + * @brief Creates an initialized ImageView from an Image instance. + * + * If the handle 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 */ - static ImageView New( Image image ); + static ImageView New( Image image ) DALI_DEPRECATED_API; /** - * @brief Create an initialized ImageView from an Image resource url + * @brief Creates an initialized ImageView from an URL to an image resource. + * + * If the string is empty, ImageView will not display anything. * - * If the string is empty, ImageView will display nothing - * @param[in] url The url of the image resource to display. - * @return A handle to a newly allocated ImageView. + * @SINCE_1_0.0 + * @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( const std::string& url ); /** - * @brief Destructor + * @brief Creates an initialized ImageView from a URL to an image resource. + * + * If the string is empty, ImageView will not display anything. + * + * @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, ImageDimensions size ); + + /** + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~ImageView(); /** * @brief Copy constructor. * + * @SINCE_1_0.0 * @param[in] imageView ImageView to copy. The copied ImageView will point at the same implementation */ ImageView( const ImageView& imageView ); @@ -112,63 +216,90 @@ public: /** * @brief Assignment operator. * - * @param[in] imageView The ImageView to assign from. - * @return The updated ImageView. + * @SINCE_1_0.0 + * @param[in] imageView The ImageView to assign from + * @return The updated ImageView */ ImageView& operator=( const ImageView& imageView ); /** - * @brief Downcast an Object handle to ImageView. + * @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 handle points to a ImageView, the downcast produces valid handle. + * If not, the returned handle is left uninitialized. * + * @SINCE_1_0.0 * @param[in] handle Handle to an object - * @return handle to a ImageView or an uninitialized handle + * @return Handle to a ImageView or an uninitialized handle */ static ImageView DownCast( BaseHandle handle ); /** - * @brief Sets this ImageView from an Image + * @DEPRECATED_1_2_8, use SetImage( const std::string& ) instead. + * + * @brief Sets this ImageView from an Image instance. * * If the handle is empty, ImageView will display nothing - * @param[in] image The Image to display. + * @SINCE_1_0.0 + * @param[in] image The Image instance to display. */ - void SetImage( Image image ); + void SetImage( Image image ) DALI_DEPRECATED_API; /** - * @brief Sets this ImageView from an Image url + * @brief Sets this ImageView from the given URL. * - * If the handle is empty, ImageView will display nothing - * - * @since DALi 1.1.4 + * If the URL is empty, ImageView will not display anything. * - * @param[in] url The Image resource to display. + * @SINCE_1_1.4 + * @REMARK_INTERNET + * @REMARK_STORAGE + * @param[in] url The URL to the image resource to display */ void SetImage( const std::string& url ); /** - * @deprecated Gets the Image + * @brief Sets this ImageView from the given URL. + * + * If the URL is empty, ImageView will not display anything. + * + * @SINCE_1_1.10 + * @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 + */ + 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. * - * @return The Image currently set to this ImageView + * @SINCE_1_0.0 + * @return The Image instance currently used by the ImageView */ - Image GetImage() const; + Image GetImage() const DALI_DEPRECATED_API; public: // Not intended for application developers + /// @cond internal /** * @brief Creates a handle using the Toolkit::Internal implementation. * - * @param[in] implementation The ImageView implementation. + * @SINCE_1_0.0 + * @param[in] implementation The ImageView implementation */ DALI_INTERNAL ImageView( Internal::ImageView& implementation ); /** * @brief Allows the creation of this ImageView from an Internal::CustomActor pointer. * - * @param[in] internal A pointer to the internal CustomActor. + * @SINCE_1_0.0 + * @param[in] internal A pointer to the internal CustomActor */ DALI_INTERNAL ImageView( Dali::Internal::CustomActor* internal ); + /// @endcond };