跳转到主要内容

滚动列表

滚动列表是可滚动的菜单,由若干项目和控件构成,这些项目和控件滚动到视图中时会进行动态更新。 与滚动列表中的项目交互时,滚动列表还能调用回调函数。

在模拟器中运行的滚动列表

控件组

滚动列表位于TouchGFX Designer中的容器控件组中。

TouchGFX Designer中的滚动列表

属性

TouchGFX Designer中滚动列表的属性。

属性组属性说明
名称控件的名称名称是TouchGFX Designer和代码中使用的唯一标识符
类型类型指定滚动列表方向为垂直方向或水平方向
位置XY 指定控件左上角相对于其父的位置。

WH 指定控件的宽度和高度。

锁定指定控件是否应锁定为其当前的X、Y、W和H。
如果锁定控件,还会禁止通过屏幕与控件进行交互。

可见 指定控件的可见性。 如果将控件标记为不可见,还会禁止通过屏幕与控件进行交互。
项目模板项目模板指定用作模板的CustomContainer。

选项数指定滚动列表中存在的项目数。
列表外观循环指定到达列表末尾后,滚动列表中的项目是否将循环。

项目对齐指定项目是否应该对齐。
如果对齐为False,则项目可随意移动。 如果对齐为True,项目将按位对齐,始终位于所选位置。

项目间距指定项目之间的间距。

填充前填充后 指定滚动列表中可见画板前后的距离偏移量。
动画缓动缓动选项指定动画使用的缓动方程。

Swipe Acc.Drag Acc. 指定滚动时的加速度。
Mixin可拖动 指定在运行时控件是否可拖动。

ClickListener 指定控件被点击时是否会调用回调函数。

MoveAnimator 指定控件是否可绘制 XY 值变化的动画。

项目模板

滚动列表中的项目基于名为“项目模板”的概念,项目模板属于CustomContainer,用作滚动列表中各项目图形元素的基础。 创建滚动列表之前,应创建自定义容器,为滚动列表提供项目模板。

创建滚动列表后,可在项目模板属性下选择CustomContainer。 指定项目模板会调整滚动列表大小,以适应所选自定义容器不在可滚动方向上的的尺寸属性(垂直滚动列表的宽度、水平滚动列表的高度)。 更改其他尺寸属性(垂直滚动列表的高度、水平滚动列表的宽度)决定了可见的项目数。

交互

下面的部分介绍了滚动列表支持的操作和触发条件。

操作

标准控件操作说明
移动控件随时间的推移将控件移动到新位置。
隐藏控件隐藏控件(将可见性设置为false)。
显示控件使隐藏的控件可见(将可见性设置为true)。

触发条件

滚动列表不会产生任何触发条件。

性能

滚动列表为Container类型,默认情况下不会出现在绘图链中。 因此,性能主要取决于子部件的绘图性能。

更多关于绘图性能的信息,请阅读常规UI组件性能部分。

示例

生成代码

在生成的视图基类的代码中,可以查看TouchGFX Designer是如何创建滚动列表的。

Screen1ViewBase.cpp
#include <gui_generated/screen1_screen/Screen1ViewBase.hpp>
#include "BitmapDatabase.hpp"

Screen1ViewBase::Screen1ViewBase() :
updateItemCallback(this, &Screen1ViewBase::updateItemCallbackHandler)
{
scrollList.setPosition(140, 10, 200, 252);
scrollList.setHorizontal(false);
scrollList.setCircular(false);
scrollList.setEasingEquation(touchgfx::EasingEquations::backEaseOut);
scrollList.setSwipeAcceleration(10);
scrollList.setDragAcceleration(10);
scrollList.setNumberOfItems(20);
scrollList.setPadding(0, 0);
scrollList.setSnapping(false);
scrollList.setDrawableSize(50, 2);
scrollList.setDrawables(scrollListListItems, updateItemCallback);

add(scrollList);
}

void Screen1ViewBase::setupScreen()
{
scrollList.initialize();
for (int i = 0; i < scrollListListItems.getNumberOfDrawables(); i++)
{
scrollListListItems[i].initialize();
}
}

