development-guidelines-on-container-components.md

# Development Guidelines on Container Components
Container components are capable of containing UI components and inherit from **UIViewGroup**. Components that are commonly used and need to contain child components are placed in the container class inheritance structure. For example, you need to call the **Add** function to add information such as time statistics and icons to **UIAnalogClock**.
**Figure 1** Structure of a common container component
The **RootView**, **UIAbstractScroll**, and **UIPicker** components inherit from **UIViewGroup**, and the **UIList**, **UIScrollView**, and **UISwipeView** components inherit from **UIAbstractScroll**.
## UIViewGroup
## When to Use
**UIViewGroup** is a base class for container components. For example, you can call the functions in this class to add, remove, and insert container components. Also, you can call the **Add** function to add child components for a container component. You need to set the position information for child components in a common container component. The position information is the coordinates relative to those of their parent component. The following figure shows the component tree structure.
**Figure 2** Component tree structure
As shown in the figure, the container component **ViewGroup1** and the component **View1** are added to **rootView**, the component **View2** and the container component **ViewGroup2** are added to **ViewGroup1**, and then the component **View3** \(as a sibling of **View1**\) is also added to **ViewGroup1**.
- Rendering: During rendering of a container component, you need to call the **OnDraw** function on all its child components to update them.
- Coordinates: As the position information of child components is the coordinates relative to those of their parent components, the system calculates and displays the absolute coordinates of child components during rendering.
- Tree structure traversing: The **UIViewGroup** class provides the functions below to traverse, search for, and manage the component tree.
## Available APIs
**Table 1** Available functions in ViewGroup

Function	Description
virtual void Add(UIView* view)	Adds a child component.
virtual void Insert(UIView* prevView, UIView* insertView)	Inserts a child component.
virtual void Remove(UIView* view)	Removes a child component.
virtual void RemoveAll()	Removes all child components.
virtual void GetTargetView(const Point& point, UIView** last)	Obtains the target view.
virtual void MoveChildByOffset(int16_t x, int16_t y)	Moves a child component by a specified offset.
UIView* GetChildrenHead() const	Obtains the first child view in a view group.
UIView* GetChildrenTail() const	Obtains the last child view in a view group.
virtual UIView* GetChildById(const char* id) const override	Obtains a child view based on its ID.

## How to Develop
1. Create **ULLabelButton** instances and set their coordinates.
```
UILabelButton* btn1 = new UILabelButton();
btn1->SetPosition(0, 0, 100, 50);
btn1->SetText("btn1");

UILabelButton* btn2 = new UILabelButton();
btn2->SetPosition(50, 50, 100, 50);
btn2->SetText("btn2");

UILabelButton* btn3 = new UILabelButton();
btn3->SetPosition(100, 100, 100, 50);
btn3->SetText("btn3");
```
2. Create a **UIViewGroup** instance and set its coordinates.
```
UIViewGroup* group = new UIViewGroup();
group->SetPosition(0, 0, 300, 300);
```
3. Add the **ULLabelButton** instances to **UIViewGroup**.
```
group->Add(btn1);
group->Add(btn2);
group->Add(btn3);
```
4. The following figure shows the effect of adding view instances to a **ViewGroup**.
**Figure 3** Effect of adding view instances to a ViewGroup
## UIScrollView
## When to Use
**UIScrollView** provides scrolling container components, which enable child components to scroll upwards, downwards, leftwards, and rightwards upon a touch event. This class also supports horizontal and vertical cursor display.
## Available APIs
**Table 2** Available functions in ScrollView

Function	Description
void ScrollBy(int16_t xDistance, int16_t yDistance)	Scrolls a view.
void SetScrollbarWidth(uint8_t width)	Sets the scrollbar width.
void SetHorizontalScrollState(bool state)	Sets the horizontal scrolling state.
bool GetHorizontalScrollState() const	Checks whether horizontal scrolling is allowed.
void SetVerticalScrollState(bool state)	Sets the vertical scrolling state.
bool GetVerticalScrollState() const	Checks whether vertical scrolling is allowed.
void SetXScrollBarVisible(bool state)	Sets whether the x-axis scrollbar is visible.
void SetYScrollBarVisible(bool state)	Sets whether the y-axis scrollbar is visible.
void RegisterScrollListener(OnScrollListener* scrollListener)	Registers the scrolling callback class.
void RefreshScrollBar()	Refreshes the scrollbar.
virtual void OnScrollStart() {}	Called when scrolling starts.
virtual void OnScrollEnd() {}	Called when scrolling ends.
uint8_t GetScrollState() const	Obtains the scrolling state.
void SetScrollState(uint8_t state)	Sets the scrolling state.

## How to Develop
Add two buttons as child components and display horizontal and vertical cursors.
```
scrollView* scroll = new UIScrollView();
scroll->SetStyle(STYLE_BACKGROUND_COLOR, Color::Red().full);
scroll->SetPosition(0,0, 200, 200);
scroll->SetXScrollBarVisible(true);
scroll->SetYScrollBarVisible(true);
UILabelButton* button1 = new UILabelButton();
button1->SetText("button1");
button1->SetPosition(0, 0, 300, 300);
UILabelButton* button2 = new UILabelButton();
button2->SetText("button2");
button2->SetPosition(0, 300, 300, 300);
scroll->Add(button1);
scroll->Add(button2);
```
**Figure 4** Scrolling effect in both horizontal and vertical directions