UIKit 非容器类组件

非容器类组件

UIImageView

UIImageView用于展示图片。

须知：

1. 使用时需注意AutoEnable和ResizeMode属性设置顺序，建议AutoEnable在ResizeMode之前进行设置。
2. UIImageView背景不透明度建议调整为0。

表 1 UIImageView核心函数

函数	介绍
void SetSrc(const char* src)	通过路径来设置图片。
void SetSrc(const ImageInfo* src)	设置组件图片信息。
void SetAutoEnable(bool enable)	设置组件自适应图片。
void SetBlurLevel(BlurLevel level)	设置旋转或缩放此图像时的模糊级别。
void SetResizeMode(ImageResizeMode mode)	设置图片缩放模式（平铺、填充、保持宽高比）。 • 在AutoEnable为true时，SetResizeMode()不生效。 • 在AutoEnable为false时，需要先设置宽高，再设置SetResizeMode()。
void SetHeight(int16_t height) override	设置组件的高度。
void SetWidth(int16_t width) override	设置组件的宽度。

UIImageAnimator

UIImageAnimator组件继承自UIImageView，主要用于播放序列帧。

表 1 UIImageAnimator核心函数

函数	介绍
void SetImageAnimatorSrc(const ImageAnimatorInfo imageSrc[], uint8_t imageNum, uint16_t timeOfUpdate)	设置序列帧图源信息以及更新时间，单位：ms。 注意：调用该接口时，需要将对应参数内部数据填充完整，禁止先传递地址，再填充数据。
void SetImageAnimatorSrc(const ImageAnimatorInfo imageSrc[], uint8_t imageNum)	设置序列帧图源信息。 注意：调用该接口时，需要将对应参数内部数据填充完整，禁止先传递地址，再填充数据。
void SetTimeOfUpdate(uint16_t timeOfUpdate)	设置更新时间，单位：ms。 该值将会被除以DEFAULT_TASK_PERIOD，从而转换为更新周期。
uint16_t GetTimeOfUpdate() const	获取更新时间。
const ImageAnimatorInfo* GetImageAnimatorSrc() const	获取序列帧图源信息。
uint8_t GetImageAnimatorImageNum() const	获取序列帧图源数量。
void SetSizeFixed(bool fixed)	设置序列帧图片大小是否保持一致。如果不一致，则每张图片按照各自设置的宽高显示。
bool IsSizeFixed() const	获取序列帧图片大小是否保持一致。
void SetRepeat(bool repeat)	设置是否重复播放。
bool IsRepeat() const	获取是否重复播放。
void SetRepeatTimes(uint32_t times)	设置重复播放次数。
uint32_t GetRepeatTimes() const	获取重复播放次数。
uint8_t GetState() const	获取播放状态。
void SetReverse(bool reverse)	设置是否倒放。
bool IsReverse() const	获取是否倒放。
void SetFillMode(bool fillMode)	设置图片填充模式。
bool GetFillMode() const	获取图片填充模式。
void Start()	启动序列帧动画。
void Stop()	停止序列帧动画。
void Pause()	暂停序列帧动画。
void Resume()	继续序列帧动画。
void SetAnimatorStopListener(AnimatorStopListener* listener)	设置序列帧停止监听。

说明： 父控件为可滑动控件时，必需调用SetSizeFixed（True）。

UILabel

UILabel组件主要用于展示文字。

须知： 在设置为LINE_BREAK_MARQUEE模式下，最小的滚动像素为1。即在设置滚动速度为0时，不是停止状态。

表 1 UILabel核心函数

函数	介绍
void SetText(const char* text)	设置展示文本内容。 参数：要展示的字符串
void SetLineBreakMode(const uint8_t lineBreakMode)	设置展示模式。例如是否包裹内容展示，是否换行等，具体请参考UILabel::LineBreakMode。
void SetTextColor(ColorType color)	设置文字颜色。
void SetAlign(UITextLanguageAlignment horizontalAlign, UITextLanguageAlignment verticalAlign = TEXT_ALIGNMENT_TOP)	设置对齐方式。
void SetDirect(UITextLanguageDirect direct)	设置文本展示方向。
void SetFontId(uint8_t fontId)	设置点阵字库ID。
void SetFont(const char* name, uint8_t size)	设置矢量字体和大小。 支持仅设置字体大小，字库name设置为空；常用于多语言场景，文本通过子类提供的接口SetTextId来配置。
void SetRollStartPos(int16_t pos)	设置字体滚动位置。
void SetWidth(int16_t width) override	设置当前组件的宽度。
void SetHeight(int16_t height) override	设置当前组件的高度。
void SetMarqueeBlankNum(uint16_t size)	设置文本循环滚动间隔的空白字符数量（仅作用于LineBreakMode = MARQUEE时）。

UILabelExt

UILabelExt继承于UILabel，支持文本语言切换以及复杂语系的文本整形。

表 1 UILabelExt核心函数

函数	描述
void SetTextId(uint16_t textId)	设置TextId。 • 参数：uint16_t textId • 返回值：void
void ForceResetText() override	强制根据控件内部的TextId设置文本内容。 • 参数：N/A • 返回值：void

UIButton

UIButton是可点击的按钮，用户可以通过函数设置图片以此改变默认展示效果。

表 1 UIButton核心函数

