inc/FUiCtrlAnimation.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FUiCtrlAnimation.h
  20  * @brief       This header file contains the declarations of the %Animation class.
  21  *
  22  * This header file contains the declarations of the %Animation class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_ANIMATION_H_
  26 #define _FUI_CTRL_ANIMATION_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FBaseColArrayList.h>
  31 #include <FGrpBitmap.h>
  32 #include <FGrpColor.h>
  33 #include <FGrpPoint.h>
  34 #include <FGrpRectangle.h>
  35 #include <FUiContainer.h>
  36 #include <FUiCtrlAnimationFrame.h>
  37 #include <FUiIAnimationEventListener.h>
  38
  39 namespace Tizen { namespace Ui { namespace Controls
  40 {
  41
  42 /**
  43  * @enum        AnimationStatus
  44  *
  45  * Defines the animation status.
  46  *
  47  * @since       2.0
  48  */
  49 enum AnimationStatus
  50 {
  51         ANIMATION_STOPPED,              /**< The %Animation is in 'stopped' state */
  52         ANIMATION_PAUSED,               /**< The %Animation is in 'paused' state */
  53         ANIMATION_PLAYING               /**< The %Animation is in 'playing' state */
  54 };
  55
  56
  57 /**
  58  * @class       Animation
  59  * @brief This class defines the common behavior of an %Animation control.
  60  *
  61  * @since       2.0
  62  *
  63  * The %Animation class displays a series of frames one by one that are represented by the AnimationFrame instances.
  64  *
  65  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_animation.htm">Animation</a>.
  66  *
  67  *
  68  * The following example demonstrates how to use the %Animation class.
  69  *
  70  *
  71  * @code
  72 // Sample code for AnimationSample.h
  73 #include <FBase.h>
  74 #include <FUi.h>
  75
  76 class AnimationSample
  77         : public Tizen::Ui::Controls::Form
  78         , public Tizen::Ui::IAnimationEventListener
  79 {
  80 public:
  81         AnimationSample(void)
  82         : __animationFrameList(){}
  83
  84         bool Initialize(void);
  85         virtual result OnInitializing(void);
  86         virtual result OnTerminating(void);
  87
  88         // IAnimationEventListener
  89         virtual void OnAnimationStopped(const Tizen::Ui::Control& source);
  90
  91 private :
  92         Tizen::Base::Collection::ArrayList __animationFrameList;
  93 };
  94
  95  *      @endcode
  96  *
  97  *      @code
  98
  99 // Sample code for AnimationSample.cpp
 100 #include <FApp.h>
 101 #include <FGraphics.h>
 102
 103 #include "AnimationSample.h"
 104
 105 using namespace Tizen::App;
 106 using namespace Tizen::Base::Collection;
 107 using namespace Tizen::Graphics;
 108 using namespace Tizen::Ui::Controls;
 109
 110 bool
 111 AnimationSample::Initialize(void)
 112 {
 113         Construct(FORM_STYLE_NORMAL);
 114         return true;
 115 }
 116
 117 result
 118 AnimationSample::OnInitializing(void)
 119 {
 120         result r = E_SUCCESS;
 121
 122         // Gets instances of Bitmap
 123         AppResource *pAppResource = Application::GetInstance()->GetAppResource();
 124         Bitmap* pBitmap1 = pAppResource->GetBitmapN(L"progressing00_big.png");
 125         Bitmap* pBitmap2 = pAppResource->GetBitmapN(L"progressing02_big.png");
 126         Bitmap* pBitmap3 = pAppResource->GetBitmapN(L"progressing04_big.png");
 127         Bitmap* pBitmap4 = pAppResource->GetBitmapN(L"progressing06_big.png");
 128
 129         // Creates instances of AnimationFrame
 130         AnimationFrame* pAniFrame1 = new AnimationFrame(*pBitmap1, 1000) ;
 131         AnimationFrame* pAniFrame2 = new AnimationFrame(*pBitmap2, 1000) ;
 132         AnimationFrame* pAniFrame3 = new AnimationFrame(*pBitmap3, 1000) ;
 133         AnimationFrame* pAniFrame4 = new AnimationFrame(*pBitmap4, 1000) ;
 134
 135         __animationFrameList.Construct();
 136         __animationFrameList.Add(*pAniFrame1);
 137         __animationFrameList.Add(*pAniFrame2);
 138         __animationFrameList.Add(*pAniFrame3);
 139         __animationFrameList.Add(*pAniFrame4);
 140
 141         // Creates an instance of Animation
 142         Animation* pAnimation = new Animation();
 143         pAnimation->Construct(Rectangle((GetClientAreaBounds().width - pBitmap1->GetWidth()) / 2, 100,
 144                                                   pBitmap1->GetWidth(), pBitmap1->GetHeight()), __animationFrameList);
 145         pAnimation->SetRepeatCount(100);
 146         pAnimation->AddAnimationEventListener(*this);
 147
 148         // Adds the animation to the form
 149         AddControl(pAnimation);
 150
 151         // Plays the animation
 152         pAnimation->Play();
 153
 154         delete pBitmap1;
 155         delete pBitmap2;
 156         delete pBitmap3;
 157         delete pBitmap4;
 158
 159         return r;
 160 }
 161
 162 result
 163 AnimationSample::OnTerminating(void)
 164 {
 165         result r = E_SUCCESS;
 166
 167         // Deallocates added animation frames from the list
 168         __animationFrameList.RemoveAll(true);
 169
 170         return r;
 171 }
 172
 173 void
 174 AnimationSample::OnAnimationStopped(const Control& source)
 175 {
 176         // ....
 177 }
 178  * @endcode
 179  *
 180  */
 181 class _OSP_EXPORT_ Animation
 182         : public Tizen::Ui::Control
 183 {
 184
 185 public:
 186         /**
 187          * The object is not fully constructed after this constructor is called. @n
 188          * For full construction, the %Construct() method must be called right after calling this constructor.
 189          *
 190          * @since               2.0
 191          */
 192         Animation(void);
 193
 194
 195         /**
 196          * This polymorphic destructor should be overridden if required. @n
 197          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
 198          *
 199          * @since               2.0
 200          */
 201         virtual ~Animation(void);
 202
 203
 204         /**
 205          * Initializes this instance of %Animation with the specified parameters. @n
 206          * The @c aniFrames list of the AnimationFrame instances should be deleted explicitly after use.
 207          *
 208          * @since               2.0
 209          *
 210          * @return              An error code
 211          * @param[in]   rect                    An instance of the Tizen::Graphics::Rectangle class @n
 212          *                                                              This instance represents the x and y coordinates of the top-left corner of the created window along with
 213          *                                                              its width and height.@n
 214          *                                                              The optimal size of the control is defined in
 215          *                                                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 216          * @param[in]   aniFrames               An IList of %AnimationFrames used in the animation
 217          * @exception   E_SUCCESS               The method is successful.
 218          * @exception   E_SYSTEM                A system error has occurred.
 219          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 220          * @remarks
 221          *                      - A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
 222          *                      - The size of the control must be within the range defined by the minimum size and the maximum size.
 223          */
 224         result Construct(const Tizen::Graphics::Rectangle& rect, const Tizen::Base::Collection::IList& aniFrames);
 225
 226         /**
 227          * Initializes this instance of %Animation with the specified parameters. @n
 228          * The @c aniFrames list of the AnimationFrame instances should be deleted explicitly after use.
 229          *
 230          * @since               2.1
 231          *
 232          * @return              An error code
 233          * @param[in]   rect                    An instance of the Tizen::Graphics::FloatRectangle class @n
 234          *                                                              This instance represents the x and y coordinates of the top-left corner of the created window along with
 235          *                                                              its width and height.@n
 236          *                                                              The optimal size of the control is defined in
 237          *                                                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 238          * @param[in]   aniFrames               An IList of %AnimationFrames used in the animation
 239          * @exception   E_SUCCESS               The method is successful.
 240          * @exception   E_SYSTEM                A system error has occurred.
 241          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 242          * @remarks
 243          *                      - A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
 244          *                      - The size of the control must be within the range defined by the minimum size and the maximum size.
 245          */
 246         result Construct(const Tizen::Graphics::FloatRectangle& rect, const Tizen::Base::Collection::IList& aniFrames);
 247
 248 public:
 249         /**
 250          * Adds a listener instance to the current instance of %Animation. @n
 251          * The added listener can listen to the events on the given event dispatcher's context when they are fired. @n
 252          * When an animation stops, a state change event with the state name "ANIMATION_NOTIFY_CLOSE" is fired.
 253          *
 254          * @since               2.0
 255          *
 256          * @param[in]   listener        The listener to add
 257          */
 258         void AddAnimationEventListener(Tizen::Ui::IAnimationEventListener& listener);
 259
 260
 261         /**
 262          * Removes a listener instance from the current instance of %Animation. @n
 263          * The removed listener cannot listen to the events when they are fired.
 264          *
 265          * @since               2.0
 266          *
 267          * @param[in]   listener        The listener to remove
 268          */
 269         void RemoveAnimationEventListener(Tizen::Ui::IAnimationEventListener& listener);
 270
 271
 272         /**
 273          * Sets the repeat count of the animation. @n
 274          * If this value is not set, the default value is @c 1.
 275          *
 276          * @since               2.0
 277          *
 278          * @param[in]   count           The repeat count
 279          */
 280         void SetRepeatCount(int count);
 281
 282
 283         /**
 284          * Gets the total repeat count of the animation.
 285          *
 286          * @since               2.0
 287          *
 288          * @return              The total repeat count @n
 289          *                              The default repeat count is @c 1.
 290          */
 291         int GetRepeatCount(void) const;
 292
 293
 294         /**
 295          * Gets the current repeated count of the animation.
 296          *
 297          * @since               2.0
 298          *
 299          * @return              The current repeated count @n
 300          *                              The default current repeated count is @c 0.
 301          */
 302         int GetCurrentRepeatedCount(void) const;
 303
 304
 305         /**
 306          * Gets the total image count of the animation.
 307          *
 308          * @since               2.0
 309          *
 310          * @return              The total image count @n
 311          *                              The default image count is @c 0.
 312          */
 313         int GetImageCount(void) const;
 314
 315
 316         /**
 317          * Plays the animation.
 318          *
 319          * @since               2.0
 320          */
 321         void Play(void);
 322
 323
 324         /**
 325          * Stops the animation.
 326          *
 327          * @since               2.0
 328          */
 329         void Stop(void);
 330
 331
 332         /**
 333          * Pauses the animation.
 334          *
 335          * @since               2.0
 336          */
 337         void Pause(void);
 338
 339
 340         /**
 341          * Gets the status of the animation.
 342          *
 343          * @since               2.0
 344          *
 345          * @return              The status of animation @n
 346          *                              The default animation status is @c ANIMATION_STOPPED.
 347          */
 348         AnimationStatus GetStatus(void) const;
 349
 350 private:
 351         //
 352         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 353         //
 354         Animation(const Animation& rhs);
 355
 356         //
 357         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 358         //
 359         Animation& operator =(const Animation& rhs);
 360
 361         friend class _AnimationImpl;
 362
 363 };  // Animation
 364
 365 }}} // Tizen::Ui::Controls
 366
 367 #endif // _FUI_CTRL_ANIMATION_H_