10. CVUI 2.7.0 组件：Trackbar （官方文档翻译）

官方文档链接：https://dovyski.github.io/cvui/components/trackbar/

---

Trackbar

cvui::trackbar() 渲染一个数值型的 trackbar，用户可以通过单击/向左右拖动标记来增加/减少数值。函数声明如下：

template <typename T>
bool trackbar (
    cv::Mat& theWhere,
    int theX,
    int theY,
    int theWidth,
    T *theValue,
    T theMin,
    T theMax,
    int theSegments = 1,
    const char *theLabelFormat = "%.1Lf",
    unsigned int theOptions = 0,
    T theDiscreteStep = 1
)

theWhere 是用于渲染图像的图像或帧，theX 是 X 坐标，theY 是 Y 坐标，theWidth 是 trackbar 的宽度，theValue 是 trackbar 的当前值，theMin 是 trackbar 允许的最小值，theMax 是 trackbar 允许的最大值。

当用户与 trackbar 交互时，将会修改参数 theValue。可以使用任何数字类型，例如 float、double、long double、int、char、uchar。

当 trackbar 的值改变时，cvui::trackbar() 返回 true；如果该值自上次交互后保持不变，则返回 false。

重要：cvui::trackbar() 使用了 C++ 模板，因此，必须非常明确地说明参数地类型：theValue，theMin，theMax，theStep，否则可能会出现奇怪的编译错误。

如下是 trackbar 的示例和输出结果：

核心语句：

double value = 12.4;
cvui::trackbar(frame, 100, 140, 400, &value, (double)0, (double)100);

完整代码：

#define CVUI_IMPLEMENTATION
#define CVUI_DISABLE_COMPILATION_NOTICES
#include "cvui.h"

#include <iostream>

#include <opencv2/core/core.hpp>
#include <opencv2/highgui/highgui.hpp>
#include <opencv2/imgproc/imgproc.hpp>
#include <opencv2/imgcodecs/imgcodecs.hpp>

#define WINDOW_NAME "CVUI Test"

int main(int argc, char** argv)
{
	cvui::init(WINDOW_NAME);

	cv::Mat frame = cv::Mat(cv::Size(600, 300), CV_8UC3);

	double value = 12.4;

	while (true) 
	{
		frame = cv::Scalar(150, 150, 150);
		cvui::trackbar(frame, 100, 140, 400, &value, (double)0, (double)100);

		cvui::imshow(WINDOW_NAME, frame);

		if (cv::waitKey(20) == 27)
			break;
	}
	
	return 0;
}

结果展示：标尺可滑动

---

自定义 (Customization)

cvui::trackbar 可高度定制。参数 theSegments 指示 trackbar 的段数（默认是 1）。Segments 可以被看作是在轨迹栏的刻度中的一组数字。例如，1 segment 表示单个值组（没有沿着刻度线的额外标签），2 segment 表示 trackbar 的刻度值将被分成两组，并且一个标签将放置在刻度线的中间。示例如下图所示：

核心语句：

double value = 12.4;
cvui::trackbar(frame, 100, 140, 400, &value, (double)0, (double)100, 10);

输出结果：

参数 theLabelFormat 是用于呈现标签的格式化字符串，例如：%.2Lf (Lf 而不是 lf)。无论 theValue 参数的类型如何，在 cvui::trackbar() 在内部都将其存储为 long double 型，所以格式化字符串将始终收到一个 long double 值来格式化。例如，如果用户使用带有整数值的 trackbar，则可以使用格式化字符串（如 %.0Lf）来控制小数。

核心语句：

double value = 12.4;
cvui::trackbar(frame, 100, 140, 400, &value, (double)0, (double)100, 10, "%.0Lf");

输出结果：

参数 theOptions 提供自定义 trackbar 的行为和外观的选项，表示为位集（bitset）。可用选项定义为 TRACKBAR_ 常量，并且可以使用按位 | 操作数组合它们。可用选项包括：

• TRACKBAR_HIDE_SEGMENT_LABELS：不渲染线段标签，只渲染最小/最大值标签；
• TRACKBAR_HIDE_STEP_SCALE：不渲染指示刻度值的小行；
• TRACKBAR_DISCRETE：trackbar 值的变化是 theDiscretestep 参数的倍数；
• TRACKBAR_HIDE_MIN_MAX_LABELS：不渲染 min/max 标签；
• TRACKBAR_HIDE_VALUE_LABEL：在移动的标记（marker）下不渲染 trackbar 的当前值；
• TRACKBAR_HIDE_LABELS：完全不渲染标签。

核心语句：

double value1 = 12.4;
double value2 = 12.4;
double value3 = 12.4;
double value4 = 12.4;
double value5 = 12.4;
double value6 = 12.4;
double value7 = 12.4;

while (true) 
{
	frame = cv::Scalar(150, 150, 150);

	cvui::text(frame, 50, 10, "Without option: ");
	cvui::trackbar(frame, 100, 20, 400, &value1, (double)0, (double)100, 10, "%.1Lf");
	std::cout << "value1 = " << value1 << std::endl;

	cvui::text(frame, 50, 90, "TRACKBAR_HIDE_SEGMENT_LABELS: ");
	cvui::trackbar(frame, 100, 100, 400, &value2, (double)0, (double)100, 10, "%.1Lf", cvui::TRACKBAR_HIDE_SEGMENT_LABELS);
	std::cout << "value2 = " << value2 << std::endl;

	cvui::text(frame, 50, 170, "TRACKBAR_HIDE_STEP_SCALE: ");
	cvui::trackbar(frame, 100, 180, 400, &value3, (double)0, (double)100, 10, "%.1Lf", cvui::TRACKBAR_HIDE_STEP_SCALE);
	std::cout << "value3 = " << value3 << std::endl;

	cvui::text(frame, 50, 250, "TRACKBAR_DISCRETE: ");
	cvui::trackbar(frame, 100, 260, 400, &value4, (double)0, (double)100, 10, "%.1Lf", cvui::TRACKBAR_DISCRETE);
	std::cout << "value4 = " << value4 << std::endl;

	cvui::text(frame, 50, 330, "TRACKBAR_HIDE_MIN_MAX_LABELS: ");
	cvui::trackbar(frame, 100, 340, 400, &value5, (double)0, (double)100, 10, "%.1Lf", cvui::TRACKBAR_HIDE_MIN_MAX_LABELS);
	std::cout << "value5 = " << value5 << std::endl;

	cvui::text(frame, 50, 410, "TRACKBAR_HIDE_VALUE_LABEL: ");
	cvui::trackbar(frame, 100, 420, 400, &value6, (double)0, (double)100, 10, "%.1Lf", cvui::TRACKBAR_HIDE_VALUE_LABEL);
	std::cout << "value6 = " << value6 << std::endl;

	cvui::text(frame, 50, 490, "TRACKBAR_HIDE_LABELS: ");
	cvui::trackbar(frame, 100, 500, 400, &value7, (double)0, (double)100, 10, "%.1Lf", cvui::TRACKBAR_HIDE_LABELS);
	std::cout << "value7 = " << value7 << std::endl;

	cvui::imshow(WINDOW_NAME, frame);

	if (cv::waitKey(20) == 27)
		break;
}

输出结果：

注意：
同时渲染多个 trackbar 时注意各自在定义时 T *theValue 是不同的，区别不同的 trackbar 即是看 T *theValue 是否一样。

参数 theDiscreteStep 是当 marker 向右/向左拖动时 trackbar marker 增加/减少的量，即增减的步长（此参数的设定需要选项 TRACKBAR_DISCRETE 处于活动状态）。