Developers Manual > Cocos2d-x > Modules > New UI > Containers

Usage of Container

GUI widgets can be divided into two general kinds- Normal Widget and Container Widget. Normal widgets are some common widgets such as Button, Text, Slider and TextField, etc. Container widgets are Layout, ScrollView and PageView, etc. Container widgets are special as they are widgets that can contain other widgets to enhance the user interface.

Layout (Panel)

Panel as primary container, it's the base to create UI by the CocoStudio editor. It's important to know Panel and its properties. The corresponding widget of Panel is named Layout.

In C++:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
   Layout* background = static_cast<Layout*>(root->getChildByName("background_Panel"));

        // Create the layout
        Layout* layout = Layout::create();
        layout->setContentSize(Size(280, 150));
        Size backgroundSize = background->getContentSize();
        layout->setPosition(Vec2((widgetSize.width - backgroundSize.width) / 2.0f +
                                  (backgroundSize.width - layout->getContentSize().width) / 2.0f,
                                  (widgetSize.height - backgroundSize.height) / 2.0f +
                                  (backgroundSize.height - layout->getContentSize().height) / 2.0f));
        _uiLayer->addChild(layout);

        Button* button = Button::create("cocosui/animationbuttonnormal.png", "cocosui/animationbuttonpressed.png");
        button->setPosition(Vec2(button->getContentSize().width / 2.0f,
                                  layout->getContentSize().height - button->getContentSize().height / 2.0f));
        layout->addChild(button);

        Button* titleButton = Button::create("cocosui/backtotopnormal.png", "cocosui/backtotoppressed.png");
        titleButton->setTitleText("Title Button");
        titleButton->setPosition(Vec2(layout->getContentSize().width / 2.0f, layout->getContentSize().height / 2.0f));
        layout->addChild(titleButton);

        Button* button_scale9 = Button::create("cocosui/button.png", "cocosui/buttonHighlighted.png");
        button_scale9->setScale9Enabled(true);
        button_scale9->setContentSize(Size(100.0f, button_scale9->getVirtualRendererSize().height));
        button_scale9->setPosition(Vec2(layout->getContentSize().width - button_scale9->getContentSize().width / 2.0f,
                                         button_scale9->getContentSize().height / 2.0f));

        layout->addChild(button_scale9);

In Lua:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
  local background = root:getChildByName("background_Panel")

    local layout = ccui.Layout:create()
    layout:setContentSize(cc.size(280, 150))
    local backgroundSize = background:getContentSize()
    layout:setPosition(cc.p((widgetSize.width - backgroundSize.width) / 2 +
                                (backgroundSize.width - layout:getContentSize().width) / 2,
                                (widgetSize.height - backgroundSize.height) / 2 +
                                (backgroundSize.height - layout:getContentSize().height) / 2))
    self._uiLayer:addChild(layout)

    local button = ccui.Button:create()
    button:setTouchEnabled(true)
    button:loadTextures("cocosui/animationbuttonnormal.png", "cocosui/animationbuttonpressed.png", "")
    button:setPosition(cc.p(button:getContentSize().width / 2, layout:getContentSize().height - button:getContentSize().height / 2))
    layout:addChild(button)

    local textButton = ccui.Button:create()
    textButton:setTouchEnabled(true)
    textButton:loadTextures("cocosui/backtotopnormal.png", "cocosui/backtotoppressed.png", "")
    textButton:setTitleText("Text Button")
    textButton:setPosition(cc.p(layout:getContentSize().width / 2, layout:getContentSize().height / 2))
    layout:addChild(textButton)

    local button_scale9 = ccui.Button:create()
    button_scale9:setTouchEnabled(true)
    button_scale9:loadTextures("cocosui/button.png", "cocosui/buttonHighlighted.png", "")
    button_scale9:setScale9Enabled(true)
    button_scale9:setContentSize(cc.size(100, button_scale9:getVirtualRendererSize().height))
    button_scale9:setPosition(cc.p(layout:getContentSize().width - button_scale9:getContentSize().width / 2, button_scale9:getContentSize().height / 2))
    layout:addChild(button_scale9) 

