X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali-toolkit%2Fpublic-api%2Fcontrols%2Fimage-view%2Fimage-view.h;h=d58e23968ee60a5dac28cb3ac9ef935603ff9850;hb=51edb9ef53a0ef0eaa93f04e7ff846c2303488a2;hp=a5529b6d5ae455937ec332842b2dcf752fd7757e;hpb=e2eda444afbe82e9591fe198eef339227f90a616;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 a5529b6..d58e239 100644 --- a/dali-toolkit/public-api/controls/image-view/image-view.h +++ b/dali-toolkit/public-api/controls/image-view/image-view.h @@ -1,26 +1,30 @@ #ifndef __DALI_TOOLKIT_IMAGE_VIEW_H__ #define __DALI_TOOLKIT_IMAGE_VIEW_H__ -// -// Copyright (c) 2014 Samsung Electronics Co., Ltd. -// -// Licensed under the Flora License, Version 1.0 (the License); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://floralicense.org/license/ -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an AS IS BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// +/* + * Copyright (c) 2015 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. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ // INTERNAL INCLUDES #include -namespace Dali DALI_IMPORT_API +// EXTERNAL INCLUDES +#include + +namespace Dali { namespace Toolkit @@ -30,165 +34,241 @@ namespace Internal DALI_INTERNAL { class ImageView; } - -class Button; +/** + * @addtogroup dali_toolkit_controls_image_view + * @{ + */ /** - * ImageView control loads and displays the correct - * image for the current level of detail (LOD) required. - * LOD is typically calculated from the Camera distance. + * @brief ImageView is a class for displaying an image resource. * - * Example: + * An instance of ImageView can be created using a URL or an Image instance. * - * ImageView imageView = ImageView::New(); - * imageView.SetCameraActor( mCamera ); - * imageView.SetSize( Vector2(64.0f, 64.0f) ); - * imageView.SetImage( "my-image.png", ImageView::BitmapType, 0.125f, 4.0f ); - * layer.Add(imageView); + * @SINCE_1_0.0 * - * The above creates an ImageView at 64x64 in size. Images of 12.5% the size up - * to 400% the size of imageView are created - * i.e. 8x8, 16x16, 32x32, 64x64, 128x128, and 256x256 - * - * based on the distance imageView is from mCamera an appropriate, different - * image will be loaded and dispayed. */ -class ImageView : public Control +class DALI_IMPORT_API ImageView : public Control { public: /** - * Image Types, determines how image should be rendered. + * @brief The start and end property ranges for this control. + * @SINCE_1_0.0 */ - enum ImageType + enum PropertyRange { - BitmapType, ///< Standard Bitmap image - DistanceFieldType ///< Distance Field encoded image + 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 }; - static const std::string DETAIL_PROPERTY_NAME; ///< The level of detail property + /** + * @brief An enumeration of properties belonging to the ImageView class. + * @SINCE_1_0.0 + */ + struct Property + { + 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 + * @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: /** - * Creates an empty ImageView handle + * @brief Create an uninitialized ImageView. + * @SINCE_1_0.0 */ ImageView(); /** - * Copy constructor. Creates another handle that points to the same real object - * @param handle to copy from + * @brief Create an initialized ImageView. + * + * @SINCE_1_0.0 + * @return A handle to a newly allocated Dali ImageView. + * + * @note ImageView will not display anything. */ - ImageView( const ImageView& handle ); + static ImageView New(); /** - * Assignment operator. Changes this handle to point to another real object + * @DEPRECATED_1_2.8, use New( const std::string& ) instead. + * + * @brief Create 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. */ - ImageView& operator=( const ImageView& handle ); + static ImageView New( Image image ); /** - * Virtual destructor. - * Dali::Object derived classes typically do not contain member data. + * @brief Create an initialized ImageView from an 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. */ - virtual ~ImageView(); + static ImageView New( const std::string& url ); /** - * Create the Poup control - * @return A handle to the ImageView control. + * @brief Create an initialized ImageView from a URL to an image resource. + * + * 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. + * + * @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(); + static ImageView New( const std::string& url, ImageDimensions size ); /** - * Downcast an Object handle to ImageView. If handle points to an ImageView the - * downcast produces valid handle. If not the returned handle is left uninitialized. - * @param[in] handle Handle to an object - * @return handle to a ImageView or an uninitialized handle + * @brief Destructor + * + * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ - static ImageView DownCast( BaseHandle handle ); + ~ImageView(); -public: + /** + * @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 ); /** - * Load image into ImageView for level of detail scaling. - * Will automatically create different sized versions - * of the source image. + * @brief Assignment operator. * - * @param[in] filename The image path to load - * @param[in] type The type of image e.g. BitmapType or DistanceFieldType + * @SINCE_1_0.0 + * @param[in] imageView The ImageView to assign from. + * @return The updated ImageView. */ - void SetImage(const std::string& filename, ImageType type); + ImageView& operator=( const ImageView& imageView ); /** - * Load image into ImageView for level of detail scaling. - * The minimum scale is a percentage of the size of the - * image view, and represents the smallest version of the - * source image to display e.g. 0.125 for 12.5% - * While the maximum scale represents the largest version of - * the source image to display e.g. 1.00 for 100% (original - * image view size) + * @brief Downcast a handle to ImageView handle. * - * @note ImageView SetSize must be set specified prior to - * calling this. + * If handle points to a ImageView the downcast produces valid + * handle. If not the returned handle is left uninitialized. * - * @param[in] filename The image path to load - * @param[in] type The type of image e.g. BitmapImage or DistanceFieldImage - * @param[in] min The minimum scale detail to load. - * @param[in] max The maximum scale detail to load. + * @SINCE_1_0.0 + * @param[in] handle Handle to an object + * @return handle to a ImageView or an uninitialized handle */ - void SetImage(const std::string& filename, ImageType type, float min, float max); + static ImageView DownCast( BaseHandle handle ); /** - * Sets an image to displayed for the entire detail range. - * Regardless of the detail level this image will be displayed. + * @DEPRECATED_1_2.8, use SetImage( const std::string& ) instead. * - * @param[in] image The image to display + * @brief Sets this ImageView from an Image instance. + * + * If the handle is empty, ImageView will display nothing + * @SINCE_1_0.0 + * @param[in] image The Image instance to display. */ - void SetImage(Image image); + void SetImage( Image image ); /** - * Sets the camera to use for determining level of detail. - * Which is based on distance from camera to this ImageView. - * The detailFactor is the distance at which the ImageView - * should appear at 100% scale. Which may differ based on - * Projection, and ShaderEffect settings. - * @param[in] camera The camera + * @brief Sets this ImageView from the given URL. + * + * 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. */ - void SetCameraActor(CameraActor camera); + void SetImage( const std::string& url ); /** - * Sets the camera to use for determining level of detail. - * Which is based on distance from camera to this ImageView. - * The detailFactor is the distance at which the ImageView - * should appear at 100% scale. Which may differ based on - * Projection, and ShaderEffect settings. - * @param[in] camera The camera - * @param[in] detailFactor The Camera distance where detail should be 1.0 - * (ImageView should appear at 100% scale) + * @brief Sets this ImageView from the given URL. + * + * 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 SetCameraActor(CameraActor camera, float detailFactor); + void SetImage( const std::string& url, ImageDimensions size ); /** - * Sets the current detail level. - * @note This sets the detail property value. - * @param[in] detail The level of detail to be viewed at. + * @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. */ - void SetDetail(float detail); + Image GetImage() const; public: // Not intended for application developers + /// @cond internal /** - * Creates a handle using the Toolkit::Internal implementation. - * @param[in] implementation The Control implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * + * @SINCE_1_0.0 + * @param[in] implementation The ImageView implementation. */ - ImageView(Internal::ImageView& implementation); + DALI_INTERNAL ImageView( Internal::ImageView& implementation ); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @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. */ - ImageView(Dali::Internal::CustomActor* internal); + DALI_INTERNAL ImageView( Dali::Internal::CustomActor* internal ); + /// @endcond + }; +/** + * @} + */ } // namespace Toolkit } // namespace Dali