函数	介绍
void SetImageSrc(const char defaultImgSrc, const char triggeredImgSrc)	设置UIButton默认展示的图片和点击后展示的图片。 参数：图片文件路径。
void SetImageSrc(const ImageInfo defaultImgSrc, const ImageInfo triggeredImgSrc)	设置UIButton默认展示的图片和点击后展示的图片，ImageInfo主要用于加载系统内置资源。 参数：传入的ImageInfo。
void SetImagePosition(const int16_t x, const int16_t y)	设置资源图片相对于控件的位置。
void Disable()	UIButton不可点击。
void Enable()	恢复UIButton可点击。
void SetStateForStyle(ButtonState state)	设置样式状态。非当前状态，而是即将要设置的样式对应的状态。
void SetStyle(uint8_t key, int64_t value) override	设置当前style对应属性的样式。
void SetStyleForState(uint8_t key, int64_t value, ButtonState state)	定制对应状态的样式。
void SetHeight(int16_t height)	设置组件高度。
void SetWidth(int16_t width)	设置组件宽度。

UILabelButtonExt

UILabelButtonExt继承于UILabelButton，支持文本语言切换以及整形。

表 1 UILabelButtonExt核心函数

函数	描述
void SetTextId(uint16_t textId)	设置TextId。 • 参数：uint16_t textId • 返回值：void
void ForceResetText() override	强制根据控件内部的TextId设置文本内容。 • 参数：N/A • 返回值：void

UILabelButton

UILabelButton是展示文字的按钮。该组件继承于UIButton，事件监听可以使用UIButton的函数设置监听器。

表 1 UILabelButton核心函数

函数	介绍
void SetText(const char* text)	为组件设置文字。
const char* GetText() const	获取组件当前设置的文字。
void SetLabelPosition(int16_t x, int16_t y)	设置文字在组件位置。
Point GetLabelPosition() const	获取文字在组件位置。
void SetAlign(UITextLanguageAlignment align)	设置文字在组件中的对齐方式。
void SetDirect(UITextLanguageDirect direct)	设置文字在组件中的方向。
void SetTextColor(ColorType color)	设置文字颜色。
void SetFont(const char* name, uint8_t size)	设置字体和字体大小。
void SetLabelStyle(uint8_t key, int64_t value)	设置标签样式。

UICheckBox

UICheckBox常用来表示状态开关，包括选中和非选择状态。具体使用流程请参考示例“/src/ohos/foundation/arkui/ui_lite/test/uitest/test_button/ui_test_button.cpp”。

表 1 UICheckBox核心函数

函数	介绍
Void SetOnChangeListener(OnChangeListener* onStateChangeListener)	为UICheckBox设置监听器，在状态改变时回调监听器的OnChange函数。
bool OnClickEvent(const ClickEvent& event) override	执行点击事件。
virtual void SetImages(const char selectedImageSrc, const char unselectedImageSrc)	通过图片路径设置选中和不选择状态的图片。
virtual void SetImages(const ImageInfo selectedImageSrc, const ImageInfo unselectedImageSrc)	通过ImageInfo设置选中和不选择状态的图片。
UICheckBoxState GetState() const	获取当前状态。
void SetState(UICheckBoxState state, bool needAnimater = false)	设置状态以及状态改变是否触发动效。
void SetSelectedStateColor(ColorType color)	设置选中状态颜色。
ColorType GetSelectedStateColor() const	获取选中状态颜色。

UIRadioButton

UIRadioButton又称为单选按钮，继承于UICheckBox，可以复用父类的函数。常将多个UIRadioButton添加到一个ViewGroup中作为一组。具体使用流程请参考示例“/src/ohos/foundation/arkui/ui_lite/test/uitest/test_button/ui_test_button.cpp”。

表 1 UIRadioButton核心函数

函数	介绍
void SetName(const char* name)	设置名称。

UIToggleButton

UIToggleButton继承于UICheckBox，其展示方式类似于拨码开关。没有自定义扩展的函数，使用方法参考UICheckBox。

UIArcLabel

UIArcLabel是以圆弧形态展示字体的组件，可以在圆形表盘的圆周按照指定的圆心、半径和角度展示文字，显示效果如图1所示，常用函数如表1所示。

图 1 UIArcLabel效果

具体使用流程请参考示例“/src/ohos/foundation/arkui/ui_lite/test/uitest/test_arc_label/ui_test_arc_label.cpp”。

表 1 UIArcLabel核心函数

函数	介绍
void SetText(const char* text)	设置展示的文字。
void SetAlign(UITextLanguageAlignment horizontalAlign)	设置此文本的对齐模式。
UITextLanguageAlignment GetHorAlign()	获取水平对齐方式。
UITextLanguageDirect GetDirect()	获取此文本的方向。
void SetFont(const char* name, uint8_t size)	设置此圆弧标签的字体及字体大小。
void SetArcTextCenter(int16_t x, int16_t y)	设置此圆弧文本的中心位置。
void SetArcTextRadius(uint16_t radius)	设置此圆弧文本的半径。
uint16_t GetArcTextRadius() const	获取此圆弧文本的半径。
void SetArcTextAngle(int16_t startAngle, int16_t endAngle)	设置此圆弧文本的开始角度和结束角度。
int16_t GetArcTextStartAngle() const	获取此圆弧文本的起始角度。
int16_t GetArcTextEndAngle() const	获取此圆弧文本的结束角度。
void SetArcTextOrientation(TextOrientation orientation)	设置此圆弧文本的方向。 参数orientation (INSIDE或OUTSIDE)

UIBoxProgress

UIBoxProgress是以条状形式表示进度的组件，例如播放视频时的进度条。继承关系为UIBoxProgress→UIAbstractProgress。父类UIAbstractProgress的常用函数如表1所示。