We created a layout widget and then added three widgets to it.

uipanel_test

We give a size of the layout by setting size value, but we don't get what we want because the color of the layout default is transparent. However, we can set color for this layout:

In C++:

1
2
    layout->setBackGroundColorType(BackGroundColorType::SOLID);
    layout->setBackGroundColor(Color3B(128, 128, 128));

In Lua:

1
2
 layout:setBackGroundColorType(ccui.LayoutBackGroundColorType.solid)
    layout:setBackGroundColor(cc.c3b(128, 128, 128))

uipanel_color

You can also set background image:

In C++:

1
    layout->setBackGroundImage("cocosgui/Hello.png");

In Lua:

1
    layout:setBackGroundImage("cocosui/Hello.png")

uipanel_background1

As shown above, we set the size and background image, but remember to call setClippingEnabled method to clip by size, if you forget to call this method you will see:

uipanel_background2

There are other ways to do the same thing:

In C++:

1
2
    layout->setBackGroundImageScale9Enabled(true);
    layout->setBackGroundImage("cocosgui/green_edit.png");

In Lua:

1
2
 layout:setBackGroundImageScale9Enabled(true)
    layout:setBackGroundImage("cocosui/green_edit.png")

uipanel_scale9

When using square images as background image, remember to enable this function.

UILayout has three modes to display color.

LayoutBackGroundColorType Desription
BackGroundColorType::NONE Transparent, no displaying color
BackGroundColorType::SOLID Solid, set displaying color
BackGroundColorType::GRADIENT Displaying gradient color

UIPanel Widget's Layout Strategies

Layout is for layout. Above we are just changing the background image. The table below shows you how to set the absolute position manually for other layout schemes:

LayoutType Description
Type::ABSOLUTE Absolute Layout Scheme
Type::VERTICAL Linear Vertical Scheme
Type::HORIZONTAL Linear Horizontal Scheme
Type::RELATIVE Relative Layout Scheme

In C++:

1
2
3
4
5
6
7
    layout->setLayoutType(Type::VERTICAL);

    // Another way 
    layout->setLayoutType(Type::HORIZONTAL);

    // Another way 
    layout->setLayoutType(Type::RELATIVE);

In Lua:

1
2
3
    layout:setLayoutType(ccui.LayoutType.VERTICAL)
    layout:setLayoutType(ccui.LayoutType.HORIZONTAL)
    layout:setLayoutType(ccui.LayoutType.RELATIVE)

Note: In addition to absolute layout scheme, if you set other scheme then UIPanel will ignore the position setting of the inside widget. You can use LayoutParameter to set position in this situation, the layout schemes provide serval parameters-LinearLayoutParameter and RelativeLayoutParameter. The following code shows how to combine these parameters and layout to design the UI.