void Screen1ViewBase::updateItemCallbackHandler(touchgfx::DrawableListItemsInterface* items, int16_t containerIndex, int16_t itemIndex)
{
if (items == &scrollListListItems)
{
touchgfx::Drawable* d = items->getDrawable(containerIndex);
TextContainer* cc = (TextContainer*)d;
scrollListUpdateItem(*cc, itemIndex);
}
}
Tip
可在用户代码中使用这些函数以及ScrollList类中提供的其他函数。 如果修改了控件的外观,记得调用 scrollList.invalidate() 以强制重绘。

用户代码

设置完滚动列表的图形元素及其属性后,可编写用户代码更新滚动列表中的项目。 下文给出了由TouchGFX Designer生成的 Screen1ViewBase 类的头文件:

ScreenViewBase.hpp
class ScreenViewBase : public touchgfx::View
{
public:
ScreenViewBase();
virtual ~ScreenViewBase() {}
virtual void setupScreen();

virtual void scrollListUpdateItem(CustomContainer& item, int16_t itemIndex)
{
// Override and implement this function in Screen
}

protected:
FrontendApplication& application() {
return *static_cast<FrontendApplication*>(Application::getInstance());
}
touchgfx::BoxWithBorder boxWithBorder;
touchgfx::ScrollList scrollList;
touchgfx::DrawableListItems<CustomContainer, 6> scrollListListItems;
private:
void updateItemCallbackHandler(DrawableListItemsInterface* items, int16_t containerIndex, int16_t itemIndex);
touchgfx::Callback<ScreenViewBase, DrawableListItemsInterface*, int16_t, int16_t> updateItemCallback;
};

TouchGFX Designer生成滚动列表代码时,会创建上文中突出显示的函数 scrollListUpdateItem,用户可使用此函数覆盖和更新滚动列表中的项目。 每当滚动列表中的项目需要更新时,都会调用此函数,因此,请先确保项目已更新,然后该项目才会变为可见状态。 scrollListUpdateItem 包含两个参数,用于标识正在更新的项目并用于对该项目进行更新。 参数 itemIndex 包含项目的索引值,该值用于标识正在更新的项目。 参数 item 是对CustomContainer对象的引用,该对象属于滚动列表中的可见项目。 更新参数 item 的图形会更新为滚动列表中可见项目的渲染。

下文给出了集成 scrollListUpdateItem 的示例:

Screen1View.hpp
#ifndef SCREEN1_VIEW_HPP
#define SCREEN1_VIEW_HPP

#include <gui_generated/screen1_screen/Screen1ViewBase.hpp>
#include <gui/screen1_screen/ScreenPresenter.hpp>

class Screen1View : public Screen1ViewBase
{
public:
Screen1View();
virtual ~Screen1View() {}
virtual void setupScreen();
virtual void tearDownScreen();

virtual void scrollListUpdateItem(CustomContainer& item, int16_t itemIndex);
protected:
};

#endif // SCREEN1_VIEW_HP
Screen1View.cpp
#include <gui/screen1_screen/Screen1View.hpp>

Screen1View::Screen1View()
{

}

void Screen1View::setupScreen()
{
Screen1ViewBase::setupScreen();
}

void Screen1View::tearDownScreen()
{
Screen1ViewBase::tearDownScreen();
}

void Screen1View::scrollListUpdateItem(CustomContainer& item, int16_t itemIndex)
{
item.setValue(itemIndex);
}

在头文件 Screen1View.hpp 中,会覆盖 scrollListUpdateItem 函数,随后会在 Screen1View.cpp 中实现该函数。

本例的目标是更新具有可见项目索引值的项目模板中的文本,与本部分开头给出的示例相似。 由于项目模板是基于CustomContainer的,因此会为CustomContainer创建一个 setValue 函数。 setValue函数能够获取 itemIndex 参数并更新项目模板中的文本。 为参数项调用setvalue会使项目更新其外观,从而会显示其索引值。

TouchGFX Designer示例

如需进一步了解滚动列表,请尝试在TouchGFX Designer中使用下列UI模板之一创建新应用:

TouchGFX Designer中的滚轮和列表示例UI模板

API参考