表 1 UIAbstractProgress核心函数

函数	介绍
void EnableBackground(bool enable)	设置进度条背景是否可见。对UISlider无效。
void SetValue(int32_t value)	设置此进度条的当前值。
int32_t GetValue() const	获取此进度条的当前值。
void SetRange(int32_t rangeMax, int32_t rangeMin)	设置此进度条的范围。
int32_t GetRangeMin() const	获取进度条最小值。
int32_t GetRangeMax() const	获取进度条最大值。
void SetCapType(CapType cap)	设置端点风格。
void SetImage(const char foregroundImage, const char backgroundImage = nullptr)	设置此进度条的图像。
void SetImage(const ImageInfo foregroundImage, const ImageInfo backgroundImage = nullptr)	设置此进度条的图像。
void SetStep(uint32_t step)	设置此进度条的步长。
uint32_t GetStep() const	获取此进度条的步长。

UIBoxProgress常用函数如表2所示，具体使用流程请参考示例“/src/ohos/foundation/arkui/ui_lite/test/uitest/test_progress_bar/ui_test_box_progress.cpp”。

表 2 UIBoxProgress核心函数

函数	介绍
void SetDirection(const Direction& direction)	设置此进度条的方向。
void SetValidWidth(int16_t width)	设置实际进度条宽度。
void SetValidHeight(int16_t height)	设置实际进度条高度。
int16_t GetValidWidth() const	获取实际进度条宽度。
int16_t GetValidHeight() const	获取实际进度条高度。

UICircleProgress

UICircleProgress组件是以圆形来展示进度的组件。该组件继承关系为UICircleProgress→UIAbstractProgress，常用函数如表1所示。具体使用流程请参考示例“/src/ohos/foundation/arkui/ui_lite/test/uitest/test_progress_bar/ui_test_circle_progress.cpp”。

表 1 UICircleProgress核心函数

函数	介绍
void SetCenterPosition(int16_t x, int16_t y)	设置此圆形进度条的中心点坐标。
void SetRadius(uint16_t radius)	设置此圆形进度条的外半径。
void SetStartAngle(int16_t startAngle)	设置开始角度（进度条初始值）。
void SetEndAngle(int16_t endAngle)	设置结束角度（进度条100%时加载位置）。
void SetCenterPosition(int16_t x, int16_t y)	设置进度条相对于控件的中心点位置。
Point GetCenterPosition() const	获取进度条相对于控件的中心点位置。
void SetProgressImagePosition(int16_t x, int16_t y)	设置此进度条的前景图像相对于视图的坐标。
void SetBackgroundImagePosition(int16_t x, int16_t y)	设置此进度条的背景图像相对于视图的坐标。
void SetLineColor(ColorType color)	设置此进度条的前景色。

UISlider

UISlider继承于UIBoxProgress，也是以进度条的方式展示进度，常用于音量条。相较于UIBoxProgress，该组件额外支持拖动以及点击事件。具体使用流程请参考示例“/src/ohos/foundation/arkui/ui_lite/test/uitest/test_slider/ui_test_slider.cpp”。

图 1 UISlider效果

表 1 UISlider核心函数

函数	介绍
void SetKnobWidth(int16_t width)	设置此旋钮的宽度。
int16_t GetKnobWidth()	获取此旋钮的宽度。
void SetImage(const ImageInfo backgroundImage, const ImageInfo foregroundImage)	将图像设置为此滑块的像素贴图，包括背景、前景。
void SetImage(const char backgroundImage, const char foregroundImage)	设置此滑块的图像，包括背景、前景。
void SetSliderColor(const ColorType backgroundColor, const ColorType foregroundColor)	设置此滑块的颜色，包括背景、前景。
void SetSliderRadius(int16_t backgroundRadius, int16_t foregroundRadius)	设置此滑块的半径，包括背景、前景。
void SetKnobImage(const ImageInfo* knobImage)	设置旋钮图片。
void SetKnobImage(const char* knobImage)	设置旋钮图片。
void SetKnobColor(const ColorType knobColor)	设置旋钮颜色。
void SetKnobRadius(int16_t knobRadius)	设置旋钮半径。
void SetKnobStyle(const Style& style)	设置旋钮样式。
void SetKnobStyle(uint8_t key, int64_t value)	设置旋钮样式。
int64_t GetKnobStyle(uint8_t key) const	获取旋钮样式。
void SetSliderEventListener(UISliderEventListener* listener)	为该组件设置监听器，使用参考sample。

UITextureMapper

UITextureMapper继承于UIImageView，主要用于做动画效果：缩放和旋转，常用函数如表1所示。具体使用流程请参考示例“/src/ohos/foundation/arkui/ui_lite/test/uitest/test_texture_mapper/ui_test_texture_mapper.cpp”。

表 1 UITextureMappre核心函数

函数	介绍
void Start()	启动动画。
void SetRotateStart(int16_t start)	设置此图像的起始旋转角度。
void SetRotateEnd(int16_t end)	设置此图像的旋转结束角。
void SetScaleStart(float start)	设置缩放此图像的起始比率。
void SetScaleEnd(float end)	设置缩放此图像的结束比率。
void SetDurationTime(uint16_t durationTime)	设置此动画器的持续时间，以毫秒为单位。
void SetDelayTime(uint16_t delayTime)	设置此动画器的延迟时间，以毫秒为单位。
void SetEasingFunc(EasingFunc easingFunc)	设置此动画器的函数。
void Cancel()	取消此动画。
void Reset()	显示原始图像。
void SetPivot(float x, float y)	设置此图像的旋转和缩放轴的变换中心点。
void SetAnimatorStopListener(AnimatorStopListener* listener)	设置此动画器停止的监听器。

