CopperSpice Overview
Migration Notes

The first step is to run PepperMill on your application and then update your build files. If your project is already using CMake this should be a quick process and pretty simple. Once these two steps are done there may be additional modifications which need to be done by hand or a few simple search and replace passes. The following notes were collated from other developers who have been through the migration.

  1. Run PepperMill
  2. Modifications to your CMake build files
    • change your build files to enable C++17
    • remove any lines which refer to AUTOMOC
    • replace any lines which refer to AUTOUIC with the following syntax
      // run uic to generate source
    • update the call to find_package
      // prior syntax
      find_package(Qt4 REQUIRED QtCore QtGui QtMultimedia QtNetwork QtSql)
      // replacement syntax
      find_package(CopperSpice REQUIRED)
    • update all library references in the style shown below
      Prior SyntaxReplacement Syntax
      Qt4::QtCore CopperSpice::CsCore
      Qt4::QtGui CopperSpice::CsGui
      Qt4::QtMultimedia CopperSpice::CsMultimedia
      Qt4::QtNetwork CopperSpice::CsNetwork
      Qt4::QtSql CopperSpice::CsSql
    • list the libraries and plugins your application will require at run time
    • these calls are added in your root project CMakeLists.txt file
      // copies the specified CS libraries to your project install prefix
      // installs the platform Gui plugins
      // installs the platform Printer driver plugin
      // installs the platform Multimedia plugins
      // installs the OpenGL plugin
      // installs the MySQL/MariaDB plugin
      // installs the PostgreSQL plugin
      // installs the plugin for loading SVG images
    • if your project contains a .qrc file add the following
    • if your project contains a .ui file add the following
    • For an example refer to this project cmake build file

  3. Source code changes: Strings
    • QString::isNull() was removed, replace with QString::isEmpty()
    • replace toAscii().constData() with toLatin1().constData()
    • replace arg() with formatArg(), refer to QStringParser
    • replace toInt() with toInteger<int>
    • QString::SplitBehavior enum moved to QStringParser
      // prior code
      // new syntax
    • add explicit conversion to QString()
      // prior code
      QString text = (var == Images::Continuous) ? "Continuous" : "Once";
      // new syntax
      QString text = (var == Images::Continuous) ? QString("Continuous") : QString("Once");

  4. Source code changes: Languages/Locales
    • replace countriesForLanguage() with matchingLocales()
      // prior code
      QLocale::Language langId = QLocale::German;
      QList<QLocale::Country> countryList = QLocale::countriesForLanguage(langId);
      for (auto country : countryList) {
      QString label = QLocale::languageToString(langId) + "/" + QLocale::countryToString(country);
      // examples will include "German/Germany", "German/Switzerland", "German/Austria", etc
      // new syntax
      QLocale::Language langId = QLocale::German;
      QList<QLocale> localeList = QLocale::matchingLocales(langId, QLocale::AnyScript, QLocale::AnyCountry);
      for (auto locale : localeList) {
      QString label = QLocale::languageToString(langId) + "/" + QLocale::countryToString(;
      // examples will include "German/Germany", "German/Switzerland", "German/Austria", etc

  5. Source code changes: General
    • replace enum type QFileDialog::Options with QFileDialog::FileDialogOptions

    • regular expressions
      QString line = "some text";
      // prior syntax
      QString str = line.section(QRegularExpression("(\\s)+"), 0, 0);
      // new syntax
      QString str = QStringParser::section(line, QRegularExpression("(\\s)+", 0, 0));
    • replacement for foreach and forever
      // prior syntax
      foreach (x, y) {
      // new syntax
      for (x : y) {
      // prior syntax
      forever {
      // new syntax
      while true() {

  6. Source code changes: Enum Change
    • enum Qt::Modifier removed, use enum Qt::KeyboardModifier
      Obsolete Replace With
      Qt::ALT (or Qt::Modifier::ALT) Qt::KeyboardModifier::AltModifier
      Qt::CTRL (or Qt::Modifier::CTRL) Qt::KeyboardModifier::ControlModifier
      Qt::META (or Qt::Modifier::META) Qt::KeyboardModifier::MetaModifier
      Qt::SHIFT (or Qt::Modifier::SHIFT) Qt::KeyboardModifier::ShiftModifier

  7. Source code changes: Headers
    • CsCore header file name changes
      Obsolete Header File Use these Header File Names
      #include <Qt> #include <qnamespace.h>
      #include <QtNamespace> #include <qnamespace.h>
      #include <QtAlgorithms> #include <qalgorithms.h>
      #include <QtGlobal> #include <qglobal.h>
      #include <QtEndian> #include <qendian.h>
      #include <qt.h> #include <qnamespace.h>
    • CsMultimedia header file name changes
      Prior Header Name New Header Name
      #include <qmediaserviceproviderplugin.h> #include <qmediaservice_provider_plugin.h>
    • CsNetwork header file name changes
      Prior Header Name New Header Name
      #include <QNetworkAccessManager> #include <QAccess_Manager>
      #include <QNetAccess_Manager>
      #include <QAbstractNetworkCache> #include <QAbstract_NetworkCache>
      #include <QHttpHeader> #include <QHttp_Header>
      #include <QHttpMultiPart> #include <QHttp_MultiPart>
      #include <QHttpPart> #include <QHttp_Part>
      #include <QNetworkCacheMetaData> #include <QNetwork_CacheMetaData>
      #include <QNetworkCookie> #include <QNetwork_Cookie>
      #include <QNetworkCookieJar> #include <QNetwork_CookieJar>
      #include <QNetworkDiskCache> #include <QNetwork_DiskCache>
      #include <QNetworkReply> #include <QNetwork_Reply>
      #include <QNetworkRequest> #include <QNetwork_Request>
      #include <QSslCertificateExtension> #include <QSslCertificate_Extension>

  8. Source code changes: QVariant
    • QVariant and QMetaType changes as of CopperSpice 1.7
    • complete redesign and refactoring of the entire QVariant system
    • QVariant uses std::variant for storing its data
    • property system returns a QVariant::Type, prior return type was QMetaType::Type
    • macro Q_DECLARE_METATYPE(Type) has been changed to CS_DECLARE_METATYPE(Type)
    • QMetaType has been removed since it is obsolete
    • change QVariant::constData() to call QVariant::getData()
    • remove qRegisterMetaTypeStreamOperators<T> since it is obsolete
    • change calls to QVariant::isNull()
      • use QVariant::isValid() and invert logic
    • changes for qVariantValue or qvariant_cast
      // prior syntax for either call
      // new syntax
    • change for qMetaTypeId
      • metaType id is automatically assigned the first time it is needed
      // prior syntax
      qMetaTypeId<QIODevice *>();
      // new syntax
      QVariant::typeToTypeId<QIODevice *>();
    • remove qRegisterMetaType<T> since it is obsolete
      • metaType id is automatically assigned the first time it is needed

  9. Source code changes: QVariant constructors for GUI Enums
    • Several enum types which were implicitly convertible to a QVariant must now be explicitly constructed
      Enum Types Used in Class
      Qt::BrushStyle QBrush
      Qt::CursorShape QCursor
      Qt::GlobalColor QColor
      Qt::PenStyle QPen
      // prior syntax
      QVariant colorA = Qt::red;
      // new syntax
      QVariant colorB = QColor(Qt::red);

  10. Source code changes: Signals / Slots
    • QObject::receivers() takes one QString as its argument, the SIGNAL macro expands to two strings
      // prior code
      // new syntax
    • if you declared an overloaded Signal or Slot replace the CS_SIGNAL_2() or CS_SLOT_2() macro calls with CS_SIGNAL_OVERLOAD() or CS_SLOT_OVERLOAD()
    • for parameters passed to a method with an associated tag, modify the CS_TAG() macro parameter list

  11. Source code changes: Print Settings
    • setPageMargins()
      // prior code
      printer->setPageMargins(0.00, 0.00, 0.00, 0.00, QPageSize::Unit::Inch);
      // new syntax
      printer->setPageMargins(QMarginsF(0.00, 0.00, 0.00, 0.00), QPageSize::Unit::Inch);
    • enum value QPrinter::Inch should be QPageSize::Unit::Inch
    • enum value QPrinter::Letter should be QPageSize::PageSizeId::Letter