dali/internal/event/actors/image-actor-impl.h

   1 #ifndef __DALI_INTERNAL_IMAGE_ACTOR_H__
   2 #define __DALI_INTERNAL_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 // INTERNAL INCLUDES
  21 #include <dali/public-api/object/ref-object.h>
  22 #include <dali/public-api/actors/image-actor.h>
  23 #include <dali/internal/event/actors/actor-declarations.h>
  24 #include <dali/internal/event/actors/renderable-actor-impl.h>
  25 #include <dali/internal/event/actor-attachments/image-attachment-impl.h>
  26 #include <dali/internal/event/animation/animation-impl.h>
  27
  28 namespace Dali
  29 {
  30
  31 namespace Internal
  32 {
  33
  34 class Image;
  35
  36 /**
  37  * An actor which displays an Image object.
  38  *
  39  * This handles image fade-in if required, waiting for the image to load.
  40  *
  41  * If a new image is set on the actor, then this ensures that the old image
  42  * is displayed until the new image is ready to render to prevent flashing
  43  * to the actor color. This will also happen if the image is reloaded.
  44  *
  45  * This is achieved by using two connector objects to Image: mImageNext and
  46  * mImageAttachment's member object. The first one points to the Image object that is going to
  47  * be displayed next, the second one to the Image that is currently being displayed.
  48  */
  49 class ImageActor : public RenderableActor
  50 {
  51 public:
  52
  53   typedef Dali::ImageActor::Style Style;
  54   typedef Dali::ImageActor::PixelArea PixelArea;
  55
  56   /**
  57    * Create an initialised image actor.
  58    * When the image is loaded the actors size will reset to the image size,
  59    * unless a custom size chosen via Actor:SetSize().
  60    * @param  [in] image A pointer to the image object to display or NULL not to display anything.
  61    * @return A smart-pointer to a newly allocated image actor.
  62    */
  63   static ImageActorPtr New( Image* image );
  64
  65   /**
  66    * Create an initialised image actor
  67    * When the image is loaded the actors size will reset to the image size,
  68    * unless a custom size chosen via Actor:SetSize().
  69    * @param [in] image A pointer to the image object to display or NULL not to display anything.
  70    * @param [in] pixelArea The area of the image to display.
  71    * This in pixels, relative to the top-left (0,0) of the image.
  72    * @return A smart-pointer to a newly allocated image actor.
  73    */
  74   static ImageActorPtr New( Image* image, const PixelArea& pixelArea );
  75
  76   /**
  77    * @copydoc Dali::Internal::Actor::OnInitialize
  78    */
  79   void OnInitialize() ;
  80
  81   /**
  82    * Set the image rendered by the actor's attachment.
  83    * When the image is loaded the actors size will be reset to the image size,
  84    * unless a custom size is chosen via Actor:SetSize().
  85    * The old image will continue to be displayed until the new image has loaded
  86    * @param [in] image A pointer to the image to display or NULL not to display anything.
  87    */
  88   void SetImage( Image* image );
  89
  90   /**
  91    * Retrieve the image rendered by the actor's attachment.
  92    * @return The image (uninitialized Image object in case the ImageActor does not display anything).
  93    */
  94   Dali::Image GetImage();
  95
  96   /**
  97    * @copydoc Dali::ImageActor::SetToNaturalSize()
  98    */
  99   void SetToNaturalSize();
 100
 101   /**
 102    * Set a region of the image to display, in pixels.
 103    * @param [in] pixelArea The area of the image to display.
 104    * This in pixels, relative to the top-left (0,0) of the image.
 105    */
 106   void SetPixelArea( const PixelArea& pixelArea );
 107
 108   /**
 109    * Retrieve the region of the image to display, in pixels.
 110    * @return The pixel area, or a default-constructed area if none was set.
 111    */
 112   const PixelArea& GetPixelArea() const;
 113
 114   /**
 115    * Query whether a pixel area has been set.
 116    * @return True if a pixel area has been set.
 117    */
 118   bool IsPixelAreaSet() const;
 119
 120   /**
 121    * Remove any pixel areas specified with SetPixelArea; the entire image will be displayed.
 122    */
 123   void ClearPixelArea();
 124
 125   /**
 126    * Set how the image is rendered; the default is STYLE_QUAD.
 127    * @param [in] style The new style.
 128    */
 129   void SetStyle( Style style );
 130
 131   /**
 132    * Query how the image is rendered.
 133    * @return The rendering style.
 134    */
 135   Style GetStyle() const;
 136
 137   /**
 138    * @copydoc Dali::ImageActor::SetNinePatchBorder
 139    */
 140   void SetNinePatchBorder( const Vector4& border, bool inPixels = false );
 141
 142   /**
 143    * @copydoc Dali::ImageActor::GetNinePatchBorder
 144    */
 145   Vector4 GetNinePatchBorder() const;
 146
 147   /**
 148    * Set whether the image should gradually fade in when first rendered.
 149    * @param [in] enableFade True if the image should fade in.
 150    */
 151   void SetFadeIn(bool enableFade);
 152
 153   /**
 154    * Query whether the image will gradually fade in when first rendered.
 155    * @return True if the image will fade in.
 156    */
 157   bool GetFadeIn() const;
 158
 159   /**
 160    * Set the duration of the fade-in effect; the default is 1 second.
 161    * @param [in] durationSeconds The duration in seconds.
 162    */
 163   void SetFadeInDuration( float durationSeconds );
 164
 165   /**
 166    * Retrieve the duration of the fade-in effect.
 167    * @return The duration in seconds.
 168    */
 169   float GetFadeInDuration() const;
 170
 171   /**
 172    * Retrieve the attachment which renders the image.
 173    * @return The attachment.
 174    */
 175   ImageAttachment& GetImageAttachment();
 176
 177   /**
 178    * @copydoc Dali::ImageActor::GetCurrentImageSize
 179    */
 180   Vector2 GetCurrentImageSize() const;
 181
 182 public: // Default property extensions from ProxyObject
 183
 184   /**
 185    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyCount()
 186    */
 187   virtual unsigned int GetDefaultPropertyCount() const;
 188
 189   /**
 190    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyIndices()
 191    */
 192   virtual void GetDefaultPropertyIndices( Property::IndexContainer& indices ) const;
 193
 194   /**
 195    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyName()
 196    */
 197   virtual const std::string& GetDefaultPropertyName(Property::Index index) const;
 198
 199   /**
 200    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyIndex()
 201    */
 202   virtual Property::Index GetDefaultPropertyIndex(const std::string& name) const;
 203
 204   /**
 205    * @copydoc Dali::Internal::ProxyObject::IsDefaultPropertyWritable()
 206    */
 207   virtual bool IsDefaultPropertyWritable(Property::Index index) const;
 208
 209   /**
 210    * @copydoc Dali::Internal::ProxyObject::IsDefaultPropertyAnimatable()
 211    */
 212   virtual bool IsDefaultPropertyAnimatable(Property::Index index) const;
 213
 214   /**
 215    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyType()
 216    */
 217   virtual Property::Type GetDefaultPropertyType(Property::Index index) const;
 218
 219   /**
 220    * @copydoc Dali::Internal::ProxyObject::SetDefaultProperty()
 221    */
 222   virtual void SetDefaultProperty(Property::Index index, const Property::Value& propertyValue);
 223
 224   /**
 225    * @copydoc Dali::Internal::ProxyObject::GetDefaultProperty()
 226    */
 227   virtual Property::Value GetDefaultProperty( Property::Index index ) const;
 228
 229 private: // From RenderableActor
 230
 231   /**
 232    * @copydoc RenderableActor::GetRenderableAttachment
 233    */
 234   virtual RenderableAttachment& GetRenderableAttachment() const;
 235
 236 protected:
 237
 238   /**
 239    * Protected constructor; see also ImageActor::New()
 240    */
 241   ImageActor();
 242
 243   /**
 244    * A reference counted object may only be deleted by calling Unreference()
 245    */
 246   virtual ~ImageActor();
 247
 248 private:
 249
 250   // Helper for overloads of SetImage().
 251   void OnImageSet( Image& image );
 252
 253   // Helper to set the actor to the image's natural size
 254   void SetNaturalSize( Image& image );
 255
 256
 257   /**
 258    * From Actor.
 259    * This is called after SizeSet() has been called.
 260    */
 261   virtual void OnSizeSet( const Vector3& targetSize );
 262
 263   /**
 264    * @copydoc Actor::OnSizeAnimation( Animation& animation, const Vector3& targetSize )
 265    */
 266   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize);
 267
 268   /**
 269    * From Actor; used to trigger fade-in animations.
 270    */
 271   virtual void OnStageConnectionInternal();
 272
 273   /**
 274    * From Actor; used to notify Image.
 275    */
 276   virtual void OnStageDisconnectionInternal();
 277
 278   /**
 279    * Helper for when the image loads.
 280    * @param[in] image The newly (re)loaded image.
 281    */
 282   void ImageLoaded( Dali::Image image );
 283
 284   /**
 285    * Helper to start fade-in animations.
 286    */
 287   void FadeIn();
 288
 289 private:
 290
 291   ImageAttachmentPtr mImageAttachment; ///< Used to display the image (holds a pointer to currently showed Image)
 292   ImageConnector     mImageNext;       ///< Manages the Image this ImageActor will show (used when changing displayed image)
 293
 294   // flags, compressed to bitfield (uses only 4 bytes)
 295   bool mUsingNaturalSize:1; ///< True only when the actor is using
 296   bool mInternalSetSize:1;  ///< True whilst setting size internally, false at all other times
 297   bool mFadeIn:1;           ///< True if fade in animation is enabled
 298   bool mFadeInitial:1;      ///< True if fading in for the first time
 299
 300   SlotDelegate<ImageActor> mLoadedConnection; ///< Tracks the connection to the "loading finished" signal
 301
 302   // For fade-in animations
 303   float        mFadeInDuration;  ///< Length of animation
 304
 305   static bool mFirstInstance ;
 306   static DefaultPropertyLookup* mDefaultImageActorPropertyLookup; ///< Default properties
 307
 308 };
 309
 310 } // namespace Internal
 311
 312 // Helpers for public-api forwarding methods
 313
 314 inline Internal::ImageActor& GetImplementation(Dali::ImageActor& image)
 315 {
 316   DALI_ASSERT_ALWAYS(image && "Image handle is empty");
 317
 318   BaseObject& handle = image.GetBaseObject();
 319
 320   return static_cast<Internal::ImageActor&>(handle);
 321 }
 322
 323 inline const Internal::ImageActor& GetImplementation(const Dali::ImageActor& image)
 324 {
 325   DALI_ASSERT_ALWAYS(image && "Image handle is empty");
 326
 327   const BaseObject& handle = image.GetBaseObject();
 328
 329   return static_cast<const Internal::ImageActor&>(handle);
 330 }
 331
 332 } // namespace Dali
 333
 334 #endif // __DALI_INTERNAL_IMAGE_ACTOR_H__