In C++:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
      // Create the layout
        Layout* layout = Layout::create();
        layout->setLayoutType(LayoutType::VERTICAL);
        layout->setContentSize(Size(280, 150));
        Size backgroundSize = background->getContentSize();
        layout->setPosition(Vec2((widgetSize.width - backgroundSize.width) / 2.0f +
                                  (backgroundSize.width - layout->getContentSize().width) / 2.0f,
                                  (widgetSize.height - backgroundSize.height) / 2.0f +
                                  (backgroundSize.height - layout->getContentSize().height) / 2.0f));
        _uiLayer->addChild(layout);


        Button* button = Button::create("cocosui/animationbuttonnormal.png", "cocosui/animationbuttonpressed.png");
        layout->addChild(button);

        LinearLayoutParameter* lp1 = LinearLayoutParameter::create();
        button->setLayoutParameter(lp1);
        lp1->setGravity(LinearLayoutParameter::LinearGravity::CENTER_HORIZONTAL);
        lp1->setMargin(Margin(0.0f, 5.0f, 0.0f, 10.0f));


        Button* titleButton = Button::create("cocosui/backtotopnormal.png", "cocosui/backtotoppressed.png");
        titleButton->setTitleText("Title Button");
        layout->addChild(titleButton);

        LinearLayoutParameter* lp2 = LinearLayoutParameter::create();
        titleButton->setLayoutParameter(lp2);
        lp2->setGravity(LinearLayoutParameter::LinearGravity::CENTER_HORIZONTAL);
        lp2->setMargin(Margin(0.0f, 10.0f, 0.0f, 10.0f));


        Button* button_scale9 = Button::create("cocosui/button.png", "cocosui/buttonHighlighted.png");
        button_scale9->setScale9Enabled(true);
        button_scale9->setContentSize(Size(100.0f, button_scale9->getVirtualRendererSize().height));
        layout->addChild(button_scale9);

        LinearLayoutParameter* lp3 = LinearLayoutParameter::create();
        button_scale9->setLayoutParameter(lp3);
        lp3->setGravity(LinearLayoutParameter::LinearGravity::CENTER_HORIZONTAL);
        lp3->setMargin(Margin(0.0f, 10.0f, 0.0f, 10.0f));

In Lua:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
local layout = ccui.Layout:create()
    layout:setLayoutType(ccui.LayoutType.VERTICAL)
    layout:setContentSize(cc.size(280, 150))
    local backgroundSize = background:getContentSize()
    layout:setPosition(cc.p((widgetSize.width - backgroundSize.width) / 2 +
                                (backgroundSize.width - layout:getContentSize().width) / 2,
                                (widgetSize.height - backgroundSize.height) / 2 +
                                (backgroundSize.height - layout:getContentSize().height) / 2))
    self._uiLayer:addChild(layout)

    local button = ccui.Button:create()
    button:setTouchEnabled(true)
    button:loadTextures("cocosui/animationbuttonnormal.png", "cocosui/animationbuttonpressed.png", "")
    layout:addChild(button)

    local lp1 = ccui.LinearLayoutParameter:create()
    button:setLayoutParameter(lp1)
    lp1:setGravity(ccui.LinearGravity.centerHorizontal)
    lp1:setMargin({ left = 0, top = 5, right = 0, bottom = 10 })


    local textButton = ccui.Button:create()
    textButton:setTouchEnabled(true)
    textButton:loadTextures("cocosui/backtotopnormal.png", "cocosui/backtotoppressed.png", "")
    textButton:setTitleText("Text Button")
    layout:addChild(textButton)

    local lp2 = ccui.LinearLayoutParameter:create()
    textButton:setLayoutParameter(lp2)
    lp2:setGravity(ccui.LinearGravity.centerHorizontal)
    lp2:setMargin({left = 0, top = 10, right = 0, bottom  = 10} )


    local button_scale9 = ccui.Button:create()
    button_scale9:setTouchEnabled(true)
    button_scale9:loadTextures("cocosui/button.png", "cocosui/buttonHighlighted.png", "")
    button_scale9:setScale9Enabled(true)
    button_scale9:setContentSize(cc.size(100, button_scale9:getVirtualRendererSize().height))
    layout:addChild(button_scale9)

    local lp3 = ccui.LinearLayoutParameter:create()
    button_scale9:setLayoutParameter(lp3)
    lp3:setGravity(ccui.LinearGravity.centerHorizontal)
    lp3:setMargin({ left = 0, top = 10, right = 0, bottom  = 10 } )

uipanel_vertical

Setting three parameters for layout - LinearLayoutParameter, Gravity and Margin, then set layout parameters for three UIPanel's inner widgets.