UIQrcode

UIQrcode继承于UIImageView，主要是用来生成二维码，二维码显示效果如图1所示，常用函数介绍如表1所示。

图 1 UIQrcode效果

具体使用流程请参考示例“/src/ohos/foundation/arkui/ui_lite/test/uitest/test_qrcode/ui_test_qrcode.cpp”。

表 1 UIQrcode核心函数

函数	介绍
void SetQrcodeInfo(const char* val, ColorType backgroundColor = Color::White(), ColorType qrColor = Color::Black())	设置二维码信息。 • 参数val：生成二维码内容的字符串。 • 参数backgroundColor：二维码的背景色，默认为白色。 • 参数qrColor：二维码颜色，默认为黑色。
void SetQrcodeInfo(const uint8_t* val, uint16_t len, ColorType backgroundColor = Color::White(), ColorType qrColor = Color::Black())	设置二维码信息。参数说明： • val：生成二维码内容的binary地址。 • len：binary数据流长度。 • backgroundColor：二维码的背景色，默认为白色。 • qrColor：二维码颜色，默认为黑色。
void SetWidth(int16_t width) override	设置生成二维码图片的宽度。
void SetHeight(int16_t height) override	设置生成二维码图片的高度。
void SetECCLevel(QrCode::Ecc level)	设置二维码纠错等级。

UIBarcode

UIBarcode继承于UIImageView，主要是用来生成条形码。

图 1 UIBarcode效果

UIBarcode的使用方式与UIQrcode类似，不再赘述。

表 1 UIBarcode核心函数函数介绍

函数	介绍
void SetBarcodeInfo(const char* srcVal)	设置条形码信息。 参数srcVal：生成条形码内容的字符串。
void SetWidth(int16_t width) override	设置生成条形码图片的宽度。
void SetHeight(int16_t height) override	设置生成条形码码图片的高度。

UICanvas

UICanvas继承于UIView, 用于绘制各个形状的图案，如直线，圆，弧线等，常用函数介绍如表1所示。具体使用流程请参考示例“/src/ohos/foundation/arkui/ui_lite/test/uitest/test_canvas/ui_test_canvas.cpp”。

表 1 UICanvas核心函数

函数	介绍
void SetStartPosition(const Point& startPoint)	设置绘制的起点坐标。
void DrawLine(const Point& endPoint, const Paint& paint)	绘制一条直线，如果没有通过SetStartPosition设置起点，默认走上一次结束位置开始绘制。
void DrawLine(const Point& startPoint, const Point& endPoint, const Paint& paint)	从起点的坐标绘制直线，到终点结束。
void DrawCurve(const Point& startPoint, const Point& control1, const Point& control2, const Point& endPoint, const Paint& paint)	从起点坐标绘制三次贝塞尔曲线。
void DrawCurve(const Point& control1, const Point& control2, const Point& endPoint, const Paint& paint)	绘制立方贝塞尔曲线。
void DrawRect(const Point& startPoint, int16_t height, int16_t width, const Paint& paint)	绘制矩形。
void DrawCircle(const Point& center, uint16_t radius, const Paint& paint)	绘制圆形。
void DrawSector(const Point& center, uint16_t radius, int16_t startAngle, int16_t endAngle, const Paint& paint)	绘制扇区。
void DrawArc(const Point& center, uint16_t radius, int16_t startAngle, int16_t endAngle, const Paint& paint)	绘制圆弧。
void DrawImage(const Point& startPoint, const char* image, const Paint& paint)	绘制图像。
void DrawLabel(const Point& startPoint, const char* text, uint16_t maxWidth, const FontStyle& fontStyle, const Paint& paint)	绘制文本。
void BeginPath()	创建路径。
void MoveTo(const Point& point)	将此路径的起点移动到指定的点。
void LineTo(const Point& point)	创建从此路径的端点到指定点的直线。
void ArcTo(const Point& center, uint16_t radius, int16_t startAngle, int16_t endAngle)	创建圆弧路径。
void AddRect(const Point& point, int16_t height, int16_t width)	创建矩形路径。
void ClosePath()	关闭此路径。
void DrawPath(const Paint& paint)	绘制此路径。

UICanvasExt

UICanvasExt继承于UIView，与UICanvas功能相似，是基于硬件绘制能力定制的一个画布控件，绘制属性通过继承于Paint的PaintExt设置。常用函数介绍如表1、表2所示。具体使用流程请参考示例“/src/middleware/services/gui/uikit/sample/uitest/components/ui_test_draw/ui_test_canvas_ext.cpp”。

表 1 PaintExt核心函数

函数	介绍
void SetLinearGradient(const LinearGradient& linear, const ColorStop* stops, uint16_t stopCount)	设置线性渐变。
void SetRadialGradient(const RadialGradient& radial, const ColorStop* stops, uint16_t stopCount)	设置放射渐变。当前芯片不支持渐变中心点为负坐标。
void SetSweepGradient(const SweepGradient& sweep, const ColorStop* stops, uint16_t stopCount)	设置扫描渐变，默认12点钟方向为0度位置，若传入值为负数，则按0处理。当前芯片不支持渐变中心点为负坐标。 注意旧版扫描渐变是以3点钟为起始方向，弧形绘制是以12点钟为起始方向；新版扫描渐变和弧形绘制都是以12点钟为方向。
void SetFillRule(const FillRule& fillRule)	设置填充规则。仅对Fill有效。
void SetGradientSpread (const GradientSpread& gradientSpread)	设置超出渐变区域的渲染模式。
void SetCapType(const CapType& capType)	设置线帽样式。仅对Stroke类型有效。 注：如果设置线帽类型为round，会在原有路径两端加上以线宽为直径的半圆。
void SetJoinType (const JoinType& joinType)	设置线段连接样式。仅对Stroke类型有效。
void SetMiterLimit(float miterLimit)	设置线端连接时内接点和外接点的长度限制。仅对Stroke类型且线段连接样式为JOIN_MITER有效。
void SetAntialiased (bool antialiased)	设置是否抗锯齿。
void SetClipRect(Rect clipRect)	设置剪切矩阵。

