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
  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   /**
  66    * @brief An enumeration of properties belonging to the ImageActor class.
  67    * Properties additional to RenderableActor.
  68    */
  69   struct Property
  70   {
  71     enum
  72     {
  73       PixelArea = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "pixel-area",  type RECTANGLE
  74       Style,                                                  ///< name "style",       type STRING
  75       Border,                                                 ///< name "border",      type VECTOR4
  76       Image,                                                  ///< name "image",       type MAP {"filename":"", "load-policy":...}
  77     };
  78   };
  79
  80   /**
  81    * @brief Style determines how the Image is rendered.
  82    *
  83    * @code
  84    * STYLE_QUAD:
  85    *
  86    *  0---------2           0-----------------2
  87    *  |        /|           |                /|
  88    *  |  A    / |           |      A       /  |
  89    *  |      /  |           |            /    |
  90    *  |     /   | SCALE (X) |          /      |
  91    *  |    /    | --------> |        /        |
  92    *  |   /     |           |      /          |
  93    *  |  /      |           |    /            |
  94    *  | /    B  |           |  /        B     |
  95    *  |/        |           |/                |
  96    *  1---------3           1-----------------3
  97    *
  98    * Image is rendered as a textured rectangle. The texture
  99    * is scaled uniformly as the quad is resized.
 100    *
 101    * STYLE_NINE_PATCH:
 102    *
 103    *  |---|---------------|---|       |---|-----------------------------|---|
 104    *  | 1 |       2       | 3 |       | 1 |              2              | 3 |
 105    *  |---|---------------|---|       |---|-----------------------------|---|
 106    *  |   |               |   |       |   |                             |   |
 107    *  |   |               |   |       |   |                             |   |
 108    *  | 4 |       5       | 6 | SCALE |   |                             |   |
 109    *  |   |               |   | ----> |   |                             |   |
 110    *  |   |               |   |       | 4 |              5              | 6 |
 111    *  |-------------------|---|       |   |                             |   |
 112    *  | 7 |       8       | 9 |       |   |                             |   |
 113    *  |---|---------------|---|       |   |                             |   |
 114    *                                  |---------------------------------|---|
 115    *                                  | 7 |              8              | 9 |
 116    *                                  |---|-----------------------------|---|
 117    *
 118    * Image is rendered as a textured rectangle. The texture
 119    * is scaled differently over each of the 9 sections.
 120    *
 121    * STYLE_NINE_PATCH_NO_CENTER:
 122    *
 123    * Image is rendered in the same way as STYLE_NINE_PATCH,
 124    * but the Center Section (5) is not rendered.
 125    * @endcode
 126    *
 127    * Visualise a Picture Frame:
 128    *
 129    * - Corner sections (1,3,7,9) are not scaled, regardless
 130    * of how big the Image is.
 131    * - Horizontal edge sections (2,8) are scaled only in the
 132    * X axis as the image increases in width.
 133    * - Vertical edge sections (4,6) are scaled only in the
 134    * Y axis as the image increases in height.
 135    * - Center section (5) is scaled in both X and Y axes as
 136    * the image increases in width and/or height.
 137    *
 138    * Note: If GRID hints are enabled (via a Shader that requires it),
 139    * the above geometry will be further subdivided into rectangles of
 140    * approx. 40x40 in size. STYLE_NINE_PATCH_NO_CENTER is not supported
 141    * yet when GRID hints are enabled.
 142    */
 143   enum Style
 144   {
 145     STYLE_QUAD,                 ///< As a simple quad.
 146     STYLE_NINE_PATCH,           ///< As a nine-patch.
 147     STYLE_NINE_PATCH_NO_CENTER  ///< As a nine-patch without center section being rendered.
 148   };
 149
 150   /**
 151    * @brief Pixel area is relative to the top-left (0,0) of the image.
 152    */
 153   typedef Rect<int> PixelArea;
 154
 155   /**
 156    * @brief Create an uninitialized ImageActor handle.
 157    *
 158    * This can be initialized with ImageActor::New(...)
 159    * Calling member functions with an uninitialized Dali::Object is not allowed.
 160    */
 161   ImageActor();
 162
 163   /**
 164    * @brief Create an empty image actor object.
 165    *
 166    * @return A handle to a newly allocated actor.
 167    */
 168   static ImageActor New();
 169
 170   /**
 171    * @brief Create a image actor object.
 172    *
 173    * The actor will take the image's natural size unless a custom size
 174    * is chosen, e.g. via Actor:SetSize().
 175    * If the handle is empty, ImageActor will display nothing
 176    * @pre ImageActor must be initialized.
 177    * @param[in] image The image to display.
 178    * @return A handle to a newly allocated actor.
 179    */
 180   static ImageActor New(Image image);
 181
 182   /**
 183    * @brief Create a image actor object.
 184    *
 185    * The actor will take the image's natural size unless a custom size
 186    * is chosen, e.g. via Actor:SetSize()
 187    * If the handle is empty, ImageActor will display nothing
 188    * @pre ImageActor must be initialized.
 189    * @param [in] image The image to display.
 190    * @param [in] pixelArea The area of the image to display.
 191    * This in pixels, relative to the top-left (0,0) of the image.
 192    * @return A handle to a newly allocated actor.
 193    */
 194   static ImageActor New(Image image, PixelArea pixelArea);
 195
 196   /**
 197    * @brief Downcast an Object handle to ImageActor.
 198    *
 199    *
 200    * If handle points to a ImageActor the downcast produces valid
 201    * handle. If not the returned handle is left uninitialized.
 202    *
 203    * @param[in] handle to An object
 204    * @return handle to a ImageActor or an uninitialized handle
 205    */
 206   static ImageActor DownCast( BaseHandle handle );
 207
 208   /**
 209    * @brief Destructor
 210    *
 211    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 212    */
 213   ~ImageActor();
 214
 215   /**
 216    * @brief Copy constructor
 217    *
 218    * @param [in] copy The actor to copy.
 219    */
 220   ImageActor(const ImageActor& copy);
 221
 222   /**
 223    * @brief Assignment operator
 224    *
 225    * @param [in] rhs The actor to copy.
 226    */
 227   ImageActor& operator=(const ImageActor& rhs);
 228
 229   /**
 230    * @brief Set the image rendered by the actor.
 231    * Set the image rendered by the actor.
 232    * If actor was already displaying a different image, the old image is dropped and actor may
 233    * temporarily display nothing. Setting an empty image (handle) causes the current image to be
 234    * dropped and actor displays nothing.
 235    * The actor will take the image's natural size unless a custom size
 236    * is chosen, e.g. via Actor:SetSize()
 237    *
 238    * @pre ImageActor must be initialized.
 239    * @param [in] image The image to display.
 240    */
 241   void SetImage(Image image);
 242
 243   /**
 244    * @brief Retrieve the image rendered by the actor.
 245    *
 246    * If no image is assigned, an empty handle is returned
 247    * @return The image.
 248    */
 249   Image GetImage();
 250
 251   /**
 252    * @brief Tell the image actor to use the natural size of the current image
 253    * or future images.
 254    *
 255    * Calling SetSize on this actor or animating the size of the actor
 256    * overrides this behaviour.
 257    *
 258    * @post The image actor uses the natural image size after an image
 259    * has been loaded.
 260    */
 261   void SetToNaturalSize();
 262
 263   /**
 264    * @brief Set a region of the image to display, in pixels.
 265    *
 266    * When the image is loaded the actor's size will be reset to the pixelArea,
 267    * unless a custom size was chosen, e.g. via Actor:SetSize().
 268    * Note! PixelArea should be inside the image data size. It gets clamped by GL
 269    * @pre image must be initialized.
 270    * @param [in] pixelArea The area of the image to display.
 271    * This in pixels, relative to the top-left (0,0) of the image.
 272    */
 273   void SetPixelArea(const PixelArea& pixelArea);
 274
 275   /**
 276    * @brief Retrieve the region of the image to display, in pixels.
 277    *
 278    * @pre image must be initialized.
 279    * @return The pixel area, or a default-constructed area if none was set.
 280    */
 281   PixelArea GetPixelArea() const;
 282
 283   /**
 284    * @brief Query whether a pixel area has been set.
 285    *
 286    * @pre image must be initialized.
 287    * @return True if a pixel area has been set.
 288    */
 289   bool IsPixelAreaSet() const;
 290
 291   /**
 292    * @brief Remove any pixel areas specified with SetPixelArea; the entire image will be displayed.
 293    *
 294    * The actor size will change to that of the Image unless a custom size was set, e.g. via
 295    * Actor::SetSize().
 296    * @pre image must be initialized.
 297    */
 298   void ClearPixelArea();
 299
 300   /**
 301    * @brief Set how the image is rendered; the default is STYLE_QUAD.
 302    *
 303    * @pre image must be initialized.
 304    * @param [in] style The new style.
 305    */
 306   void SetStyle(Style style);
 307
 308   /**
 309    * @brief Query how the image is rendered.
 310    *
 311    * @pre image must be initialized.
 312    * @return The rendering style.
 313    */
 314   Style GetStyle() const;
 315
 316   /**
 317    * @brief Set the border used with STYLE_NINE_PATCH.
 318    *
 319    * The values are in pixels from the left, top, right, and bottom of the image respectively.
 320    * 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.
 321    * @param [in] border The new nine-patch border.
 322    */
 323   void SetNinePatchBorder(const Vector4& border);
 324
 325   /**
 326    * @brief Retrieve the border used with STYLE_NINE_PATCH.
 327    *
 328    * @return The nine-patch border.
 329    */
 330   Vector4 GetNinePatchBorder() const;
 331
 332 public: // Not intended for application developers
 333
 334   explicit DALI_INTERNAL ImageActor(Internal::ImageActor*);
 335 };
 336
 337 } // namespace Dali
 338
 339 #endif // __DALI_IMAGE_ACTOR_H__