Here we used Linear Vertical scheme, but every Gravity set as LinearLayoutParameter::LinearGravity::CENTER_HORIZONTAL that is displaying as center horizontally. Margin shows the spacing around the edges, notice that the value of lp2 is UIMargin(20, 20, 0, 5), which means the spacing from left, top, right and button. When left spacing is 20 you can see textButton's position has little offset to right. Except for the direction, other setting of layout vertical scheme is same as horizontal scheme. And two schemes are called Linear Layout, they using the same parameters. Checking out following layout:

In C++:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
   // Create the layout
        Layout* layout = Layout::create();
        layout->setLayoutType(LayoutType::RELATIVE);
        layout->setContentSize(Size(280, 150));
        layout->setBackGroundColorType(Layout::BackGroundColorType::SOLID);
        layout->setBackGroundColor(Color3B::GREEN);
        Size backgroundSize = background->getContentSize();
        layout->setPosition(Vec2((widgetSize.width - backgroundSize.width) / 2.0f +
                                (backgroundSize.width - layout->getContentSize().width) / 2.0f,
                                (widgetSize.height - backgroundSize.height) / 2.0f +
                                (backgroundSize.height - layout->getContentSize().height) / 2.0f));
        _uiLayer->addChild(layout);

        // top left
        Button* button_TopLeft = Button::create("cocosui/animationbuttonnormal.png",
                                                "cocosui/animationbuttonpressed.png");
        layout->addChild(button_TopLeft);

        RelativeLayoutParameter* rp_TopLeft = RelativeLayoutParameter::create();
        rp_TopLeft->setAlign(RelativeLayoutParameter::RelativeAlign::PARENT_TOP_LEFT);
        button_TopLeft->setLayoutParameter(rp_TopLeft);


        // top center horizontal
        Button* button_TopCenter = Button::create("cocosui/animationbuttonnormal.png",
                                                  "cocosui/animationbuttonpressed.png");
        layout->addChild(button_TopCenter);

        RelativeLayoutParameter* rp_TopCenter = RelativeLayoutParameter::create();
        rp_TopCenter->setAlign(RelativeLayoutParameter::RelativeAlign::PARENT_TOP_CENTER_HORIZONTAL);
        button_TopCenter->setLayoutParameter(rp_TopCenter);


        // top right
        Button* button_TopRight = Button::create("cocosui/animationbuttonnormal.png",
                                                 "cocosui/animationbuttonpressed.png");
        layout->addChild(button_TopRight);

        RelativeLayoutParameter* rp_TopRight = RelativeLayoutParameter::create();
        rp_TopRight->setAlign(RelativeLayoutParameter::RelativeAlign::PARENT_TOP_RIGHT);
        button_TopRight->setLayoutParameter(rp_TopRight);


        // left center
        Button* button_LeftCenter = Button::create("cocosui/animationbuttonnormal.png",
                                                   "cocosui/animationbuttonpressed.png");
        layout->addChild(button_LeftCenter);

        RelativeLayoutParameter* rp_LeftCenter = RelativeLayoutParameter::create();
        rp_LeftCenter->setAlign(RelativeLayoutParameter::RelativeAlign::PARENT_LEFT_CENTER_VERTICAL);
        button_LeftCenter->setLayoutParameter(rp_LeftCenter);


        // center
        Button* buttonCenter = Button::create("cocosui/animationbuttonnormal.png",
                                              "cocosui/animationbuttonpressed.png");
        layout->addChild(buttonCenter);

        RelativeLayoutParameter* rpCenter = RelativeLayoutParameter::create();
        rpCenter->setAlign(RelativeLayoutParameter::RelativeAlign::CENTER_IN_PARENT);
        buttonCenter->setLayoutParameter(rpCenter);


        // right center
        Button* button_RightCenter = Button::create("cocosui/animationbuttonnormal.png",
                                                    "cocosui/animationbuttonpressed.png");
        layout->addChild(button_RightCenter);

        RelativeLayoutParameter* rp_RightCenter = RelativeLayoutParameter::create();
        rp_RightCenter->setAlign(RelativeLayoutParameter::RelativeAlign::PARENT_RIGHT_CENTER_VERTICAL);
        button_RightCenter->setLayoutParameter(rp_RightCenter);


        // left bottom
        Button* button_LeftBottom = Button::create("cocosui/animationbuttonnormal.png",
                                                   "cocosui/animationbuttonpressed.png");
        layout->addChild(button_LeftBottom);

        RelativeLayoutParameter* rp_LeftBottom = RelativeLayoutParameter::create();
        rp_LeftBottom->setAlign(RelativeLayoutParameter::RelativeAlign::PARENT_LEFT_BOTTOM);
        button_LeftBottom->setLayoutParameter(rp_LeftBottom);


        // bottom center
        Button* button_BottomCenter = Button::create("cocosui/animationbuttonnormal.png",
                                                     "cocosui/animationbuttonpressed.png");
        layout->addChild(button_BottomCenter);

        RelativeLayoutParameter* rp_BottomCenter = RelativeLayoutParameter::create();
        rp_BottomCenter->setAlign(RelativeLayoutParameter::RelativeAlign::PARENT_BOTTOM_CENTER_HORIZONTAL);
        button_BottomCenter->setLayoutParameter(rp_BottomCenter);


        // right bottom
        Button* button_RightBottom = Button::create("cocosui/animationbuttonnormal.png",
                                                    "cocosui/animationbuttonpressed.png");
        layout->addChild(button_RightBottom);

        RelativeLayoutParameter* rp_RightBottom = RelativeLayoutParameter::create();
        rp_RightBottom->setAlign(RelativeLayoutParameter::RelativeAlign::PARENT_RIGHT_BOTTOM);
        button_RightBottom->setLayoutParameter(rp_RightBottom);

