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::GetDefaultPropertyName()
 191    */
 192   virtual const std::string& GetDefaultPropertyName(Property::Index index) const;
 193
 194   /**
 195    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyIndex()
 196    */
 197   virtual Property::Index GetDefaultPropertyIndex(const std::string& name) const;
 198
 199   /**
 200    * @copydoc Dali::Internal::ProxyObject::IsDefaultPropertyWritable()
 201    */
 202   virtual bool IsDefaultPropertyWritable(Property::Index index) const;
 203
 204   /**
 205    * @copydoc Dali::Internal::ProxyObject::IsDefaultPropertyAnimatable()
 206    */
 207   virtual bool IsDefaultPropertyAnimatable(Property::Index index) const;
 208
 209   /**
 210    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyType()
 211    */
 212   virtual Property::Type GetDefaultPropertyType(Property::Index index) const;
 213
 214   /**
 215    * @copydoc Dali::Internal::ProxyObject::SetDefaultProperty()
 216    */
 217   virtual void SetDefaultProperty(Property::Index index, const Property::Value& propertyValue);
 218
 219   /**
 220    * @copydoc Dali::Internal::ProxyObject::GetDefaultProperty()
 221    */
 222   virtual Property::Value GetDefaultProperty( Property::Index index ) const;
 223
 224 private: // From RenderableActor
 225
 226   /**
 227    * @copydoc RenderableActor::GetRenderableAttachment
 228    */
 229   virtual RenderableAttachment& GetRenderableAttachment() const;
 230
 231 protected:
 232
 233   /**
 234    * Protected constructor; see also ImageActor::New()
 235    */
 236   ImageActor();
 237
 238   /**
 239    * A reference counted object may only be deleted by calling Unreference()
 240    */
 241   virtual ~ImageActor();
 242
 243 private:
 244
 245   // Helper for overloads of SetImage().
 246   void OnImageSet( Image& image );
 247
 248   // Helper to set the actor to the image's natural size
 249   void SetNaturalSize( Image& image );
 250
 251
 252   /**
 253    * From Actor.
 254    * This is called after SizeSet() has been called.
 255    */
 256   virtual void OnSizeSet( const Vector3& targetSize );
 257
 258   /**
 259    * @copydoc Actor::OnSizeAnimation( Animation& animation, const Vector3& targetSize )
 260    */
 261   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize);
 262
 263   /**
 264    * From Actor; used to trigger fade-in animations.
 265    */
 266   virtual void OnStageConnectionInternal();
 267
 268   /**
 269    * From Actor; used to notify Image.
 270    */
 271   virtual void OnStageDisconnectionInternal();
 272
 273   /**
 274    * Helper for when the image loads.
 275    * @param[in] image The newly (re)loaded image.
 276    */
 277   void ImageLoaded( Dali::Image image );
 278
 279   /**
 280    * Helper to start fade-in animations.
 281    */
 282   void FadeIn();
 283
 284 private:
 285
 286   ImageAttachmentPtr mImageAttachment; ///< Used to display the image (holds a pointer to currently showed Image)
 287   ImageConnector     mImageNext;       ///< Manages the Image this ImageActor will show (used when changing displayed image)
 288
 289   // flags, compressed to bitfield (uses only 4 bytes)
 290   bool mUsingNaturalSize:1; ///< True only when the actor is using
 291   bool mInternalSetSize:1;  ///< True whilst setting size internally, false at all other times
 292   bool mFadeIn:1;           ///< True if fade in animation is enabled
 293   bool mFadeInitial:1;      ///< True if fading in for the first time
 294
 295   SlotDelegate<ImageActor> mLoadedConnection; ///< Tracks the connection to the "loading finished" signal
 296
 297   // For fade-in animations
 298   float        mFadeInDuration;  ///< Length of animation
 299
 300   static bool mFirstInstance ;
 301   static DefaultPropertyLookup* mDefaultImageActorPropertyLookup; ///< Default properties
 302
 303 };
 304
 305 } // namespace Internal
 306
 307 // Helpers for public-api forwarding methods
 308
 309 inline Internal::ImageActor& GetImplementation(Dali::ImageActor& image)
 310 {
 311   DALI_ASSERT_ALWAYS(image && "Image handle is empty");
 312
 313   BaseObject& handle = image.GetBaseObject();
 314
 315   return static_cast<Internal::ImageActor&>(handle);
 316 }
 317
 318 inline const Internal::ImageActor& GetImplementation(const Dali::ImageActor& image)
 319 {
 320   DALI_ASSERT_ALWAYS(image && "Image handle is empty");
 321
 322   const BaseObject& handle = image.GetBaseObject();
 323
 324   return static_cast<const Internal::ImageActor&>(handle);
 325 }
 326
 327 } // namespace Dali
 328
 329 #endif // __DALI_INTERNAL_IMAGE_ACTOR_H__