dali/public-api/actors/image-actor.h

   1 #ifndef __DALI_IMAGE_ACTOR_H__
   2 #define __DALI_IMAGE_ACTOR_H__
   3
   4 /*
   5  * Copyright (c) 2014 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 // EXTERNAL INCLUDES
  22 #include <string>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/actors/renderable-actor.h>
  26 #include <dali/public-api/math/rect.h>
  27 #include <dali/public-api/images/image.h>
  28
  29 namespace Dali DALI_IMPORT_API
  30 {
  31
  32 namespace Internal DALI_INTERNAL
  33 {
  34 class ImageActor;
  35 }
  36
  37 /**
  38  * @brief An actor for displaying images.
  39  *
  40  * Allows the developer to add an actor to stage which displays the content of an Image object.
  41  *
  42  * By default CullFaceMode is set to CullNone to enable the ImageActor to be viewed from all angles.
  43  *
  44  * If an ImageActor is created without setting size, then the actor takes the size of the image -
  45  * this is the natural size.
  46  * Setting a size on the ImageActor, e.g through the SetSize api or through an animation will
  47  * stop the natural size being used.
  48  *
  49  * Such a set size can be changed back to the image's size by calling SetToNaturalSize().
  50  *
  51  * If a pixel area is set on an ImageActor with natural size, the actor size will change
  52  * to match the pixel area. If a pixel area is set on an ImageActor that has had it's size set,
  53  * then the size doesn't change, and the partial image will be stretched to fill the set size.
  54  *
  55  * Clearing the pixel area on an Image actor with natural size will cause the actor to show the
  56  * whole image again, and will change size back to that of the image.
  57  *
  58  * Clearing the pixel area on an Image actor with a set size will cause the actor to show the
  59  * whole image again, but will not change the image size.
  60  */
  61 class DALI_IMPORT_API ImageActor : public RenderableActor
  62 {
  63 public:
  64
  65   // Default Properties additional to RenderableActor
  66   static const Property::Index PIXEL_AREA;           ///< name "pixel-area",          type RECTANGLE
  67   static const Property::Index FADE_IN;              ///< name "fade-in",             type BOOLEAN
  68   static const Property::Index FADE_IN_DURATION;     ///< name "fade-in-duration",    type FLOAT
  69   static const Property::Index STYLE;                ///< name "style",               type STRING
  70   static const Property::Index BORDER;               ///< name "border",              type VECTOR4
  71   static const Property::Index IMAGE;                ///< name "image",               type MAP {"filename":"", "load-policy":...}
  72
  73   /**
  74    * @brief Style determines how the Image is rendered.
  75    *
  76    * @code
  77    * STYLE_QUAD:
  78    *
  79    *  0---------2           0-----------------2
  80    *  |        /|           |                /|
  81    *  |  A    / |           |      A       /  |
  82    *  |      /  |           |            /    |
  83    *  |     /   | SCALE (X) |          /      |
  84    *  |    /    | --------> |        /        |
  85    *  |   /     |           |      /          |
  86    *  |  /      |           |    /            |
  87    *  | /    B  |           |  /        B     |
  88    *  |/        |           |/                |
  89    *  1---------3           1-----------------3
  90    *
  91    * Image is rendered as a textured rectangle. The texture
  92    * is scaled uniformly as the quad is resized.
  93    *
  94    * STYLE_NINE_PATCH:
  95    *
  96    *  |---|---------------|---|       |---|-----------------------------|---|
  97    *  | 1 |       2       | 3 |       | 1 |              2              | 3 |
  98    *  |---|---------------|---|       |---|-----------------------------|---|
  99    *  |   |               |   |       |   |                             |   |
 100    *  |   |               |   |       |   |                             |   |
 101    *  | 4 |       5       | 6 | SCALE |   |                             |   |
 102    *  |   |               |   | ----> |   |                             |   |
 103    *  |   |               |   |       | 4 |              5              | 6 |
 104    *  |-------------------|---|       |   |                             |   |
 105    *  | 7 |       8       | 9 |       |   |                             |   |
 106    *  |---|---------------|---|       |   |                             |   |
 107    *                                  |---------------------------------|---|
 108    *                                  | 7 |              8              | 9 |
 109    *                                  |---|-----------------------------|---|
 110    *
 111    * @endcode
 112    * Image is rendered as a textured rectangle. The texture
 113    * is scaled differently over each of the 9 sections.
 114    *
 115    * Visualise a Picture Frame:
 116    *
 117    * - Corner sections (1,3,7,9) are not scaled, regardless
 118    * of how big the Image is.
 119    * - Horizontal edge sections (2,8) are scaled only in the
 120    * X axis as the image increases in width.
 121    * - Vertical edge sections (4,6) are scaled only in the
 122    * Y axis as the image increases in height.
 123    * - Center section (5) is scaled in both X and Y axes as
 124    * the image increases in width and/or height.
 125    *
 126    * Note: If GRID hints are enabled (via a Shader that requires it),
 127    * the above geometry will be further subdivided into rectangles of
 128    * approx. 40x40 in size.
 129    *
 130    */
 131   enum Style
 132   {
 133     STYLE_QUAD,       ///< As a simple quad.
 134     STYLE_NINE_PATCH  ///< As a nine-patch.
 135   };
 136
 137   /**
 138    * @brief Pixel area is relative to the top-left (0,0) of the image.
 139    */
 140   typedef Rect<int> PixelArea;
 141
 142   /**
 143    * @brief Create an uninitialized ImageActor handle.
 144    *
 145    * This can be initialized with ImageActor::New(...)
 146    * Calling member functions with an uninitialized Dali::Object is not allowed.
 147    */
 148   ImageActor();
 149
 150   /**
 151    * @brief Create an empty image actor object.
 152    *
 153    * @return A handle to a newly allocated actor.
 154    */
 155   static ImageActor New();
 156
 157   /**
 158    * @brief Create a image actor object.
 159    *
 160    * The actor will take the image's natural size unless a custom size
 161    * is chosen, e.g. via Actor:SetSize()
 162    * @pre image must be initialized.
 163    * @param[in] image The image to display.
 164    * @return A handle to a newly allocated actor.
 165    */
 166   static ImageActor New(Image image);
 167
 168   /**
 169    * @brief Create a image actor object.
 170    *
 171    * When the image is loaded the actor's size will reset to the pixelArea,
 172    * unless a custom size was chosen, e.g. via Actor:SetSize().
 173    * @pre image must be initialized.
 174    * @param [in] image The image to display.
 175    * @param [in] pixelArea The area of the image to display.
 176    * This in pixels, relative to the top-left (0,0) of the image.
 177    * @return A handle to a newly allocated actor.
 178    */
 179   static ImageActor New(Image image, PixelArea pixelArea);
 180
 181   /**
 182    * @brief Downcast an Object handle to ImageActor.
 183    *
 184    *
 185    * If handle points to a ImageActor the downcast produces valid
 186    * handle. If not the returned handle is left uninitialized.
 187    *
 188    * @param[in] handle to An object
 189    * @return handle to a ImageActor or an uninitialized handle
 190    */
 191   static ImageActor DownCast( BaseHandle handle );
 192
 193   /**
 194    * @brief Destructor
 195    *
 196    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 197    */
 198   ~ImageActor();
 199
 200   /**
 201    * @brief Copy constructor
 202    *
 203    * @param [in] copy The actor to copy.
 204    */
 205   ImageActor(const ImageActor& copy);
 206
 207   /**
 208    * @brief Assignment operator
 209    *
 210    * @param [in] rhs The actor to copy.
 211    */
 212   ImageActor& operator=(const ImageActor& rhs);
 213
 214   /**
 215    * @brief This method is defined to allow assignment of the NULL value,
 216    * and will throw an exception if passed any other value.
 217    *
 218    * Assigning to NULL is an alias for Reset().
 219    * @param [in] rhs  A NULL pointer
 220    * @return A reference to this handle
 221    */
 222   ImageActor& operator=(BaseHandle::NullType* rhs);
 223
 224   /**
 225    * @brief Set the image rendered by the actor.
 226    *
 227    * When the image is loaded the actor's size will be reset to the image size,
 228    * unless a custom size was chosen, e.g. via Actor:SetSize() or a pixel area
 229    * was set.
 230    * @note The old image will continue to be displayed until the given image has loaded.
 231    * @pre image must be initialized.
 232    * @param [in] image The image to display.
 233    */
 234   void SetImage(Image image);
 235
 236   /**
 237    * @brief Retrieve the image rendered by the actor's attachment.
 238    *
 239    * @return The image.
 240    */
 241   Image GetImage();
 242
 243   /**
 244    * @brief Tell the image actor to use the natural size of the current image
 245    * or future images.
 246    *
 247    * Calling SetSize on this actor or animating the size of the actor
 248    * overrides this behaviour.
 249    *
 250    * @post The image actor uses the natural image size after an image
 251    * has been loaded.
 252    * @note Actor::SetSizeSignal() will be triggered if there is a current image.
 253    */
 254   void SetToNaturalSize();
 255
 256   /**
 257    * @brief Set a region of the image to display, in pixels.
 258    *
 259    * When the image is loaded the actor's size will be reset to the pixelArea,
 260    * unless a custom size was chosen, e.g. via Actor:SetSize().
 261    * Note! PixelArea should be inside the image data size. It gets clamped by GL
 262    * @pre image must be initialized.
 263    * @param [in] pixelArea The area of the image to display.
 264    * This in pixels, relative to the top-left (0,0) of the image.
 265    */
 266   void SetPixelArea(const PixelArea& pixelArea);
 267
 268   /**
 269    * @brief Retrieve the region of the image to display, in pixels.
 270    *
 271    * @pre image must be initialized.
 272    * @return The pixel area, or a default-constructed area if none was set.
 273    */
 274   PixelArea GetPixelArea() const;
 275
 276   /**
 277    * @brief Query whether a pixel area has been set.
 278    *
 279    * @pre image must be initialized.
 280    * @return True if a pixel area has been set.
 281    */
 282   bool IsPixelAreaSet() const;
 283
 284   /**
 285    * @brief Remove any pixel areas specified with SetPixelArea; the entire image will be displayed.
 286    *
 287    * The actor size will change to that of the Image unless a custom size was set, e.g. via
 288    * Actor::SetSize().
 289    * @pre image must be initialized.
 290    */
 291   void ClearPixelArea();
 292
 293   /**
 294    * @brief Set how the image is rendered; the default is STYLE_QUAD.
 295    *
 296    * @pre image must be initialized.
 297    * @param [in] style The new style.
 298    */
 299   void SetStyle(Style style);
 300
 301   /**
 302    * @brief Query how the image is rendered.
 303    *
 304    * @pre image must be initialized.
 305    * @return The rendering style.
 306    */
 307   Style GetStyle() const;
 308
 309   /**
 310    * @brief Set the border used with STYLE_NINE_PATCH.
 311    *
 312    * The values are in pixels from the left, top, right, and bottom of the image respectively.
 313    * i.e. SetNinePatchBorder( Vector4(1,2,3,4) ) sets the left-border to 1, top-border to 2, right-border to 3, and bottom-border to 4 pixels.
 314    * @param [in] border The new nine-patch border.
 315    */
 316   void SetNinePatchBorder(const Vector4& border);
 317
 318   /**
 319    * @brief Retrieve the border used with STYLE_NINE_PATCH.
 320    *
 321    * @return The nine-patch border.
 322    */
 323   Vector4 GetNinePatchBorder() const;
 324
 325   /**
 326    * @brief Set whether the image should gradually fade in when first rendered.
 327    *
 328    * @pre image must be initialized.
 329    * @param [in] enableFade True if the image should fade in.
 330    */
 331   void SetFadeIn(bool enableFade);
 332
 333   /**
 334    * @brief Query whether the image will gradually fade in when first rendered.
 335    *
 336    * @pre image must be initialized.
 337    * @return True if the image will fade in.
 338    */
 339   bool GetFadeIn() const;
 340
 341   /**
 342    * @brief Set the duration of the fade-in effect; the default is 1 second.
 343    *
 344    * @pre image must be initialized.
 345    * @param [in] durationSeconds The duration in seconds.
 346    */
 347   void SetFadeInDuration(float durationSeconds);
 348
 349   /**
 350    * @brief Retrieve the duration of the fade-in effect.
 351    *
 352    * @pre image must be initialized.
 353    * @return The duration in seconds.
 354    */
 355   float GetFadeInDuration() const;
 356
 357   /**
 358    * @brief Retrieve the size of the displayed image within the image actor.
 359    *
 360    * The size of the image may be different to that of the image actor
 361    * size depending on the geometry scaling used.
 362    * @pre image must be initialized.
 363    * @return The actual size of the image shown.
 364    * @note If a pixel area is set then this returns the size of the pixel area shown.
 365    */
 366   Vector2 GetCurrentImageSize() const;
 367
 368 public: // Not intended for application developers
 369
 370   explicit DALI_INTERNAL ImageActor(Internal::ImageActor*);
 371 };
 372
 373 } // namespace Dali
 374
 375 #endif // __DALI_IMAGE_ACTOR_H__