1/*
2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup UI_Animator
18 * @{
19 *
20 * @brief Defines UI animation effects and provides matched curves.
21 *
22 * @since 1.0
23 * @version 1.0
24 */
25
26/**
27 * @file animator.h
28 *
29 * @brief Defines the attributes and common functions of the animator module.
30 *
31 * @since 1.0
32 * @version 1.0
33 */
34
35#ifndef GRAPHIC_LITE_ANIMATOR_H
36#define GRAPHIC_LITE_ANIMATOR_H
37
38#include "components/ui_view.h"
39
40namespace OHOS {
41/**
42 * @brief Represents the animator callback.
43 *
44 * You need to implement the callback function to produce specific animator effects.
45 *
46 * @since 1.0
47 * @version 1.0
48 */
49class AnimatorCallback : public HeapBase {
50public:
51    /**
52     * @brief Called when each frame starts. This is a pure virtual function, which needs your inheritance
53     *        and implementation.
54     *
55     * @param view Indicates the <b>UIView</b> instance, which is added from the constructor of
56     *             the <b>Animator</b> class.
57     * @since 1.0
58     * @version 1.0
59     */
60    virtual void Callback(UIView* view) = 0;
61
62    /**
63     * @brief Called when an animator stops. This is a pure virtual function, which needs your inheritance and
64     *        implementation.
65     *
66     * @param view Indicates the <b>UIView</b> instance, which is added from the constructor of
67     *             the <b>Animator</b> class.
68     * @since 1.0
69     * @version 1.0
70     */
71    virtual void OnStop(UIView& view) {}
72
73    /**
74     * @brief A default destructor used to delete an <b>AnimatorCallback</b> instance.
75     *
76     * @since 1.0
77     * @version 1.0
78     */
79    virtual ~AnimatorCallback() {}
80};
81
82/**
83 * @brief Represents an animator.
84 *
85 * This class is used to set the animator attributes, such as the duration, whether an animator is repeated,
86 * start and stop of an animator.
87 *
88 * @see Animator
89 * @since 1.0
90 * @version 1.0
91 */
92class Animator : public HeapBase {
93public:
94    /**
95     * @brief Enumerates the states of this animator.
96     */
97    enum : uint8_t {
98        /** Stop */
99        STOP,
100        /** Start */
101        START,
102        /** Pause */
103        PAUSE,
104        /** Running (reserved and not used currently) */
105        RUNNING
106    };
107
108    /**
109     * @brief A default constructor used to create an <b>Animator</b> instance.
110     *
111     * @since 1.0
112     * @version 1.0
113     */
114    Animator()
115        : callback_(nullptr), view_(nullptr), state_(STOP), period_(0), repeat_(false), runTime_(0), lastRunTime_(0)
116    {
117    }
118
119    /**
120     * @brief A constructor used to create an <b>Animator</b> instance.
121     *
122     * @param callback Indicates the animator callback for producing animator effects.
123     *                 For details, see {@link AnimatorCallback}.
124     * @param view     Indicates the <b>UIView</b> instance bound to an animator, which can be used when invoking
125     *                 the animator callback.
126     * @param time     Indicates the duration of this animator, in milliseconds.
127     * @param repeat   Specifies whether to repeat this animator. <b>true</b> indicates the animator is repeated,
128     *                 and <b>false</b> (default value) indicates the animator is played once.
129     * @since 1.0
130     * @version 1.0
131     */
132    Animator(AnimatorCallback* callback, UIView* view, uint32_t time, bool repeat)
133        : callback_(callback), view_(view), state_(STOP), period_(time), repeat_(repeat), runTime_(0), lastRunTime_(0)
134    {
135    }
136
137    /**
138     * @brief A destructor used to delete the <b>Animator</b> instance.
139     *
140     * @since 1.0
141     * @version 1.0
142     */
143    virtual ~Animator();
144
145    /**
146     * @brief Starts this animator.
147     *
148     * @see Stop
149     * @since 1.0
150     * @version 1.0
151     */
152    void Start();
153
154    /**
155     * @brief Stops this animator.
156     *
157     * @see Start
158     * @since 1.0
159     * @version 1.0
160     */
161    void Stop();
162
163    /**
164     * @brief Pauses this animator.
165     *
166     * @see Resume
167     * @since 1.0
168     * @version 1.0
169     */
170    void Pause();
171
172    /**
173     * @brief Resumes this animator from where it was paused.
174     *
175     * @see Pause
176     * @since 1.0
177     * @version 1.0
178     */
179    void Resume();
180
181    /**
182     * @brief Obtains the current state of this animator.
183     *
184     * @return Returns the current animator state, which can be {@link START}, {@link STOP}, or {@link PAUSE}.
185     * @see SetState
186     * @since 1.0
187     * @version 1.0
188     */
189    uint8_t GetState() const
190    {
191        return state_;
192    }
193
194    /**
195     * @brief Sets the current state for this animator.
196     *
197     * @param state Indicates the current animator state to set, which can be {@link STOP}, {@link START},
198     *              or {@link PAUSE}.
199     * @see GetState
200     * @since 1.0
201     * @version 1.0
202     */
203    void SetState(uint8_t state)
204    {
205        state_ = state;
206    }
207
208    /**
209     * @brief Obtains the total duration of this animator.
210     *
211     * @return Returns the total duration.
212     * @see SetTime
213     * @since 1.0
214     * @version 1.0
215     */
216    uint32_t GetTime() const
217    {
218        return period_;
219    }
220
221    /**
222     * @brief Sets the total duration for this animator.
223     *
224     * @param time Indicates the total duration to set, in milliseconds.
225     * @see GetTime
226     * @since 1.0
227     * @version 1.0
228     */
229    void SetTime(uint32_t period)
230    {
231        period_ = period;
232    }
233
234    /**
235     * @brief Obtains the running time of this animator.
236     *
237     * @return Returns the running time.
238     * @see SetRunTime
239     * @since 1.0
240     * @version 1.0
241     */
242    uint32_t GetRunTime() const
243    {
244        return runTime_;
245    }
246
247    /**
248     * @brief Sets the running time for this animator.
249     *
250     * @param runTime Indicates the running time to set, in milliseconds.
251     * @see GetRunTime
252     * @since 1.0
253     * @version 1.0
254     */
255    void SetRunTime(uint32_t runTime)
256    {
257        runTime_ = runTime;
258    }
259
260    /**
261     * @brief Checks whether this animator is repeated.
262     *
263     * @return Returns <b>true</b> if the animator is repeated; returns <b>false</b> if the animator is played once.
264     * @since 1.0
265     * @version 1.0
266     */
267    bool IsRepeat() const
268    {
269        return repeat_;
270    }
271
272    void Run();
273
274protected:
275    AnimatorCallback* callback_;
276    UIView* view_;
277    uint8_t state_;
278    uint32_t period_;
279    bool repeat_;
280    uint32_t runTime_;
281    uint32_t lastRunTime_;
282};
283} // namespace OHOS
284#endif
285