uipanel_relative

Here created three layout properties, and setted different Align parameters.

ScrollView

In addition to layout container, scroll view is always been used, it can enlarge the displaying widget and it's very useful when content elements increased. You can set different direction as you like.

In C++:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
   // Create the scrollview by vertical
        ui::ScrollView* scrollView = ui::ScrollView::create();
        scrollView->setContentSize(Size(280.0f, 150.0f));
        Size backgroundSize = background->getContentSize();
        scrollView->setPosition(Vec2((widgetSize.width - backgroundSize.width) / 2.0f +
                               (backgroundSize.width - scrollView->getContentSize().width) / 2.0f,
                               (widgetSize.height - backgroundSize.height) / 2.0f +
                               (backgroundSize.height - scrollView->getContentSize().height) / 2.0f));
        _uiLayer->addChild(scrollView);

        ImageView* imageView = ImageView::create("cocosui/ccicon.png");

        float innerWidth = scrollView->getContentSize().width;
        float innerHeight = scrollView->getContentSize().height + imageView->getContentSize().height;

        scrollView->setInnerContainerSize(Size(innerWidth, innerHeight));                

        Button* button = Button::create("cocosui/animationbuttonnormal.png", "cocosui/animationbuttonpressed.png");
        button->setPosition(Vec2(innerWidth / 2.0f, scrollView->getInnerContainerSize().height - button->getContentSize().height / 2.0f));
        scrollView->addChild(button);

        Button* titleButton = Button::create("cocosui/backtotopnormal.png", "cocosui/backtotoppressed.png");
        titleButton->setTitleText("Title Button");
        titleButton->setPosition(Vec2(innerWidth / 2.0f, button->getBottomBoundary() - button->getContentSize().height));
        scrollView->addChild(titleButton);

        Button* button_scale9 = Button::create("cocosui/button.png", "cocosui/buttonHighlighted.png");
        button_scale9->setScale9Enabled(true);
        button_scale9->setContentSize(Size(100.0f, button_scale9->getVirtualRendererSize().height));
        button_scale9->setPosition(Vec2(innerWidth / 2.0f, titleButton->getBottomBoundary() - titleButton->getContentSize().height));
        scrollView->addChild(button_scale9);

        imageView->setPosition(Vec2(innerWidth / 2.0f, imageView->getContentSize().height / 2.0f));
        scrollView->addChild(imageView);   

