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