说明： 渐变指的是多色的一个渐变效果，设置单色会提示错误。

表 2 UICanvasExt核心函数

函数	介绍
int16_t BeginPath(PaintExt paint)	开始一段路径。 若已经调用过且后续未调用SetPathData进行数据设置，或是数据设置后未调用DrawPath，再次调用则无效。 返回此path对象对应的index。
void SetPathData(uint32_t cmdNum, const uint8_t cmd, uint32_t dataNum, const float data)	设置Path数据。 仅在开始一段路径后调用。针对单个路径，仅能设置一次。
void SetMatrix(Matrix3 matrix, int16_t index = -1)	设置内部path对象对应的变换矩阵。如不设置，则使用单位矩阵。 index默认参数为-1，表示最后一个创建的path对象。用户可使用其他接口返回的path index指定具体的path对象。
void DrawPath()	设置路径绘制标志位为true。 若未调用此函数，创建的Path将无法显示在画布上。后续也无法创建新路径。
void Clear()	清除Canvas画布，清除所有内部Path对象以及其相关的数据。
int16_t DrawLine(const Point& startPoint, const Point& endPoint, const PaintExt& paint)	绘制直线。 返回此path对象对应的index。
int16_t DrawCurve(const Point& startPoint, const Point& control1, const Point& control2, const Point& endPoint, const PaintExt& paint)	绘制三阶贝塞尔曲线。 返回此path对象对应的index。
int16_t DrawRect(const Point& startPoint, int16_t height, int16_t width, const PaintExt& paint)	绘制矩形。 返回此path对象对应的index。
int16_t DrawArc(const Point& center, uint16_t radius, int16_t startAngle, int16_t endAngle, const PaintExt& paint)	绘制弧线。注：画跨0度区间且为上半部分的弧线，需要分2段拼接实现。 返回此path对象对应的index。
int16_t DrawSvg(const char* path)	绘制svg文件通过工具转换出的bin。
void SetSvgMatrix(Matrix3 matrix, int16_t index)	设置内部svg对象对应的变换矩阵。如不设置，则使用单位矩阵。

说明： DrawSvg API入参为svg_to_bin工具转换出的二进制文件路径。 该工具由 graphic_tools.tar.gz 提供，解压后进入 graphic_tools/svg_to_path/src 使用。

• Linux环境：
  • 前置条件：需要安装python 3.8.10以上版本。
  • 使用命令：python3 main.py -f [FILE] -output [output] * [FILE]：svg格式文件，文件名中不能包含空格。 * [output]：输出路径，非必要。
  • 使用示例：python3 main.py -f ./run.svg
• Windows环境：
  • 前置条件：需要安装python 3.11.2以上版本，并将添加到计算机环境变量内。
  • 使用命令：python main.py -f [FILE] -output [output] * [FILE]：svg格式文件，文件名中不能包含空格。 * [output]：输出路径，非必要。
  • 使用示例：python main.py -f ./run.svg

UILiteSurfaceView

UILiteSurfaceView是用于播放视频的组件，继承于UIView。具体使用流程请参考示例“/src/middleware/services/gui/uikit/sample/uitest/components/ui_test_video_play/ui_test_video_play.cpp”。

表 1 UILiteSurfaceView核心函数

函数	介绍
Surface* GetSurface() const	获取Surface。
void SetPosition(int16_t x, int16_t y, int16_t width, int16_t height) override	设置当前视图的位置以及宽高。
void Resize(int16_t width, int16_t height) override	调整此视图的大小。
void SetX(int16_t x) override	设置此视图的X坐标位置。
void SetY(int16_t y) override	设置此视图的Y坐标位置。
void SetWidth(int16_t width) override	设置此视图的宽度。
void SetHeight(int16_t height) override	设置此视图的高度。
void SetVideoResizeMode(VideoResizeMode resizeMode)	设置视频自适应模式。自适应模式默认为Fill。 VideoResizeMode枚举包含以下值： • Fill：视频的内容完全填充容器。内容将被拉伸以适应容器的尺寸，可能会导致内容变形。 • Contain：视频的内容在保持其宽高比的情况下完全适应容器。内容将被缩放以适应容器的尺寸，但不会被裁剪。
VideoResizeMode GetVideoResizeMode()	获取视频自适应模式。
void SetRotation(VideoRotation rotation)	设置视频旋转度数。默认不旋转。 VideoRotation枚举包含以下值： • ROTATE_0：不旋转； • ROTATE_90：旋转90度； • ROTATE_180：旋转180度； • ROTATE_270：旋转270度。
VideoRotation GetRotation()	获取视频旋转度数。

LiteSurface是由UILiteSurfaceView中通过GetSurface获取的Surface，用于管理媒体和图形的共享内存。

表 2 LiteSurface核心函数