In Lua:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
  local scrollView = ccui.ScrollView:create()
    scrollView:setTouchEnabled(true)
    scrollView:setContentSize(cc.size(280, 150))        
    local backgroundSize = background:getContentSize()
    scrollView:setPosition(cc.p((widgetSize.width - backgroundSize.width) / 2 +
                               (backgroundSize.width - scrollView:getContentSize().width) / 2,
                               (widgetSize.height - backgroundSize.height) / 2 +
                               (backgroundSize.height - scrollView:getContentSize().height) / 2))
    self._uiLayer:addChild(scrollView)

    local imageView = ccui.ImageView:create()
    imageView:loadTexture("cocosui/ccicon.png")

    local innerWidth = scrollView:getContentSize().width
    local innerHeight = scrollView:getContentSize().height + imageView:getContentSize().height

    scrollView:setInnerContainerSize(cc.size(innerWidth, innerHeight))                

    local button = ccui.Button:create()
    button:setTouchEnabled(true)
    button:loadTextures("cocosui/animationbuttonnormal.png", "cocosui/animationbuttonpressed.png", "")
    button:setPosition(cc.p(innerWidth / 2, scrollView:getInnerContainerSize().height - button:getContentSize().height / 2))
    scrollView:addChild(button)

    local textButton = ccui.Button:create()
    textButton:setTouchEnabled(true)
    textButton:loadTextures("cocosui/backtotopnormal.png", "cocosui/backtotoppressed.png", "")
    textButton:setTitleText("Text Button")
    textButton:setPosition(cc.p(innerWidth / 2, button:getBottomBoundary() - button:getContentSize().height))
    scrollView:addChild(textButton)

    local button_scale9 = ccui.Button:create()
    button_scale9:setTouchEnabled(true)
    button_scale9:setScale9Enabled(true)
    button_scale9:loadTextures("cocosui/button.png", "cocosui/buttonHighlighted.png", "")
    button_scale9:setContentSize(cc.size(100, button_scale9:getVirtualRendererSize().height))
    button_scale9:setPosition(cc.p(innerWidth / 2, textButton:getBottomBoundary() - textButton:getContentSize().height))
    scrollView:addChild(button_scale9)

    imageView:setPosition(cc.p(innerWidth / 2, imageView:getContentSize().height / 2))
    scrollView:addChild(imageView)

uiscrollview_vertical

As the image shows, we created a ScrollView widget and added some inner elements to it. The content is too much that out of the display area, in this situation we can drag the view up and down to show the content.

Note: imageView's position is set outside of scrollview, besides you can call the scrollview's setInnerContainerSize method resize the content displaying area. Checking boundary when dragging.

If horizontal drag is set, then we just need to set InnerContainerSize's width larger than widget's, height equal to widget's. In this way you can drag it horizontally.

ListView

ListView inherited from ScrollView, so ScrollView's characters also can be shown in ListView. Let's see the difference between ListView and ScrollView:

In C++:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
    ListView* lv = UIListView::create();
    Button* model = Button::create();
    model->loadTextures("cocosgui/animationbuttonnormal.png", "cocosgui/animationbuttonpressed.png", "");
    lv->setItemModel(model);

    for (int i=0; i<20; i++)
    {
        lv->pushBackDefaultItem();
    }
    lv->setItemsMargin(10);
    lv->setGravity(ListView::Gravity::CENTER_HORIZONTAL);
    lv->setSize(Size(100, 100));
    lv->setBackGroundColorType(LAYOUT_COLOR_SOLID);
    lv->setBackGroundColor(Color3B::GREEN);
    lv->setPosition(Point(100, 100));
    m_pUiLayer->addWidget(lv);

