1 #ifndef __DALI_IMAGE_ACTOR_H__
2 #define __DALI_IMAGE_ACTOR_H__
5 * Copyright (c) 2014 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
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>
29 namespace Dali DALI_IMPORT_API
32 namespace Internal DALI_INTERNAL
38 * @brief An actor for displaying images.
40 * Allows the developer to add an actor to stage which displays the content of an Image object.
42 * By default CullFaceMode is set to CullNone to enable the ImageActor to be viewed from all angles.
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.
49 * Such a set size can be changed back to the image's size by calling SetToNaturalSize().
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.
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.
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.
61 class DALI_IMPORT_API ImageActor : public RenderableActor
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":...}
74 * @brief Style determines how the Image is rendered.
79 * 0---------2 0-----------------2
83 * | / | SCALE (X) | / |
84 * | / | --------> | / |
89 * 1---------3 1-----------------3
91 * Image is rendered as a textured rectangle. The texture
92 * is scaled uniformly as the quad is resized.
96 * |---|---------------|---| |---|-----------------------------|---|
97 * | 1 | 2 | 3 | | 1 | 2 | 3 |
98 * |---|---------------|---| |---|-----------------------------|---|
101 * | 4 | 5 | 6 | SCALE | | | |
102 * | | | | ----> | | | |
103 * | | | | | 4 | 5 | 6 |
104 * |-------------------|---| | | | |
105 * | 7 | 8 | 9 | | | | |
106 * |---|---------------|---| | | | |
107 * |---------------------------------|---|
109 * |---|-----------------------------|---|
112 * Image is rendered as a textured rectangle. The texture
113 * is scaled differently over each of the 9 sections.
115 * Visualise a Picture Frame:
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.
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.
133 STYLE_QUAD, ///< As a simple quad.
134 STYLE_NINE_PATCH ///< As a nine-patch.
138 * @brief Pixel area is relative to the top-left (0,0) of the image.
140 typedef Rect<int> PixelArea;
143 * @brief Create an uninitialized ImageActor handle.
145 * This can be initialized with ImageActor::New(...)
146 * Calling member functions with an uninitialized Dali::Object is not allowed.
151 * @brief Create an empty image actor object.
153 * @return A handle to a newly allocated actor.
155 static ImageActor New();
158 * @brief Create a image actor object.
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.
166 static ImageActor New(Image image);
169 * @brief Create a image actor object.
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.
179 static ImageActor New(Image image, PixelArea pixelArea);
182 * @brief Downcast an Object handle to ImageActor.
185 * If handle points to a ImageActor the downcast produces valid
186 * handle. If not the returned handle is left uninitialized.
188 * @param[in] handle to An object
189 * @return handle to a ImageActor or an uninitialized handle
191 static ImageActor DownCast( BaseHandle handle );
196 * This is non-virtual since derived Handle types must not contain data or virtual methods.
201 * @brief Copy constructor
203 * @param [in] copy The actor to copy.
205 ImageActor(const ImageActor& copy);
208 * @brief Assignment operator
210 * @param [in] rhs The actor to copy.
212 ImageActor& operator=(const ImageActor& rhs);
215 * @brief This method is defined to allow assignment of the NULL value,
216 * and will throw an exception if passed any other value.
218 * Assigning to NULL is an alias for Reset().
219 * @param [in] rhs A NULL pointer
220 * @return A reference to this handle
222 ImageActor& operator=(BaseHandle::NullType* rhs);
225 * @brief Set the image rendered by the actor.
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
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.
234 void SetImage(Image image);
237 * @brief Retrieve the image rendered by the actor's attachment.
244 * @brief Tell the image actor to use the natural size of the current image
247 * Calling SetSize on this actor or animating the size of the actor
248 * overrides this behaviour.
250 * @post The image actor uses the natural image size after an image
252 * @note Actor::SetSizeSignal() will be triggered if there is a current image.
254 void SetToNaturalSize();
257 * @brief Set a region of the image to display, in pixels.
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.
266 void SetPixelArea(const PixelArea& pixelArea);
269 * @brief Retrieve the region of the image to display, in pixels.
271 * @pre image must be initialized.
272 * @return The pixel area, or a default-constructed area if none was set.
274 PixelArea GetPixelArea() const;
277 * @brief Query whether a pixel area has been set.
279 * @pre image must be initialized.
280 * @return True if a pixel area has been set.
282 bool IsPixelAreaSet() const;
285 * @brief Remove any pixel areas specified with SetPixelArea; the entire image will be displayed.
287 * The actor size will change to that of the Image unless a custom size was set, e.g. via
289 * @pre image must be initialized.
291 void ClearPixelArea();
294 * @brief Set how the image is rendered; the default is STYLE_QUAD.
296 * @pre image must be initialized.
297 * @param [in] style The new style.
299 void SetStyle(Style style);
302 * @brief Query how the image is rendered.
304 * @pre image must be initialized.
305 * @return The rendering style.
307 Style GetStyle() const;
310 * @brief Set the border used with STYLE_NINE_PATCH.
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.
316 void SetNinePatchBorder(const Vector4& border);
319 * @brief Retrieve the border used with STYLE_NINE_PATCH.
321 * @return The nine-patch border.
323 Vector4 GetNinePatchBorder() const;
326 * @brief Set whether the image should gradually fade in when first rendered.
328 * @pre image must be initialized.
329 * @param [in] enableFade True if the image should fade in.
331 void SetFadeIn(bool enableFade);
334 * @brief Query whether the image will gradually fade in when first rendered.
336 * @pre image must be initialized.
337 * @return True if the image will fade in.
339 bool GetFadeIn() const;
342 * @brief Set the duration of the fade-in effect; the default is 1 second.
344 * @pre image must be initialized.
345 * @param [in] durationSeconds The duration in seconds.
347 void SetFadeInDuration(float durationSeconds);
350 * @brief Retrieve the duration of the fade-in effect.
352 * @pre image must be initialized.
353 * @return The duration in seconds.
355 float GetFadeInDuration() const;
358 * @brief Retrieve the size of the displayed image within the image actor.
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.
366 Vector2 GetCurrentImageSize() const;
368 public: // Not intended for application developers
370 explicit DALI_INTERNAL ImageActor(Internal::ImageActor*);
375 #endif // __DALI_IMAGE_ACTOR_H__