函数	介绍
void SetQueueSize(uint8_t queueSize) override	设置buffer队列大小（最大值为3，建议设置为3）。
uint8_t GetQueueSize() override	获取buffer队列大小。
void SetWidthAndHeight(uint32_t width, uint32_t height) override	设置buffer宽高。
uint32_t GetWidth() override	获取buffer宽度。
uint32_t GetHeight() override	获取buffer高度。
void SetFormat(uint32_t format) override	设置buffer像素格式（目前仅支持PIXEL_FMT_YCBCR_420_SP）。
uint32_t GetFormat() override	获取buffer像素格式。
void RegisterConsumerListener(IBufferConsumerListener& listener) override	注册消费者回调。当生产者刷新一个buffer至脏队列即通知消费者。
void UnregisterConsumerListener() override	去注册消费者回调。
void SetStrideAlignment(uint32_t strideAlignment) override	设置stride对齐。
uint32_t GetStrideAlignment() override	获取stride对齐（目前必须传入64）。
uint32_t GetStride() override	获取stride。
void SetSize(uint32_t size) override	设置buffer大小。
uint32_t GetSize() override	获取buffer大小。
SurfaceBuffer* RequestBuffer(uint8_t wait = 0) override	生产者从空闲队列中获取buffer用于填写数据。
int32_t FlushBuffer(SurfaceBuffer* buffer) override	生产者在RequestBuffer后且完成填写数据动作后，刷新buffer至脏队列，等待消费者处理。
void CancelBuffer(SurfaceBuffer* buffer) override	生产者释放buffer至空闲队列。
SurfaceBuffer* AcquireBuffer() override	消费者从脏队列中获取被生产者刷新的buffer用于送显。
bool ReleaseBuffer(SurfaceBuffer* buffer) override	消费者在AcquireBuffer后且完成送显动作后，释放buffer至空闲队列。

UIEditText

UIEditText是支持输入法编辑的文本类组件，继承于UIView。

支持两种以下模式：

• 明码模式：显示文本具体内容。
• 密码模式：不显示具体输入的内容，以符合“·”替代。

图 1 UIEditText两种模式显示效果图

图 2 软键盘效果图

常用函数介绍如表1所示。具体使用流程请参考示例“/src/middleware/services/gui/uikit/sample/uitest/components/ui_test_keyboard/ui_test_keyboard.cpp”。

表 1 UIEditText核心函数

函数	介绍
void SetTextColor(ColorType color)	设置文本内容显示颜色。
ColorType GetTextColor()	获取文本内容显示颜色。
void SetInputType(InputType type)	设置文本内容显示模式。
InputType GetInputType()	获取文本内容显示模式。
void SetText(const char* text)	设置当前文本内容。
const char* GetText()	获取当前文本内容。
void SetPlaceholder(const char* placeholder)	设置提示文本内容。
const char* GetPlaceholder()	获取提示文本内容。
void SetMaxLength(uint16_t maxLength)	设置最大文本内容长度。
uint16_t GetMaxLength()	获取最大文本内容长度。
void SetPlaceholderColor(ColorType color)	设置提示文本内容显示颜色。
ColorType GetPlaceholderColor()	获取提示文本内容显示颜色。
void SetCursorColor(ColorType color)	设置光标颜色。
ColorType GetCursorColor()	获取光标颜色。
void SetFontId(uint16_t fontId)	设置字体。
uint8_t GetFontId()	获取字体。
void SetFont(const char* name, uint8_t size)	设置字体。
uint16_t GetTextWidth()	获取字体宽度。
uint16_t GetTextHeight()	获取字体高度。
void InsertText(std::string text)	在末尾插入文本。
void DeleteBackward(uint32_t length)	删除末尾文本。

说明： 软键盘功能为客户参考代码，适配的屏幕为 454×454 屏，客户可按需进行布局调整，包括布局效果调整、适配不同屏幕尺寸等。重新适配需要修改文件 ui_soft_keyboard.cpp 中的控件位置、大小等布局信息。

UIKaleidoscopeView

UIKaleidoscopeView是基于原始图片素材生成万花筒效果的控件。该控件将直接读写送显Buffer，因此需要设置控件起始位置为[0, 0]，并保持其尺寸与送显Buffer尺寸一致。具体使用流程请参考示例middleware/services/gui/uikit/sample/uitest/components/ui_test_kaleidoscope/ui_test_kaleidoscope.cpp。

图 1 万花筒效果示意图

表 1 UIKaleidoscopeView核心函数

函数	描述
bool SetSrc(const ImageInfo* src)	设置万花筒效果的源素材。
void Rotate(float rotate)	根据设定的旋转刻度，生成新的万花筒效果图。
void SetRotateEventFactor(float factor)	设置万花筒响应表冠旋转事件的因子。
void SetRotateAnimatorValue(float rotate)	设置万花筒动画使用的旋转刻度。
void StartRotateAnimator()	启动万花筒动画。
void StopRotateAnimator()	停止万花筒动画。

UIFloatBoxView

UIFlloatBoxView是弧形悬浮框中显示圆形图标的控件，常用于界面之上的快捷应用浮窗。该控件以内部有效区域的中心点为圆心，并以偏小一侧的尺寸作为直径去构建弧形布局。建议使用宽高相等的控件，便于布局计算。具体使用流程请参考示例“/src/middleware/services/gui/uikit/sample/uitest/components/ui_test_float_box/ui_test_float_box.cpp”。

图 1 UIFloatBoxView效果示意图

表 1 UIFloatBoxView核心函数

