1 #ifndef __DALI_INTERNAL_IMAGE_ACTOR_H__
2 #define __DALI_INTERNAL_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.
22 #include <dali/public-api/object/ref-object.h>
23 #include <dali/public-api/actors/image-actor.h>
24 #include <dali/internal/event/actors/actor-declarations.h>
25 #include <dali/internal/event/actors/renderable-actor-impl.h>
26 #include <dali/internal/event/actor-attachments/image-attachment-impl.h>
27 #include <dali/internal/event/animation/animation-impl.h>
28 #include <dali/internal/event/images/nine-patch-image-impl.h>
39 * An actor which displays an Image object.
41 * This handles image fade-in if required, waiting for the image to load.
43 * If a new image is set on the actor, then this ensures that the old image
44 * is displayed until the new image is ready to render to prevent flashing
45 * to the actor color. This will also happen if the image is reloaded.
47 * This is achieved by using two connector objects to Image: mImageNext and
48 * mImageAttachment's member object. The first one points to the Image object that is going to
49 * be displayed next, the second one to the Image that is currently being displayed.
51 class ImageActor : public RenderableActor
55 typedef Dali::ImageActor::Style Style;
56 typedef Dali::ImageActor::PixelArea PixelArea;
59 * @brief Create an initialised image actor.
60 * When the image is loaded the actors size will reset to the image size,
61 * unless a custom size chosen via Actor:SetSize().
62 * @param[in] image A pointer to the image object to display or NULL not to display anything.
63 * @return A smart-pointer to a newly allocated image actor.
65 static ImageActorPtr New( Image* image );
68 * @brief Create an initialised image actor.
69 * When the image is loaded the actors size will reset to the image size,
70 * unless a custom size chosen via Actor:SetSize().
71 * @param [in] image A pointer to the image object to display or NULL not to display anything.
72 * @param [in] pixelArea The area of the image to display.
73 * This in pixels, relative to the top-left (0,0) of the image.
74 * @return A smart-pointer to a newly allocated image actor.
76 static ImageActorPtr New( Image* image, const PixelArea& pixelArea );
79 * @copydoc Dali::Internal::Actor::OnInitialize
84 * Set the image rendered by the actor's attachment.
85 * When the image is loaded the actors size will be reset to the image size,
86 * unless a custom size is chosen via Actor:SetSize().
87 * The old image will continue to be displayed until the new image has loaded
88 * @param [in] image A pointer to the image to display or NULL not to display anything.
90 void SetImage( Image* image );
93 * Retrieve the image rendered by the actor's attachment.
94 * @return The image (uninitialized Image object in case the ImageActor does not display anything).
96 Dali::Image GetImage();
99 * @copydoc Dali::ImageActor::SetToNaturalSize()
101 void SetToNaturalSize();
104 * Set a region of the image to display, in pixels.
105 * @param [in] pixelArea The area of the image to display.
106 * This in pixels, relative to the top-left (0,0) of the image.
108 void SetPixelArea( const PixelArea& pixelArea );
111 * Retrieve the region of the image to display, in pixels.
112 * @return The pixel area, or a default-constructed area if none was set.
114 const PixelArea& GetPixelArea() const;
117 * Query whether a pixel area has been set.
118 * @return True if a pixel area has been set.
120 bool IsPixelAreaSet() const;
123 * Remove any pixel areas specified with SetPixelArea; the entire image will be displayed.
125 void ClearPixelArea();
128 * Set how the image is rendered; the default is STYLE_QUAD.
129 * @param [in] style The new style.
131 void SetStyle( Style style );
134 * Query how the image is rendered.
135 * @return The rendering style.
137 Style GetStyle() const;
140 * @copydoc Dali::ImageActor::SetNinePatchBorder
142 void SetNinePatchBorder( const Vector4& border, bool inPixels = false );
145 * @copydoc Dali::ImageActor::GetNinePatchBorder
147 Vector4 GetNinePatchBorder() const;
150 * Set whether the image should gradually fade in when first rendered.
151 * @param [in] enableFade True if the image should fade in.
153 void SetFadeIn(bool enableFade);
156 * Query whether the image will gradually fade in when first rendered.
157 * @return True if the image will fade in.
159 bool GetFadeIn() const;
162 * Set the duration of the fade-in effect; the default is 1 second.
163 * @param [in] durationSeconds The duration in seconds.
165 void SetFadeInDuration( float durationSeconds );
168 * Retrieve the duration of the fade-in effect.
169 * @return The duration in seconds.
171 float GetFadeInDuration() const;
174 * Retrieve the attachment which renders the image.
175 * @return The attachment.
177 ImageAttachment& GetImageAttachment();
180 * @copydoc Dali::ImageActor::GetCurrentImageSize
182 Vector2 GetCurrentImageSize() const;
184 public: // Default property extensions from ProxyObject
187 * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyCount()
189 virtual unsigned int GetDefaultPropertyCount() const;
192 * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyIndices()
194 virtual void GetDefaultPropertyIndices( Property::IndexContainer& indices ) const;
197 * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyName()
199 virtual const std::string& GetDefaultPropertyName(Property::Index index) const;
202 * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyIndex()
204 virtual Property::Index GetDefaultPropertyIndex(const std::string& name) const;
207 * @copydoc Dali::Internal::ProxyObject::IsDefaultPropertyWritable()
209 virtual bool IsDefaultPropertyWritable(Property::Index index) const;
212 * @copydoc Dali::Internal::ProxyObject::IsDefaultPropertyAnimatable()
214 virtual bool IsDefaultPropertyAnimatable(Property::Index index) const;
217 * @copydoc Dali::Internal::ProxyObject::IsDefaultPropertyAConstraintInput()
219 virtual bool IsDefaultPropertyAConstraintInput( Property::Index index ) const;
222 * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyType()
224 virtual Property::Type GetDefaultPropertyType(Property::Index index) const;
227 * @copydoc Dali::Internal::ProxyObject::SetDefaultProperty()
229 virtual void SetDefaultProperty(Property::Index index, const Property::Value& propertyValue);
232 * @copydoc Dali::Internal::ProxyObject::GetDefaultProperty()
234 virtual Property::Value GetDefaultProperty( Property::Index index ) const;
236 private: // From RenderableActor
239 * @copydoc RenderableActor::GetRenderableAttachment
241 virtual RenderableAttachment& GetRenderableAttachment() const;
246 * Protected constructor; see also ImageActor::New()
251 * A reference counted object may only be deleted by calling Unreference()
253 virtual ~ImageActor();
257 // Helper for overloads of SetImage().
258 void OnImageSet( Image& image );
260 // Helper to set the actor to the image's natural size
261 void SetNaturalSize( Image& image );
266 * This is called after SizeSet() has been called.
268 virtual void OnSizeSet( const Vector3& targetSize );
271 * @copydoc Actor::OnSizeAnimation( Animation& animation, const Vector3& targetSize )
273 virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize);
276 * From Actor; used to trigger fade-in animations.
278 virtual void OnStageConnectionInternal();
281 * From Actor; used to notify Image.
283 virtual void OnStageDisconnectionInternal();
286 * Helper for when the image loads.
287 * @param[in] image The newly (re)loaded image.
289 void ImageLoaded( Dali::Image image );
292 * Helper to start fade-in animations.
298 ImageAttachmentPtr mImageAttachment; ///< Used to display the image (holds a pointer to currently showed Image)
299 ImageConnector mImageNext; ///< Manages the Image this ImageActor will show (used when changing displayed image)
301 // flags, compressed to bitfield (uses only 4 bytes)
302 bool mUsingNaturalSize:1; ///< True only when the actor is using
303 bool mInternalSetSize:1; ///< True whilst setting size internally, false at all other times
304 bool mFadeIn:1; ///< True if fade in animation is enabled
305 bool mFadeInitial:1; ///< True if fading in for the first time
307 SlotDelegate<ImageActor> mLoadedConnection; ///< Tracks the connection to the "loading finished" signal
309 // For fade-in animations
310 float mFadeInDuration; ///< Length of animation
312 static bool mFirstInstance ;
313 static DefaultPropertyLookup* mDefaultImageActorPropertyLookup; ///< Default properties
317 } // namespace Internal
319 // Helpers for public-api forwarding methods
321 inline Internal::ImageActor& GetImplementation(Dali::ImageActor& image)
323 DALI_ASSERT_ALWAYS(image && "Image handle is empty");
325 BaseObject& handle = image.GetBaseObject();
327 return static_cast<Internal::ImageActor&>(handle);
330 inline const Internal::ImageActor& GetImplementation(const Dali::ImageActor& image)
332 DALI_ASSERT_ALWAYS(image && "Image handle is empty");
334 const BaseObject& handle = image.GetBaseObject();
336 return static_cast<const Internal::ImageActor&>(handle);
341 #endif // __DALI_INTERNAL_IMAGE_ACTOR_H__