QCustomPlot 提供了一系列可以在圖表上疊加顯示的對象（items），這些對象不屬于數據本身，而是用于標注、輔助線等用途。以下是主要疊加對象的詳細說明和使用方法。

1. QCPItemStraightLine (無限直線)

特性：

• 無限延伸的直線

• 常用于參考線、基準線

創建與設置：

QCPItemStraightLine *line = new QCPItemStraightLine(customPlot);
line->point1->setCoords(0, 5);  // 線上第一個點
line->point2->setCoords(1, 5);  // 線上第二個點（確定方向）
line->setPen(QPen(Qt::red, 2, Qt::DashLine));

常用方法：

• setPen()?- 設置線條樣式

• point1,?point2?- 直線的兩個定義點

2. QCPItemLine (有限線段)

特性：

• 兩點之間的有限長度線段

• 可以添加箭頭

創建與設置：

QCPItemLine *line = new QCPItemLine(customPlot);
line->start->setCoords(1, 1);  // 起點
line->end->setCoords(5, 3);    // 終點
line->setHead(QCPLineEnding::esSpikeArrow);  // 終點箭頭
line->setPen(QPen(Qt::blue, 2));

常用方法：

• setHead(),?setTail()?- 設置起點/終點箭頭樣式

• setSelectedPen()?- 設置選中時的線條樣式

QCPItemStraightLine 與 QCPItemLine 的區別

幾何特性區別

特性	QCPItemStraightLine	QCPItemLine
線條類型	無限延伸的直線	兩點之間的有限線段
定義方式	通過一個點和方向定義	通過起點和終點定義
數學表示	參數方程或斜截式	兩點之間的線段
實際繪制范圍	總是延伸到整個繪圖區域	僅在兩點之間繪制

功能特性對比

功能	QCPItemStraightLine	QCPItemLine
箭頭支持	? 不支持	? 支持
長度限制	? 無限	? 有限
方向表示	需要兩個點定義方向	明確起點終點
適合場景	參考線、基準線	連接線、標注

坐標系統注意事項

兩者都使用相同的坐標系統，但行為不同：

• QCPItemStraightLine：

  // 當圖表縮放時，直線會自動延伸以適應新范圍
  line->point1->setType(QCPItemPosition::ptPlotCoords);  // 使用繪圖坐標

• QCPItemLine：

  // 線段長度固定，不會隨縮放改變
  line->start->setType(QCPItemPosition::ptPlotCoords);
  line->end->setType(QCPItemPosition::ptPlotCoords);

性能考慮

• QCPItemStraightLine?通常性能稍好，因為它的幾何計算更簡單。

• QCPItemLine?在有大量箭頭裝飾時可能會有額外開銷。

• 兩者在常規使用中性能差異不明顯。

3. QCPItemText (文本標簽)

特性：

• 可放置在任意位置的文本

• 支持旋轉和多種對齊方式

創建與設置：

QCPItemText *text = new QCPItemText(customPlot);
text->position->setCoords(3, 4);  // 文本位置
text->setText("Important Point");
text->setFont(QFont("Arial", 12));
text->setColor(Qt::darkGreen);
text->setRotation(45);  // 旋轉45度
text->setTextAlignment(Qt::AlignCenter);

常用方法：

• setPadding()?- 設置文本內邊距

• setPositionAlignment()?- 設置位置對齊方式

• setBrush()?- 設置背景填充

4. QCPItemRect (矩形)

特性：

• 可設置邊框和填充的矩形

• 常用于高亮顯示區域

創建與設置：

QCPItemRect *rect = new QCPItemRect(customPlot);
rect->topLeft->setCoords(1, 6);
rect->bottomRight->setCoords(4, 3);
rect->setPen(QPen(Qt::black));
rect->setBrush(QBrush(QColor(255, 200, 200, 100)));  // 半透明填充

常用方法：

• setRadius()?- 設置圓角半徑

• setSelectedBrush()?- 設置選中時的填充

5. QCPItemEllipse (橢圓)

特性：

• 可設置邊框和填充的橢圓

• 實際上是基于矩形的內切橢圓

創建與設置：

QCPItemEllipse *ellipse = new QCPItemEllipse(customPlot);
ellipse->topLeft->setCoords(2, 5);
ellipse->bottomRight->setCoords(5, 2);
ellipse->setPen(QPen(Qt::darkBlue));
ellipse->setBrush(QBrush(QColor(200, 200, 255, 50)));

6. QCPItemPixmap (位圖)

特性：

• 可以在圖表上顯示位圖

• 支持縮放和保持寬高比

創建與設置：

QCPItemPixmap *pixmap = new QCPItemPixmap(customPlot);
pixmap->topLeft->setCoords(3, 7);
pixmap->setPixmap(QPixmap(":/images/logo.png"));
pixmap->setScaled(true, Qt::KeepAspectRatio);

通用屬性和方法

所有疊加對象都繼承自 QCPAbstractItem，具有以下通用功能：

1. 位置控制：

   • 使用錨點（QCPItemPosition）定義位置

   • 支持絕對坐標或相對坐標（軸坐標）

2. 可選擇性：

   item->setSelectable(true);
   connect(customPlot, &QCustomPlot::itemClick, [](QCPAbstractItem *item, QMouseEvent *event) {qDebug() << "Item clicked:" << item;
   });

3. 可見性控制：

   item->setVisible(false);  // 隱藏項目

4. 圖層控制：

   item->setLayer("overlay");  // 放置到特定圖層

使用技巧

1. 動態更新：

   // 在重繪前更新項目位置
   connect(customPlot, &QCustomPlot::beforeReplot, [=](){textLabel->position->setCoords(customPlot->xAxis->range().center(), customPlot->yAxis->range().upper);
   });

2. 批量操作：

   // 隱藏所有項目
   foreach(QCPAbstractItem *item, customPlot->items()) {item->setVisible(false);
   }

3. 交互示例：

   // 創建可拖動的文本標簽
   QCPItemText *dragText = new QCPItemText(customPlot);
   dragText->setText("Drag me");
   dragText->position->setType(QCPItemPosition::ptPlotCoords);
   dragText->position->setCoords(5, 5);
   dragText->setSelectable(true);// 啟用拖動交互
   customPlot->setInteraction(QCP::iSelectItems, true);
   customPlot->setInteraction(QCP::iMoveItems, true);