函数	描述
bool AddItems(FloatItem* floatItems, uint8_t floatItemsCnt)	添加一组悬浮元素，元素数量有效范围为[2, 3]。 FloatItem由std::string name及ImageInfo* imgInfo组成。每个元素都应对应独一无二的名字，图片内容则应为圆形图标。
void ClearItems()	清除已添加的悬浮元素。
void SetOnItemClickListener(UIFloatBoxView::OnItemClickListener* listener)	设置点击元素回调监听器。当点击图标时，会回调该监听器中自实现的OnItemClick函数。
UIFloatBoxView::OnItemClickListener*& GetOnItemClickListener()	获取点击元素回调监听器。
uint16_t GetItemCnt() const	获取元素数量。
void SetItemSize(uint16_t size)	设置图片元素的显示大小。该值与ItemSpacing的总和等于弧形背景的宽度，但不能超过控件偏小一侧的尺寸的四分之一。
void SetItemSpacing(uint16_t spacing)	设置图片元素之间的间隔距离。该值和ItemSize的总和等于弧形背景的宽度，但不能超过控件偏小一侧的尺寸的四分之一。
void SetDragFactor(float value)	设置滑动加权值。 值越大，滑动时图标位置变化得越大。
float GetDragFactor() const	获取滑动加权值。
void SetAccFactor(float factor)	设置滑动松手后的惯性加速加权值。 值越大，滑动松手后图标位置变化得越大。
float GetAccFactor() const	获取滑动松手后的惯性加速加权值。
void SetRotateFactor(float value)	设置旋转表冠加权值。 值越大，旋转表冠时图标位置变化得越大。
float GetRotateFactor() const	获取旋转表冠加权值。
void SetAlignAvgSpeed(float speed)	设置对齐动画的平均速度。 值越大，松手后对齐元素动画越快。
float GetAlignAvgSpeed() const	获取对齐动画的平均速度。
void SetBgArcColor(uint32_t color)	设置弧形背景的颜色。

UILottView

UILottView是支持播放Lottie矢量动画的控件。Lottie矢量动画相较于序列帧方案占用资源更小。设计师通过After Effects软件设计矢量动画，通过Bodymovin插件导出Lottie Json文件，通过自研的Lottie转换工具将Json文件转为Bin文件，最终通过UILottView解析Bin文件播放矢量动画，如图1所示。

图 1 Lottie开发流程图

表 1 UI3DView核心函数

函数	描述
bool SetSrc(std::string file, FILE *fp = nullptr, uint32_t offset = 0)	设置通过Lottie工具转换生成的Lottie Bin文件。
void Start()	播放Lottie矢量动画。
void Pause()	暂停Lottie矢量动画
void Resume()	继续Lottie矢量动画。
void Stop()	停止Lottie矢量动画。
void SetRepeat(bool repeat)	设置是否重复播放动画。
bool IsRepeat() const	获取是否重复播放动画。
uint8_t GetState() const	获取Lottie矢量动画状态。

须知： 目前仅支持基础矢量图形和基础样式绘制，矢量变换，矢量路径裁剪功能。不支持全量Lottie功能。

UI3DView

UI3DView是支持3D能力的基类，为UI3DSphere、UI3DMesh、UI3DCylinder等派生类提供了通用的属性和函数。

表 1 UI3DView核心函数

函数	描述
virtual bool SetModel(std::string file)	设置通过3D工具生成的3D模型。 UI3DSphere和UI3DCylinder必须设置模型文件。 UI3DMesh弱交互网格变形模式下，需要设置对应类型的模型文件；而强交互网格变形模式下，则无需设置模型文件。
void ClearModel()	清除3D模型。
virtual bool SetTexture(const ImageInfo* info)	设置纹理。 UI3DSphere和UI3DCylinder必须设置纹理素材。 UI3DMesh可选是否设置纹理素材。如果没有设置纹理素材，将在内部自动生成背景截图当作纹理使用。
void ClearTexture()	清除纹理。
const ImageInfo* GetTexture() const	获取纹理。

UI3DSphere

UI3DSphere是支持3D球体模型纹理贴图的控件。具体使用流程请参考示例“/src/middleware/services/gui/uikit/sample/uitest/components/ui_test_3d/ui_test_sphere.cpp”。

图 1 UI3DSphere效果示意图

表 1 UI3DSphere核心函数

函数	描述
void RotateAroundXAxis(float angle)	绕X轴旋转特定角度。
void RotateAroundYAxis(float angle)	绕Y轴旋转特定角度。
void RotateAroundZAxis(float angle)	绕Z轴旋转特定角度。
float GetAngleAroundXAxis()	获取绕X轴旋转的角度。
float GetAngleAroundYAxis()	获取绕Y轴旋转的角度。
float GetAngleAroundZAxis()	获取绕Z轴旋转的角度。

UI3DMesh

UI3DMesh是支持纹理网格变形动画的控件。具体使用流程请参考示例“/src/middleware/services/gui/uikit/sample/uitest/components/ui_test_3d/ui_test_mesh.cpp”。

图 1 原始图片效果示意图

图 2 UI3DMesh Array网格变形模式效果示意图

表 1 UI3DMesh核心函数

