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_view_group.h
28  *
29  * @brief Declares a view group.
30  *
31  * @since 1.0
32  * @version 1.0
33  */
34 
35 #ifndef GRAPHIC_LITE_UI_VIEW_GROUP_H
36 #define GRAPHIC_LITE_UI_VIEW_GROUP_H
37 
38 #include "components/ui_view.h"
39 
40 namespace OHOS {
41 /**
42  * @brief Represents a view group that consists of its child views.
43  *
44  * The child views can be added to, inserted in, and removed from the view group.
45  * Child views that are added later are displayed at the upper layer of this view group.
46  * All child views are stored in a linked list.
47  *
48  * @since 1.0
49  * @version 1.0
50  */
51 class UIViewGroup : public UIView {
52 public:
53     /**
54      * @brief A default constructor used to create a <b>UIViewGroup</b> instance.
55      *
56      * @since 1.0
57      * @version 1.0
58      */
59     UIViewGroup();
60 
61     /**
62      * @brief A destructor used to delete the <b>UIViewGroup</b> instance.
63      *
64      * @since 1.0
65      * @version 1.0
66      */
67     virtual ~UIViewGroup();
68 
69     /**
70      * @brief Obtains the view type.
71      *
72      * @return Returns <b>UI_VIEW_GROUP</b>, as defined in {@link UIViewType}.
73      * @since 1.0
74      * @version 1.0
75      */
GetViewType()76     UIViewType GetViewType() const override
77     {
78         return UI_VIEW_GROUP;
79     }
80 
81     /**
82      * @brief Adds a child view.
83      *
84      * @param view Indicates the pointer to the child view to add.
85      * @since 1.0
86      * @version 1.0
87      */
88     virtual void Add(UIView* view);
89 
90     /**
91      * @brief Inserts a new child view behind the current one.
92      *
93      * @param prevView Indicates the pointer to the current child view, previous to the new child view to insert.
94      * @param view Indicates the pointer to the new child view to insert.
95      * @since 1.0
96      * @version 1.0
97      */
98     virtual void Insert(UIView* prevView, UIView* insertView);
99 
100     /**
101      * @brief Removes a child view.
102      *
103      * @param view Indicates the pointer to the child view to remove.
104      * @since 1.0
105      * @version 1.0
106      */
107     virtual void Remove(UIView* view);
108 
109     /**
110      * @brief Removes all child views.
111      *
112      * @since 1.0
113      * @version 1.0
114      */
115     virtual void RemoveAll();
116 
117     /**
118      * @brief Obtains the target child view that is visible and can respond to touch events based on given coordinates.
119      *
120      * @param point Indicates the given coordinates.
121      * @param last Indicates the double pointer to the target view. <b>nullptr</b> indicates that the target
122      *             view is not available.
123      * @since 1.0
124      * @version 1.0
125      */
126     void GetTargetView(const Point& point, UIView** last) override;
127 
128     /**
129      * @brief Obtains the current view and target view based on specified coordinates. The obtained current view
130      *        must include the specified coordinates and is a visible top view that can respond to touch events,
131      *        and the obtained target view must be the top view that includes the specified coordinates.
132      *
133      * @param point Indicates the specified coordinates.
134      * @param current Indicates the double pointer to the current view to obtain.
135      *        <b>nullptr</b> indicates that the target view fails to be obtained.
136      * @param target Indicates the double pointer to the target view to obtain.
137      *        <b>nullptr</b> indicates that the target view fails to be obtained.
138      * @since 5.0
139      * @version 3.0
140      */
141     void GetTargetView(const Point& point, UIView** current, UIView** target) override;
142 
143     /**
144      * @brief Moves all child views.
145      *
146      * @param x Indicates the offset distance by which this view group is moved on the x-axis.
147      * @param y Indicates the offset distance by which this view group is moved on the y-axis.
148      * @since 1.0
149      * @version 1.0
150      */
151     virtual void MoveChildByOffset(int16_t x, int16_t y);
152 
153     /**
154      * @brief Obtains the first child view in this view group.
155      *
156      * @return Returns the first child view.
157      * @since 1.0
158      * @version 1.0
159      */
GetChildrenHead()160     UIView* GetChildrenHead() const
161     {
162         return childrenHead_;
163     }
164 
165     /**
166      * @brief Obtains the last child view in this view group.
167      *
168      * @return Returns the last child view.
169      * @since 1.0
170      * @version 1.0
171      */
GetChildrenTail()172     UIView* GetChildrenTail() const
173     {
174         return childrenTail_;
175     }
176 
177     /**
178      * @brief Obtains the first render child view in this view group.
179      *
180      * @return Returns the first render child view.
181      */
182     UIView* GetChildrenRenderHead() const;
183 
184     /**
185      * @brief Set the first render child view in this view group.
186      *
187      * @param renderHead the first render child view.
188      */
189     void SetChildrenRenderHead(UIView* renderHead);
190 
191     /**
192      * @brief Sets whether this view group is intercepted upon touch events.
193      *
194      * @param flag Specifies whether this view group is intercepted upon touch events. <b>true</b> indicates that
195      *             this view group is intercepted upon touch events, and <b> false</b> indicates the opposite case.
196      * @since 1.0
197      * @version 1.0
198      */
SetDisallowIntercept(bool flag)199     void SetDisallowIntercept(bool flag)
200     {
201         disallowIntercept_ = flag;
202     }
203 
204     /**
205      * @brief Obtains the target child view with a specified ID.
206      *
207      * @param id Indicates the pointer to the ID of the target child view.
208      * @return Returns the target child view if available; returns <b>nullptr</b> otherwise.
209      * @since 1.0
210      * @version 1.0
211      */
212     UIView* GetChildById(const char* id) const override;
213 
214     /**
215      * @brief Sets whether the size of this view group is adaptive to that of all child views.
216      *
217      * @param state Specifies whether the size of this view group is adaptive to that of all child views.
218      *              <b>true</b> indicates automatic adaption is enabled, and <b> false</b> indicates the opposite case.
219      * @since 1.0
220      * @version 1.0
221      */
SetAutoSize(bool state)222     void SetAutoSize(bool state)
223     {
224         isAutoSize_ = state;
225     }
226 
227 #if ENABLE_FOCUS_MANAGER
228     /**
229      * @brief 设置组件是否拦截焦点.
230      *
231      * @param interceptFocus 是否拦截焦点.
232      * @since 5.0
233      * @version 3.0
234      */
SetInterceptFocus(bool interceptFocus)235     void SetInterceptFocus(bool interceptFocus)
236     {
237         isInterceptFocus_ = interceptFocus;
238     }
239 
240     /**
241      * @brief 获取组件是否拦截焦点.
242      *
243      * @return 是否为焦点.
244      * @since 5.0
245      * @version 3.0
246      */
IsInterceptFocus()247     bool IsInterceptFocus() const
248     {
249         return isInterceptFocus_;
250     }
251 #endif
252 
253     /**
254      * @brief Update the render tree
255      *
256      * @param targetView the view being added/removed or changed zIndex.
257      */
258     void UpdateRenderView(UIView* targetView);
259 
260 protected:
261     /**
262      * @brief Obtains the rectangle area of a new view group after being adaptive to the size of all child views.
263      *
264      * @return Returns the rectangle area of the new view group.
265      * @since 1.0
266      * @version 1.0
267      */
268     Rect GetAllChildRelativeRect() const;
269 
270     /**
271      * @brief Performs operations needed after a child view is added or removed.
272      *
273      * @since 1.0
274      * @version 1.0
275      */
OnChildChanged()276     virtual void OnChildChanged() {}
277 
278     /**
279      * @brief Indicates the pointer to the first child view of this view group.
280      */
281     UIView* childrenHead_;
282 
283     /**
284      * @brief Indicates the pointer to the first render child view of this view group.
285      */
286     UIView* childrenRenderHead_;
287 
288     /**
289      * @brief Indicates the pointer to the last child view of this view group.
290      */
291     UIView* childrenTail_;
292 
293     /**
294      * @brief Represents the number of child views.
295      */
296     uint16_t childrenNum_;
297 
298     /**
299      * @brief Specifies the sliding state of this view group.
300      */
301     bool isDragging_;
302 
303     /**
304      * @brief Specifies whether this view group is intercepted upon touch events.
305      */
306     bool disallowIntercept_;
307 
308     /**
309      * @brief Specifies whether the size of this view group is adaptive to that of all child views.
310      */
311     bool isAutoSize_;
312 
313 private:
314     void AutoResize();
315     void InsertRenderView(UIView* anchorView, UIView* anchorPreView, UIView* targetView);
316     void RemoveRenderView(UIView* targetView);
317 #if ENABLE_FOCUS_MANAGER
318     bool isInterceptFocus_ : 1;
319 #endif
320 };
321 } // namespace OHOS
322 #endif // GRAPHIC_LITE_UI_VIEW_GROUP_H
323