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_Components
18  * @{
19  *
20  * @brief Defines UI components such as buttons, texts, images, lists, and progress bars.
21  *
22  * @since 1.0
23  * @version 1.0
24  */
25 
26 /**
27  * @file ui_abstract_progress.h
28  *
29  * @brief Defines the base class attributes and common functions of a progress bar.
30  *
31  * @since 1.0
32  * @version 1.0
33  */
34 
35 #ifndef GRAPHIC_LITE_UI_ABSTRACT_PROGRESS_H
36 #define GRAPHIC_LITE_UI_ABSTRACT_PROGRESS_H
37 
38 #include "common/image.h"
39 #include "components/ui_view.h"
40 
41 namespace OHOS {
42 /**
43  * @brief Represents the abstract base class which provides functions related to the progress bar.
44  *
45  * @see UIView
46  * @since 1.0
47  * @version 1.0
48  */
49 class UIAbstractProgress : public UIView {
50 public:
51     /**
52      * @brief A constructor used to create a <b>UIAbstractProgress</b> instance.
53      *
54      * @since 1.0
55      * @version 1.0
56      */
57     UIAbstractProgress();
58 
59     /**
60      * @brief A destructor used to delete the <b>UIAbstractProgress</b> instance.
61      *
62      * @since 1.0
63      * @version 1.0
64      */
65     virtual ~UIAbstractProgress();
66 
67     /**
68      * @brief Obtains the component type.
69      *
70      * @return Returns the component type, as defined in {@link UIViewType}.
71      * @since 1.0
72      * @version 1.0
73      */
GetViewType()74     UIViewType GetViewType() const override
75     {
76         return UI_ABSTRACT_PROGRESS;
77     }
78 
79     /**
80      * @brief Sets whether the background of the progress bar is visible.
81      *
82      * @param enable Specifies whether the background of the progress bar is visible. <b>true</b> (the default value)
83      *               indicates that the background is visible, and <b>false</b> indicates the opposite case.
84      * @since 1.0
85      * @version 1.0
86      */
EnableBackground(bool enable)87     void EnableBackground(bool enable)
88     {
89         enableBackground_ = enable;
90     }
91 
92     /**
93      * @brief Sets the current value for this progress bar.
94      *
95      * @param value Indicates the current value of this progress bar, within [rangeMin, rangeMax] specified by
96      *              {@link SetRange}. If the value is less than <b>rangeMin</b>, <b>rangeMin</b> is used;
97      *              if the value is greater than <b>rangeMax</b>, <b>rangeMax</b> is used.
98      * @see SetRange | GetValue
99      * @since 1.0
100      * @version 1.0
101      */
102     void SetValue(int32_t value);
103 
104     /**
105      * @brief Obtains the current value of this progress bar.
106      *
107      * @return Returns the current value of this progress bar.
108      * @see SetValue
109      * @since 1.0
110      * @version 1.0
111      */
GetValue()112     int32_t GetValue() const
113     {
114         return curValue_;
115     }
116 
117     /**
118      * @brief Sets the range for this progress bar.
119      *
120      * <b>rangeMin</b> and <b>rangeMax</b> can be any value represented by <b>int32_t</b>.
121      * <b>rangeMax</b> must be greater than or equal to <b>rangeMin</b>.
122      * Otherwise, the setting does not take effect and the original value is used.
123      *
124      * @param rangeMax Indicates the maximum value of this progress bar. The default value is 100.
125      * @param rangeMin Indicates the minimum value of this progress bar. The default value is 0.
126      * @see GetRangeMin | GetRangeMax
127      * @since 1.0
128      * @version 1.0
129      */
130     void SetRange(int32_t rangeMax, int32_t rangeMin);
131 
132     /**
133      * @brief Obtains the minimum value of this progress bar.
134      *
135      * @return Returns the minimum value of this progress bar.
136      * @see  SetRange | GetRangeMax
137      * @since 1.0
138      * @version 1.0
139      */
GetRangeMin()140     int32_t GetRangeMin() const
141     {
142         return rangeMin_;
143     }
144 
145     /**
146      * @brief Obtains the maximum value of this progress bar.
147      *
148      * @return Returns the maximum value of this progress bar.
149      * @see SetRange | GetRangeMin
150      * @since 1.0
151      * @version 1.0
152      */
GetRangeMax()153     int32_t GetRangeMax() const
154     {
155         return rangeMax_;
156     }
157 
158     /**
159      * @brief Sets the image for this progress bar.
160      *
161      * The size of the image must be the same as that of the progress bar to ensure a normal display.
162      * If the value of any input parameter is <b>nullptr</b>, image filling is canceled.
163      * Instead, color filling will be adopted.
164      *
165      * @param foregroundImage Indicates the foreground image of the progress bar. The default value is <b>nullptr</b>.
166      * @param backgroundImage Indicates the background image of the progress bar. The default value is <b>nullptr</b>.
167      * @since 1.0
168      * @version 1.0
169      */
170     void SetImage(const char* foregroundImage, const char* backgroundImage = nullptr);
171 
172     /**
173      * @brief Sets the image as a pixel map for this progress bar.
174      *
175      * The size of the image must be the same as that of the progress bar to ensure a normal display.
176      * If the value of any input parameter is <b>nullptr</b>, image filling is canceled.
177      * Instead, color filling will be adopted.
178      *
179      * @param foregroundImage Indicates the foreground image of the progress bar. The default value is <b>nullptr</b>.
180      * @param backgroundImage Indicates the background image of the progress bar. The default value is <b>nullptr</b>.
181      * @since 1.0
182      * @version 1.0
183      */
184     void SetImage(const ImageInfo* foregroundImage, const ImageInfo* backgroundImage = nullptr);
185 
186     /**
187      * @brief Sets the step for this progress bar.
188      *
189      * The step is used to control the update frequency of the progress bar. When the value change exceeds the step,
190      * the progress bar is redrawn. \n
191      * For example, when the step is set to 10 and the current progress value is 5, the progress bar will not be
192      * redrawn if the progress value becomes 14, but will be redrawn if the progress value becomes 15. \n
193      * In addition, when its current value changes to be the maximum or minimum value,
194      * the progress bar is redrawn regardless of the step you set. \n
195      *
196      * @param step Indicates the step to set. The default value is 1.
197      * @see GetStep
198      * @since 1.0
199      * @version 1.0
200      */
SetStep(uint32_t step)201     void SetStep(uint32_t step)
202     {
203         step_ = step;
204     }
205 
206     /**
207      * @brief Obtains the current step of this progress bar.
208      *
209      * @return Returns the current step.
210      * @see  SetStep
211      * @since 1.0
212      * @version 1.0
213      */
GetStep()214     uint32_t GetStep() const
215     {
216         return step_;
217     }
218 
219     /**
220      * @brief Sets the background style for this progress bar.
221      *
222      * @param style Indicates the background style of the progress bar. For details, see {@link Style}.
223      * @see SetForegroundStyle | GetBackgroundStyle
224      * @since 1.0
225      * @version 1.0
226      */
227     void SetBackgroundStyle(const Style& style);
228 
229     /**
230      * @brief Sets a background style for this progress bar.
231      *
232      * @param key Indicates the key of the style to set.
233      * @param value Indicates the value matching the key.
234      * @since 1.0
235      * @version 1.0
236      */
237     void SetBackgroundStyle(uint8_t key, int64_t value);
238 
239     /**
240      * @brief Obtains the background style of this progress bar.
241      *
242      * @return Returns the background style.
243      * @See SetBackgroundStyle
244      * @since 1.0
245      * @version 1.0
246      */
247     const Style& GetBackgroundStyle() const;
248 
249     /**
250      * @brief Obtains the value of a background style of this progress bar.
251      *
252      * @param key Indicates the key of the style.
253      * @return Returns the value of the style.
254      * @since 1.0
255      * @version 1.0
256      */
257     int64_t GetBackgroundStyle(uint8_t key) const;
258 
259     /**
260      * @brief Sets the foreground style for this progress bar.
261      *
262      * @param style Indicates the foreground style of this progress bar. For details, see {@link Style}.
263      * @see SetBackgroundStyle | GetForegroundStyle
264      * @since 1.0
265      * @version 1.0
266      */
267     void SetForegroundStyle(const Style& style);
268 
269     /**
270      * @brief Sets a foreground style for this progress bar.
271      *
272      * @param key Indicates the key of the style to set.
273      * @param value Indicates the value matching the key.
274      * @since 1.0
275      * @version 1.0
276      */
277     void SetForegroundStyle(uint8_t key, int64_t value);
278 
279     /**
280      * @brief Obtains the foreground style of this progress bar.
281      *
282      * @return Returns the foreground style.
283      * @See SetForegroundStyle
284      * @since 1.0
285      * @version 1.0
286      */
287     const Style& GetForegroundStyle() const;
288 
289     /**
290      * @brief Obtains the value of a foreground style of this progress bar.
291      *
292      * @param key Indicates the key of the style.
293      * @return Returns the value of the style.
294      * @since 1.0
295      * @version 1.0
296      */
297     int64_t GetForegroundStyle(uint8_t key) const;
298 
299     /**
300      * @brief Sets the type of caps on the background and foreground of the progress bar.
301      *
302      * @param cap  Indicates the cap type. For details, see {@link CapType}.
303      * @since 1.0
304      * @version 1.0
305      */
SetCapType(CapType cap)306     void SetCapType(CapType cap)
307     {
308         SetBackgroundStyle(STYLE_LINE_CAP, cap);
309         SetForegroundStyle(STYLE_LINE_CAP, cap);
310     }
311 
312 protected:
313     static constexpr uint16_t MAX_PERCENT_VALUE = 100;
314     static constexpr uint16_t MIN_PERCENT_VALUE = 0;
315 
316     uint32_t GetRangeSize() const;
317     int16_t GetCurrentPos(int16_t distance) const;
318     virtual bool InitImage();
319     bool enableBackground_ : 1;
320     bool backgroundStyleAllocFlag_ : 1;
321     bool foregroundStyleAllocFlag_ : 1;
322     Style* backgroundStyle_;
323     Style* foregroundStyle_;
324     Image* backgroundImage_;
325     Image* foregroundImage_;
326     int32_t rangeMax_;
327     int32_t rangeMin_;
328     int32_t curValue_;
329     uint32_t step_;
330     int32_t lastValue_;
331 };
332 } // namespace OHOS
333 #endif // GRAPHIC_LITE_UI_ABSTRACT_PROGRESS_H
334