如何使用Qt的PIMPL习惯用法（PIMPL Idiom

）

PIMPL是指“Pointer to IMPLementation”（指向实现的指针），意味着将实现细节隐藏起来，用户类无需关注这些实现细节。在Qt中常用PIMPL习惯用法来清晰地区分接口与实现，尽管Qt官方文档并未详细说明该机制。本文将演示如何在Qt中使用PIMPL习惯用法，并以一个简单的坐标输入对话框作为实例。

原理与动机

PIMPL的核心在于将类的实现细节封装在一个私有类中，这个私有类包含了所有特定于实现的数据和方法。通过这种方式，可以将头文件中的实现细节移除，减少头文件的依赖。

// CoordinateDialog.h
#include <QDialog>
#include <QVector3D>

class CoordinateDialogPrivate;  // 前向声明私有类
class CoordinateDialog : public QDialog
{
  Q_OBJECT
  Q_DECLARE_PRIVATE(CoordinateDialog)  // 声明私有指针
#if QT_VERSION <= QT_VERSION_CHECK(5,0,0)
  Q_PRIVATE_SLOT(d_func(), void onAccepted())  // 兼容Qt 4的私有槽
#endif
  QScopedPointer<CoordinateDialogPrivate> const d_ptr;  // 智能指针管理私有类实例
public:
  CoordinateDialog(QWidget * parent = 0, Qt::WindowFlags flags = 0);
  ~CoordinateDialog();
  QVector3D coordinates() const;
  Q_SIGNAL void acceptedCoordinates(const QVector3D &);
};
Q_DECLARE_METATYPE(QVector3D)

对比非PIMPL接口

不使用PIMPL的接口如下所示，尽管实现更为简单，但是头文件中包含了大量实现细节，违反了接口与实现分离的原则。

// CoordinateDialog.h
#include <QDialog>
#include <QVector3D>
#include <QFormLayout>
#include <QDoubleSpinBox>
#include <QDialogButtonBox>

class CoordinateDialog : public QDialog
{
  QFormLayout m_layout;
  QDoubleSpinBox m_x, m_y, m_z;
  QVector3D m_coordinates;
  QDialogButtonBox m_buttons;
  Q_SLOT void onAccepted();
public:
  CoordinateDialog(QWidget * parent = 0, Qt::WindowFlags flags = 0);
  QVector3D coordinates() const;
  Q_SIGNAL void acceptedCoordinates(const QVector3D &);
};
Q_DECLARE_METATYPE(QVector3D)

实现细节

下面详细介绍PIMPL实现的各个部分。

接口文件（Header）部分

// CoordinateDialog.h
#include <QDialog>
#include <QVector3D>

class CoordinateDialogPrivate;  // 前向声明
class CoordinateDialog : public QDialog
{
  Q_OBJECT
  Q_DECLARE_PRIVATE(CoordinateDialog)  // 声明私有指针
#if QT_VERSION <= QT_VERSION_CHECK(5,0,0)
  Q_PRIVATE_SLOT(d_func(), void onAccepted())  // 兼容Qt 4的私有槽
#endif
  QScopedPointer<CoordinateDialogPrivate> const d_ptr;  // 智能指针管理私有类实例
public:
  CoordinateDialog(QWidget * parent = 0, Qt::WindowFlags flags = 0);
  ~CoordinateDialog();
  QVector3D coordinates() const;
  Q_SIGNAL void acceptedCoordinates(const QVector3D &);
};
Q_DECLARE_METATYPE(QVector3D)

实现文件（Source）部分

// CoordinateDialog.cpp
#include "CoordinateDialog.h"
#include <QFormLayout>
#include <QDoubleSpinBox>
#include <QDialogButtonBox>

// 私有类的定义
class CoordinateDialogPrivate {
  Q_DISABLE_COPY(CoordinateDialogPrivate)  // 禁用拷贝
  Q_DECLARE_PUBLIC(CoordinateDialog)  // 声明公有指针
  CoordinateDialog * const q_ptr;  // 指向公有类实例的指针
  QFormLayout layout;
  QDoubleSpinBox x, y, z;
  QDialogButtonBox buttons;
  QVector3D coordinates;
  void onAccepted();
  CoordinateDialogPrivate(CoordinateDialog*);
};

CoordinateDialogPrivate::CoordinateDialogPrivate(CoordinateDialog *dialog) :
  q_ptr(dialog),
  layout(dialog),
  buttons(QDialogButtonBox::Ok | QDialogButtonBox::Cancel)
{
  layout.addRow("X", &x);
  layout.addRow("Y", &y);
  layout.addRow("Z", &z);
  layout.addRow(&buttons);
  dialog->connect(&buttons, SIGNAL(accepted()), SLOT(accept()));
  dialog->connect(&buttons, SIGNAL(rejected()), SLOT(reject()));
#if QT_VERSION <= QT_VERSION_CHECK(5,0,0)
  this->connect(dialog, SIGNAL(accepted()), SLOT(onAccepted()));
#else
  QObject::connect(dialog, &QDialog::accepted, [this]{ onAccepted(); });
#endif
}

void CoordinateDialogPrivate::onAccepted() {
  Q_Q(CoordinateDialog);  // 声明指向公有类实例的指针
  coordinates.setX(x.value());
  coordinates.setY(y.value());
  coordinates.setZ(z.value());
  emit q->acceptedCoordinates(coordinates);
}

CoordinateDialog::CoordinateDialog(QWidget *parent, Qt::WindowFlags flags) :
  QDialog(parent, flags),
  d_ptr(new CoordinateDialogPrivate(this))  // 初始化私有数据指针
{}

QVector3D CoordinateDialog::coordinates() const {
  Q_D(const CoordinateDialog);  // 声明指向私有数据的指针
  return d->coordinates;
}

CoordinateDialog::~CoordinateDialog() {}

关键宏解释

• Q_DECLARE_PRIVATE(Class): 声明私有指针，d_func()返回指向私有类实例的指针。
• Q_PRIVATE_SLOT(instance_pointer, method signature): 用来声明私有槽，仅用于Qt 4或非C++11兼容项目。
• Q_DISABLE_COPY(Class): 禁用复制和赋值操作。
• Q_DECLARE_PUBLIC(Class): 声明公有指针，q_func()返回指向公有类实例的指针。

常见问题与注意事项

1. 头文件包含顺序：在实现文件中，接口文件必须首先包含。
2. 私有类的定义：私有类不能在公有类内部定义。
3. Q_ 宏的使用：宏的定义中已经包含了分号，因此无需额外添加分号。