In Lua:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
  local listView = ccui.ListView:create()
    -- set list view ex direction
    listView:setDirection(ccui.ScrollViewDir.vertical)
    listView:setBounceEnabled(true)
    listView:setBackGroundImage("cocosui/green_edit.png")
    listView:setBackGroundImageScale9Enabled(true)
    listView:setContentSize(cc.size(240, 130))
    listView:setPosition(cc.p((widgetSize.width - backgroundSize.width) / 2.0 +
                              (backgroundSize.width - listView:getContentSize().width) / 2.0,
                              (widgetSize.height - backgroundSize.height) / 2.0 +
                              (backgroundSize.height - listView:getContentSize().height) / 2.0))
    listView:addEventListener(listViewEvent)
    listView:addScrollViewEventListener(scrollViewEvent)
    self._uiLayer:addChild(listView)


    -- create model
    local default_button = ccui.Button:create("cocosui/backtotoppressed.png", "cocosui/backtotopnormal.png")
    default_button:setName("Title Button")

    local default_item = ccui.Layout:create()
    default_item:setTouchEnabled(true)
    default_item:setContentSize(default_button:getContentSize())
    default_button:setPosition(cc.p(default_item:getContentSize().width / 2.0, default_item:getContentSize().height / 2.0))
    default_item:addChild(default_button)

    --set model
    listView:setItemModel(default_item)

    --add default item
    local count = table.getn(array)
    for i = 1,math.floor(count / 4) do
        listView:pushBackDefaultItem()
    end

uilistview_vertical

As shown above, it's the implementation like ScrollView. There are twenty buttons can be dragged, by setting every element's space with ItemsMargin and Gravity make them displaying in the center horizontally.

lv->setItemModel(model) set Default Item for ListView, then added twenty times this Default Item by a for loop. Notice that it doesn't mean the same model has been added twenty times but there are twenty new object which are the clone of the original model.

pushBackDefaultItem() is not the only item that can be added to ListView, there are others:

Method Description
pushBackDefaultItem() Add a Default Item
insertDefaultItem(int index) Insert a sorted Default Item
pushBackCustomItem(UIWidget* item) Add a new Item
insertCustomItem(UIWidget* item, int index) Insert a new Item

Some method to add Item already described in above table, now introduce you some delete and get method:

Method Description
removeItem(int index) Remove a Item
removeLastItem() Remove the last Item
getItem(unsigned int index) Get a Item by Index
getItems() Get all the Items and return Array
getIndex(UIWidget *item) Get a Item's Index

PageView

We talked about ScrollView and some widget can display list, still PageView can display entire page one time. Moreover, it can auto align-just like when you turning the over page it will help you done it.

In C++:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
    // Create the page view
        PageView* pageView = PageView::create();
        pageView->setContentSize(Size(240.0f, 130.0f));
        Size backgroundSize = background->getContentSize();
        pageView->setPosition(Vec2((widgetSize.width - backgroundSize.width) / 2.0f +
                                  (backgroundSize.width - pageView->getContentSize().width) / 2.0f,
                                  (widgetSize.height - backgroundSize.height) / 2.0f +
                                  (backgroundSize.height - pageView->getContentSize().height) / 2.0f));

        pageView->removeAllPages();

        int pageCount = 4;
        for (int i = 0; i < pageCount; ++i)
        {
            Layout* layout = Layout::create();
            layout->setContentSize(Size(240.0f, 130.0f));

            ImageView* imageView = ImageView::create("cocosui/scrollviewbg.png");
            imageView->setScale9Enabled(true);
            imageView->setContentSize(Size(240, 130));
            imageView->setPosition(Vec2(layout->getContentSize().width / 2.0f, layout->getContentSize().height / 2.0f));
            layout->addChild(imageView);

            Text* label = Text::create(StringUtils::format("page %d",(i+1)), "fonts/Marker Felt.ttf", 30);
            label->setColor(Color3B(192, 192, 192));
            label->setPosition(Vec2(layout->getContentSize().width / 2.0f, layout->getContentSize().height / 2.0f));
            layout->addChild(label);

            pageView->insertPage(layout,i);
        }

        pageView->removePageAtIndex(0);
        pageView->scrollToPage(pageCount-2);

        pageView->addEventListener(CC_CALLBACK_2(UIPageViewTest::pageViewEvent, this));

        _uiLayer->addChild(pageView);

