1 /*
2  * Copyright (c) 2020-2022 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_label.h
28  *
29  * @brief Declares a <b>UILabel</b> class that represents a label.
30  *
31  * @since 1.0
32  * @version 1.0
33  */
34 
35 #ifndef GRAPHIC_LITE_UI_LABEL_H
36 #define GRAPHIC_LITE_UI_LABEL_H
37 
38 #include "animator/animator.h"
39 #include "common/text.h"
40 #include "components/ui_view.h"
41 
42 namespace OHOS {
43 /**
44  * @brief Defines the functions for presenting a label in a specified area, setting the style and background color
45  *        of a label, and setting the display mode of a long label text.
46  *
47  * @since 1.0
48  * @version 1.0
49  */
50 class UILabel : public UIView {
51 public:
52     /**
53      * @brief Enumerates the display modes of a long text.
54      */
55     enum LineBreakMode : uint8_t {
56         /**
57          * The label size is adaptive to the text size.
58          */
59         LINE_BREAK_ADAPT = 0,
60         /**
61          * The height of this label remains unchanged, and the width is adaptive to the text size.
62          */
63         LINE_BREAK_STRETCH,
64         /**
65          * The width of this label remains unchanged, and the height is adaptive to the text size.
66          * The text switches to the next line if the text exceeds the maximum label width.
67          */
68         LINE_BREAK_WRAP,
69         /**
70          * The width and height of this label remain unchanged.
71          * If this text is too long, ellipsis will be used at the end.
72          */
73         LINE_BREAK_ELLIPSIS,
74         /**
75          * The width and height of this label remain unchanged.
76          * If this text is too long, it will be rolled to display.
77          */
78         LINE_BREAK_MARQUEE,
79         /**
80          * The width and height of this label remain unchanged.
81          * If this text is too long, it will be cropped to display.
82          */
83         LINE_BREAK_CLIP,
84         /**
85          * Maximum value of the line break mode, which is used for validity check.
86          */
87         LINE_BREAK_MAX,
88     };
89 
90     /**
91      * @brief A constructor used to create a <b>UILabel</b> instance.
92      *
93      * @since 1.0
94      * @version 1.0
95      */
96     UILabel();
97 
98     /**
99      * @brief A destructor used to delete the <b>UILabel</b> instance.
100      *
101      * @since 1.0
102      * @version 1.0
103      */
104     virtual ~UILabel();
105 
106     /**
107      * @brief Obtains the view type.
108      *
109      * @return Returns <b>UI_LABEL</b>, as defined in {@link UIViewType}.
110      * @since 1.0
111      * @version 1.0
112      */
GetViewType()113     UIViewType GetViewType() const override
114     {
115         return UI_LABEL;
116     }
117 
118     /**
119      * @brief Obtains the width of this label.
120      *
121      * @return Returns the label width.
122      * @since 1.0
123      * @version 1.0
124      */
125     int16_t GetWidth() override;
126 
127     /**
128      * @brief Obtains the height of this label.
129      *
130      * @return Returns the label height.
131      * @since 1.0
132      * @version 1.0
133      */
134     int16_t GetHeight() override;
135 
136     /**
137      * @brief Sets the view style.
138      * @param style Indicates the view style.
139      * @since 1.0
140      * @version 1.0
141      */
SetStyle(Style & style)142     void SetStyle(Style& style) override
143     {
144         UIView::SetStyle(style);
145     }
146 
147     /**
148      * @brief Sets a style.
149      *
150      * @param key Indicates the key of the style to set.
151      * @param value Indicates the value matching the key.
152      * @since 1.0
153      * @version 1.0
154      */
155     void SetStyle(uint8_t key, int64_t value) override;
156 
157     /**
158      * @brief Checks whether this label needs to be covered before drawing it.
159      *
160      * @param invalidatedArea Indicates the area to draw.
161      * @return Returns <b>true</b> if this label needs to be covered; returns <b> false</b> otherwise.
162      * @since 1.0
163      * @version 1.0
164      */
OnPreDraw(Rect & invalidatedArea)165     bool OnPreDraw(Rect& invalidatedArea) const override
166     {
167         return false;
168     }
169 
170     /**
171      * @brief Draws this label.
172      *
173      * @param invalidatedArea Indicates the area to draw.
174      * @since 1.0
175      * @version 1.0
176      */
177     void OnDraw(BufferInfo& gfxDstBuffer, const Rect& invalidatedArea) override;
178 
179     /**
180      * @brief Sets the text content for this label.
181      *
182      * @param text Indicates the pointer to the text content.
183      * @since 1.0
184      * @version 1.0
185      */
186     void SetText(const char* text);
187 
188     /**
189      * @brief Sets the SpannableString content for this label.
190      *
191      * @param text Indicates the pointer to the text content.
192      */
193     void SetText(const SpannableString* text);
194 
195     /**
196      * @brief Obtains the text of this label.
197      *
198      * @return Returns the text.
199      * @since 1.0
200      * @version 1.0
201      */
GetText()202     const char* GetText() const
203     {
204         return (labelText_ == nullptr) ? nullptr : labelText_->GetText();
205     }
206 
207     /**
208      * @brief Sets the line break mode for this text.
209      *
210      * @param lineBreakMode Indicates the line break mode to set.
211      * @since 1.0
212      * @version 1.0
213      */
214     void SetLineBreakMode(const uint8_t lineBreakMode);
215 
216     /**
217      * @brief Obtains the line break mode of this text.
218      *
219      * @return Returns the line break mode.
220      * @since 1.0
221      * @version 1.0
222      */
GetLineBreakMode()223     uint8_t GetLineBreakMode() const
224     {
225         return lineBreakMode_;
226     }
227 
228     /**
229      * @brief Sets the color for this text.
230      *
231      * @param color Indicates the text color to set.
232      * @since 1.0
233      * @version 1.0
234      */
SetTextColor(ColorType color)235     void SetTextColor(ColorType color)
236     {
237         useTextColor_ = true;
238         textColor_ = color;
239     }
240 
241     /**
242      * @brief Obtains the color of this text.
243      *
244      * @return Returns the text color.
245      * @since 1.0
246      * @version 1.0
247      */
GetTextColor()248     ColorType GetTextColor() const
249     {
250         return useTextColor_ ? textColor_ : GetStyleConst().textColor_;
251     }
252 
253     /**
254      * @brief Sets the alignment mode for this text.
255      *
256      * @param horizontalAlign Indicates the horizontal alignment mode to set,
257      *                        which can be {@link TEXT_ALIGNMENT_LEFT},
258      *                        {@link TEXT_ALIGNMENT_CENTER}, or {@link TEXT_ALIGNMENT_RIGHT}.
259      * @param verticalAlign Indicates the vertical alignment mode to set, which can be
260      *                      {@link TEXT_ALIGNMENT_TOP} (default mode), {@link TEXT_ALIGNMENT_CENTER},
261      *                      or {@link TEXT_ALIGNMENT_BOTTOM}.
262      * @since 1.0
263      * @version 1.0
264      */
265     void SetAlign(UITextLanguageAlignment horizontalAlign,
266         UITextLanguageAlignment verticalAlign = TEXT_ALIGNMENT_TOP);
267 
268     /**
269      * @brief Obtains the horizontal alignment mode.
270      *
271      * @return Returns the horizontal alignment mode.
272      * @since 1.0
273      * @version 1.0
274      */
GetHorAlign()275     UITextLanguageAlignment GetHorAlign()
276     {
277         InitLabelText();
278         return labelText_->GetHorAlign();
279     }
280 
281     /**
282      * @brief Obtains the vertical alignment mode.
283      *
284      * @return Returns the vertical alignment mode.
285      * @since 1.0
286      * @version 1.0
287      */
GetVerAlign()288     UITextLanguageAlignment GetVerAlign()
289     {
290         InitLabelText();
291         return labelText_->GetVerAlign();
292     }
293 
294     /**
295      * @brief Sets the direction for this text.
296      *
297      * @return direct Returns the text direction, as defined in {@link UITextLanguageDirect}.
298      * @since 1.0
299      * @version 1.0
300      */
SetDirect(UITextLanguageDirect direct)301     void SetDirect(UITextLanguageDirect direct)
302     {
303         InitLabelText();
304         labelText_->SetDirect(direct);
305     }
306 
307     /**
308      * @brief Obtains the direction of this text.
309      *
310      * @return Returns the text direction, as defined in {@link UITextLanguageDirect}.
311      * @since 1.0
312      * @version 1.0
313      */
GetDirect()314     UITextLanguageDirect GetDirect()
315     {
316         InitLabelText();
317         return labelText_->GetDirect();
318     }
319 
320     /**
321      * @brief Sets the font ID for this label.
322      *
323      * @param fontId Indicates the font ID composed of font name and size.
324      * @since 1.0
325      * @version 1.0
326      */
327     void SetFontId(uint16_t fontId);
328 
329     /**
330      * @brief Obtains the font ID composed of font name and size.
331      *
332      * @return Returns the front ID of this label.
333      * @since 1.0
334      * @version 1.0
335      */
GetFontId()336     uint16_t GetFontId()
337     {
338         InitLabelText();
339         return labelText_->GetFontId();
340     }
341 
342     /**
343      * @brief Sets the font for this label.
344      *
345      * @param name Indicates the pointer to the font name.
346      * @param size Indicates the font size to set.
347      * @since 1.0
348      * @version 1.0
349      */
350     void SetFont(const char* name, uint8_t size);
351 
352     /**
353      * @brief Sets the scroll speed for this text.
354      *
355      * @param speed Indicates the scroll speed to set.
356      * @since 1.0
357      * @version 1.0
358      */
359     void SetRollSpeed(uint16_t speed);
360 
361     /**
362      * @brief Obtains the scroll speed for this text.
363      *
364      * @return Returns the scroll speed.
365      */
366     uint16_t GetRollSpeed() const;
367 
368     /**
369      * @brief Obtains the width of this text.
370      *
371      * @return Returns the text width.
372      * @since 1.0
373      * @version 1.0
374      */
375     uint16_t GetTextWidth();
376 
377     /**
378      * @brief Obtains the height of this text.
379      *
380      * @return Returns the text height.
381      * @since 1.0
382      * @version 1.0
383      */
384     uint16_t GetTextHeight();
385 
386     /**
387      * @brief Sets the position where this text starts to roll.
388      *
389      * @param pos Indicates the position to set.
390      * @since 1.0
391      * @version 1.0
392      */
393     void SetRollStartPos(int16_t pos);
394 
395     /**
396      * @brief Obtains the position where this text starts to roll.
397      *
398      * @return Returns the position where this text starts to roll.
399      * @since 1.0
400      * @version 1.0
401      */
402     int16_t GetRollStartPos() const;
403 
404     /**
405      * @brief Sets the width for this label.
406      *
407      * @param width Indicates the width to set.
408      * @since 1.0
409      * @version 1.0
410      */
411     void SetWidth(int16_t width) override;
412 
413     /**
414      * @brief Sets the height for this label.
415      *
416      * @param height Indicates the height to set.
417      * @since 1.0
418      * @version 1.0
419      */
420     void SetHeight(int16_t height) override;
421 
422     void ReMeasure() override;
423 
SetSupportBaseLine(bool baseLine)424     void SetSupportBaseLine(bool baseLine)
425     {
426         InitLabelText();
427         labelText_->SetSupportBaseLine(baseLine);
428     }
429 
SetBackgroundColorSpan(ColorType backgroundColor,int16_t start,int16_t end)430     void SetBackgroundColorSpan(ColorType backgroundColor, int16_t start, int16_t end)
431     {
432         labelText_->SetBackgroundColorSpan(backgroundColor, start, end);
433     }
434 
SetForegroundColorSpan(ColorType fontColor,int16_t start,int16_t end)435     void SetForegroundColorSpan(ColorType fontColor, int16_t start, int16_t end)
436     {
437         labelText_->SetForegroundColorSpan(fontColor, start, end);
438     }
439 
SetEliminateTrailingSpaces(bool eliminateTrailingSpaces)440     void SetEliminateTrailingSpaces(bool eliminateTrailingSpaces)
441     {
442         InitLabelText();
443         if (eliminateTrailingSpaces != labelText_->IsEliminateTrailingSpaces()) {
444             labelText_->SetEliminateTrailingSpaces(eliminateTrailingSpaces);
445             RefreshLabel();
446         }
447     }
448 
SetLineBackgroundSpan(ColorType lineBackgroundColor,int16_t start,int16_t end)449     void SetLineBackgroundSpan(ColorType lineBackgroundColor, int16_t start, int16_t end)
450     {
451         labelText_->SetLineBackgroundSpan(lineBackgroundColor, start, end);
452     }
453 
454     void SetAbsoluteSizeSpan(uint16_t start, uint16_t end, uint8_t size);
455     void SetRelativeSizeSpan(uint16_t start, uint16_t end, float size);
456     uint8_t GetFontSize();
457 protected:
458     Text* labelText_;
459     void RefreshLabel();
460     virtual void InitLabelText();
461 
462 private:
463     friend class LabelAnimator;
464 
465     void RemeasureForMarquee(int16_t textWidth);
466 
467     bool needRefresh_ : 1;
468     bool useTextColor_ : 1;
469     bool hasAnimator_ : 1;
470     uint8_t lineBreakMode_ : 4;
471     uint16_t ellipsisIndex_;
472     int16_t offsetX_;
473     ColorType textColor_;
474 
475     static constexpr uint16_t DEFAULT_ANIMATOR_SPEED = 35;
476     union {
477         Animator* animator;
478         struct {
479             uint16_t speed;
480             int16_t pos;
481         };
482     } animator_;
483 };
484 } // namespace OHOS
485 #endif // GRAPHIC_LITE_UI_LABEL_H
486