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