In Lua:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 local pageView = ccui.PageView:create()
    pageView:setTouchEnabled(true)
    pageView:setContentSize(cc.size(240, 130))
    local backgroundSize = background:getContentSize()
    pageView:setPosition(cc.p((widgetSize.width - backgroundSize.width) / 2 +
                                  (backgroundSize.width - pageView:getContentSize().width) / 2,
                                  (widgetSize.height - backgroundSize.height) / 2 +
                                  (backgroundSize.height - pageView:getContentSize().height) / 2))

    for i = 1 , 3 do
        local layout = ccui.Layout:create()
        layout:setContentSize(cc.size(240, 130))

        local imageView = ccui.ImageView:create()
        imageView:setTouchEnabled(true)
        imageView:setScale9Enabled(true)
        imageView:loadTexture("cocosui/scrollviewbg.png")
        imageView:setContentSize(cc.size(240, 130))
        imageView:setPosition(cc.p(layout:getContentSize().width / 2, layout:getContentSize().height / 2))
        layout:addChild(imageView)

        local label = ccui.Text:create()
        local pageInfo = string.format("page %d", i)
        label:setString(pageInfo)
        label:setFontName(font_UIPageViewTest)
        label:setFontSize(30)
        label:setColor(cc.c3b(192, 192, 192))
        label:setPosition(cc.p(layout:getContentSize().width / 2, layout:getContentSize().height / 2))
        layout:addChild(label)

        pageView:addPage(layout)

    end 

    local function pageViewEvent(sender, eventType)
        if eventType == ccui.PageViewEventType.turning then
            local pageView = sender
            local pageInfo = string.format("page %d " , pageView:getCurPageIndex() + 1)
            self._displayValueLabel:setString(pageInfo)
        end
    end 

    pageView:addEventListener(pageViewEvent)

    self._uiLayer:addChild(pageView)

uipageview

As shown, a PageView object created and size is "Size(240, 130)", which is display area. We added three same Layout and each of them has the same size "Size(240, 130)" so PageView can display the entire content of a Item one time. You can added what you need in Layout, then add a page by pageView->addPage(layout). You should remember you have to add Layout object or its derived class object.

Although PageView implemented scroll, it is not inherited from ScrollView but Layout. So does ScrollView.

Every single widget make a GUI scene, the container is the skeleton, according to its layout to reach out expectation. Using Panel, ScrollView, ListView and PageView can make a better and friendly GUI.

uipanel_gradient.png (95 kB) owen, 2014-04-02 07:10

uipanel_relative.png (91.4 kB) owen, 2014-04-02 07:10

uipanel_scale9.png (92.8 kB) owen, 2014-04-02 07:10

uipanel_test.png (91.1 kB) owen, 2014-04-02 07:10

uilistview_vertical.png (96.3 kB) owen, 2014-04-02 07:10

uipageview.png (97.1 kB) owen, 2014-04-02 07:10

uipanel_background1.png (121.6 kB) owen, 2014-04-02 07:10

uipanel_background2.png (115.3 kB) owen, 2014-04-02 07:10

uipanel_vertical.png (91.7 kB) owen, 2014-04-02 07:10

uipanel_color.png (91.5 kB) owen, 2014-04-02 07:10

uipanel_vertical.png (91.7 kB) owen, 2014-04-02 07:10

uiscrollview_vertical.png (101.5 kB) owen, 2014-04-02 07:10

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.