函数	描述
bool SetMeshType(VGUMeshType meshType)	设置网格变形模式。
VGUMeshType GetMeshType() const	获取网格变形模式。
void SetMeshPosition(int16_t x, int16_t y)	设置网格变形原点。
void SetTime(uint32_t time)	设置网格变形动画时长。
void Start()	启动网格变形动画。
void Pause()	暂停网格变形动画。
void Resume()	恢复网格变形动画。
void Stop()	停止网格变形动画。
uint8_t GetState()	获取网格变形动画状态。
void SetReverse(bool reverse)	设置网格变形动画是否逆序播放。
bool GetReverse() const	获取网格变形动画是否逆序播放。
void SetRealTimeScreencap(bool realTime)	设置网格变形动画过程中是否每帧实时截图，该属性仅针对没有设置纹理的场景有效。
bool GetRealTimeScreencap()	获取网格变形动画过程中是否每帧实时截图。

表 2 VGUMeshType枚举

枚举值	描述
VGU_MESH_ARRAY	强交互网格变形模式。无需设置对应的模型文件。通过SetMeshPosition函数配置网格变形原点。
VGU_MESH_CONVEX	弱交互网格变形模式。需要设置对应的模型文件。SetMeshPosition函数无法生效。
VGU_MESH_CONCAVE	弱交互网格变形模式。需要设置对应的模型文件。SetMeshPosition函数无法生效。
VGU_MESH_VORTEX	弱交互网格变形模式。需要设置对应的模型文件。SetMeshPosition函数无法生效。
VGU_MESH_WAVE	弱交互网格变形模式。需要设置对应的模型文件。SetMeshPosition函数无法生效。
VGU_MESH_MORIE	弱交互网格变形模式。需要设置对应的模型文件。SetMeshPosition函数无法生效。
VGU_MESH_RIPPLE	强交互网格变形模式。无需设置对应的模型文件。通过SetMeshPosition函数配置网格变形原点。
VGU_MESH_INVALID	无效的网格变形模式。

UI3DCylinder

UI3DCylinder是支持3D柱状体模型纹理贴图的控件。具体使用流程请参考示例“/src/middleware/services/gui/uikit/sample/uitest/components/ui_test_3d/ui_test_cylinder.cpp”。

图 1 UI3DCylinder效果示意图

表 1 UI3DCylinder核心函数

函数	描述
void SetStartY(int16_t y)	设置局部显示部分相对于整张纹理素材的起始Y坐标。
int16_t GetStartY() const	获取局部显示部分相对于整张纹理素材的起始Y坐标。
void SetCameraAngle(float angle)	设置相机旋转角度。
void SetCameraVFov(float distance)	设置相机垂直视角。
void SetCameraAspectRatio(float ratio)	设置相机画面宽高比。
void SetCameraNearPlane(float value)	设置相机近裁剪平面。
void SetCameraFarPlane(float value)	设置相机远裁剪平面。
void SetCameraAxis(Vector3 axis)	设置相机中心轴。
void SetCameraScale(Vector3 scale)	设置相机缩放比。
void SetCameraTranslation(Vector3 translation);	设置相机平移。
void SetCameraPosition(Vector3 position)	设置相机位置。

UIPostEffectImageView

UIPostEffectImageView是支持对图片进行HSV或者Colorize后处理的控件。HSV是指通过调整颜色模型的色相（Hue）、饱和度（Saturation）和明度（Value）来调整图像颜色。Colorize是指根据输入的颜色对图像进行染色。

HSV具体使用流程请参考示例“/src/middleware/services/gui/uikit/sample/uitest/components/ui_test_hsv/ui_test_hsv.cpp”。

Colorize具体使用流程请参考示例“/src/middleware/services/gui/uikit/sample/uitest/components/ui_test_colorize/ui_test_colorize.cpp”。

表 1 UIPostEffectImageView核心函数

函数	描述
void EnableColorize(bool enable)	设置Colorize是否使能。
bool IsEnableColorize()	获取Colorize是否使能。
void SetColorize(ColorType color)	设置Colorize的颜色类型。
ColorType GetColorize()	获取Colorize的颜色类型。
void EnableHSVAdjust(bool enable)	设置HSV是否使能。
bool IsEnableHSVAdjust()	获取HSV是否使能。
void SetHSVInfo(int16_t hAdjust, int8_t sAdjust, int8_t vAdjust, int16_t threshold)	设置HSV参数。
void SetHSVMask(const std::string& mask)	设置HSV蒙版。

UIRainView

UIRainView是支持呈现雨滴效果以及擦拭交互的控件。具体使用流程请参考示例“/src/middleware/services/gui/uikit/sample/uitest/components/ui_test_rain/ui_test_rain.cpp”。

表 1 UIRainView核心函数

函数	描述
void SetRain(const ImageInfo* rainInfo[], uint8_t rainNum)	设置RainView所需要的图片以及图片数量。
void SetTimeOfUpdate(uint16_t timeOfUpdate)	设置RainView的动画播放速度。
uint16_t GetTimeOfUpdate()	获取RainView的动画播放速度。
void SetTimeOfPause(uint16_t timeOfPause)	设置无限重复动画的两次播放之间的间隔。
uint16_t GetTimeOfPause()	获取无限重复动画的两次播放之间的间隔。
void Start()	播放动画。
void Pause()	暂停动画。
void Resume()	恢复动画。
void Stop()	停止动画。
void GetState()	获取动画状态。
void SetBlur(float radius)	设置高斯模糊值。
float GetBlur()	获取高斯模糊值。
uint8_t ClearWipeArea()	启动手动擦拭擦拭区域。
void SetWipeWidth(uint32_t width)	设置手动擦拭屏幕的宽度。
uint32_t GetWipeWidth()	获取手动擦拭屏幕的宽度。
void Clear()	手动清除雨水图像缓存并擦拭区域，应在此动画器停止后调用。