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