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 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    * Set a region of the image to display, in pixels.
  98    * @param [in] pixelArea The area of the image to display.
  99    * This in pixels, relative to the top-left (0,0) of the image.
 100    */
 101   void SetPixelArea( const PixelArea& pixelArea );
 102
 103   /**
 104    * Retrieve the region of the image to display, in pixels.
 105    * @return The pixel area, or a default-constructed area if none was set.
 106    */
 107   const PixelArea& GetPixelArea() const;
 108
 109   /**
 110    * Query whether a pixel area has been set.
 111    * @return True if a pixel area has been set.
 112    */
 113   bool IsPixelAreaSet() const;
 114
 115   /**
 116    * Remove any pixel areas specified with SetPixelArea; the entire image will be displayed.
 117    */
 118   void ClearPixelArea();
 119
 120   /**
 121    * Set how the image is rendered; the default is STYLE_QUAD.
 122    * @param [in] style The new style.
 123    */
 124   void SetStyle( Style style );
 125
 126   /**
 127    * Query how the image is rendered.
 128    * @return The rendering style.
 129    */
 130   Style GetStyle() const;
 131
 132   /**
 133    * @copydoc Dali::ImageActor::SetNinePatchBorder
 134    */
 135   void SetNinePatchBorder( const Vector4& border, bool inPixels = false );
 136
 137   /**
 138    * @copydoc Dali::ImageActor::GetNinePatchBorder
 139    */
 140   Vector4 GetNinePatchBorder() const;
 141
 142   /**
 143    * Set whether the image should gradually fade in when first rendered.
 144    * @param [in] enableFade True if the image should fade in.
 145    */
 146   void SetFadeIn(bool enableFade);
 147
 148   /**
 149    * Query whether the image will gradually fade in when first rendered.
 150    * @return True if the image will fade in.
 151    */
 152   bool GetFadeIn() const;
 153
 154   /**
 155    * Set the duration of the fade-in effect; the default is 1 second.
 156    * @param [in] durationSeconds The duration in seconds.
 157    */
 158   void SetFadeInDuration( float durationSeconds );
 159
 160   /**
 161    * Retrieve the duration of the fade-in effect.
 162    * @return The duration in seconds.
 163    */
 164   float GetFadeInDuration() const;
 165
 166   /**
 167    * Retrieve the attachment which renders the image.
 168    * @return The attachment.
 169    */
 170   ImageAttachment& GetImageAttachment();
 171
 172   /**
 173    * @copydoc Dali::ImageActor::GetCurrentImageSize
 174    */
 175   Vector2 GetCurrentImageSize() const;
 176
 177 public: // Default property extensions from ProxyObject
 178
 179   /**
 180    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyCount()
 181    */
 182   virtual unsigned int GetDefaultPropertyCount() const;
 183
 184   /**
 185    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyName()
 186    */
 187   virtual const std::string& GetDefaultPropertyName(Property::Index index) const;
 188
 189   /**
 190    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyIndex()
 191    */
 192   virtual Property::Index GetDefaultPropertyIndex(const std::string& name) const;
 193
 194   /**
 195    * @copydoc Dali::Internal::ProxyObject::IsDefaultPropertyWritable()
 196    */
 197   virtual bool IsDefaultPropertyWritable(Property::Index index) const;
 198
 199   /**
 200    * @copydoc Dali::Internal::ProxyObject::IsDefaultPropertyAnimatable()
 201    */
 202   virtual bool IsDefaultPropertyAnimatable(Property::Index index) const;
 203
 204   /**
 205    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyType()
 206    */
 207   virtual Property::Type GetDefaultPropertyType(Property::Index index) const;
 208
 209   /**
 210    * @copydoc Dali::Internal::ProxyObject::SetDefaultProperty()
 211    */
 212   virtual void SetDefaultProperty(Property::Index index, const Property::Value& propertyValue);
 213
 214   /**
 215    * @copydoc Dali::Internal::ProxyObject::GetDefaultProperty()
 216    */
 217   virtual Property::Value GetDefaultProperty( Property::Index index ) const;
 218
 219 private: // From RenderableActor
 220
 221   /**
 222    * @copydoc RenderableActor::GetRenderableAttachment
 223    */
 224   virtual RenderableAttachment& GetRenderableAttachment() const;
 225
 226 protected:
 227
 228   /**
 229    * Protected constructor; see also ImageActor::New()
 230    */
 231   ImageActor();
 232
 233   /**
 234    * A reference counted object may only be deleted by calling Unreference()
 235    */
 236   virtual ~ImageActor();
 237
 238 private:
 239
 240   // Helper for overloads of SetImage().
 241   void OnImageSet( Image& image );
 242
 243   /**
 244    * From Actor.
 245    * This is called after SizeSet() has been called.
 246    */
 247   virtual void OnSizeSet( const Vector3& targetSize );
 248
 249   /**
 250    * From Actor; used to trigger fade-in animations.
 251    */
 252   virtual void OnStageConnectionInternal();
 253
 254   /**
 255    * From Actor; used to notify Image.
 256    */
 257   virtual void OnStageDisconnectionInternal();
 258
 259   /**
 260    * Helper for when the image loads.
 261    * @param[in] image The newly (re)loaded image.
 262    */
 263   void ImageLoaded( Dali::Image image );
 264
 265   /**
 266    * Helper to start fade-in animations.
 267    */
 268   void FadeIn();
 269
 270 private:
 271
 272   ImageAttachmentPtr mImageAttachment; ///< Used to display the image (holds a pointer to currently showed Image)
 273   ImageConnector     mImageNext;       ///< Manages the Image this ImageActor will show (used when changing displayed image)
 274
 275   // flags, compressed to bitfield (uses only 4 bytes)
 276   bool mCustomSizeSet:1; ///< True if SizeSet() has ever been called
 277   bool mFadeIn:1;        ///< True if fade in animation is enabled
 278   bool mFadeInitial:1;   ///< True if fading in for the first time
 279
 280   SlotDelegate<ImageActor> mLoadedConnection; ///< Tracks the connection to the "loading finished" signal
 281
 282   // For fade-in animations
 283   float        mFadeInDuration;  ///< Length of animation
 284
 285   static bool mFirstInstance ;
 286   static DefaultPropertyLookup* mDefaultImageActorPropertyLookup; ///< Default properties
 287
 288 };
 289
 290 } // namespace Internal
 291
 292 // Helpers for public-api forwarding methods
 293
 294 inline Internal::ImageActor& GetImplementation(Dali::ImageActor& image)
 295 {
 296   DALI_ASSERT_ALWAYS(image && "Image handle is empty");
 297
 298   BaseObject& handle = image.GetBaseObject();
 299
 300   return static_cast<Internal::ImageActor&>(handle);
 301 }
 302
 303 inline const Internal::ImageActor& GetImplementation(const Dali::ImageActor& image)
 304 {
 305   DALI_ASSERT_ALWAYS(image && "Image handle is empty");
 306
 307   const BaseObject& handle = image.GetBaseObject();
 308
 309   return static_cast<const Internal::ImageActor&>(handle);
 310 }
 311
 312 } // namespace Dali
 313
 314 #endif // __DALI_INTERNAL_IMAGE_ACTOR_H__