Tutorial: Creating an RCC Plugin

Table of Contents

 

Introduction

QCAD comes with a powerful script interface that allows users to add their own custom menus and tools.

RCC plugins offer an easy way to pack a set of such custom QCAD scripts into one single file for easy distribution to its end users. An RCC file is essentially a virtual file system that contains files and directories. RCC files can also be compressed to reduce the file size. While the same can also be achieved through a C++ plugin that contains these resources, an RCC plugin is much easier to create as we do not need a C++ development environment and we don't have to write a single line of C++ code. We only need the rcc utility that comes with every Qt installation.

The exact same RCC plugin file works on all supported platforms (Windows, macOS, Linux / 32bit, 64bit, arm64).

Preparing the Script Files

To pack our custom scripts, we place them into a folder named "scripts" and sub folders as appropriate. For this example, we assume that we want to pack two custom tools called "MyTool1" and "MyTool2" into a single plugin file named "MyPlugin.rcc". The structure of our directories and files looks like this:

  •  scripts
    • MyTool1
      • MyTool1.js
      • MyTool1.svg
    • MyTool2
      • MyTool2.js
      • MyTool2.svg
  • MyPlugin.json

MyTool1.js and MyTool2.js are the script implementations of our new tools and MyTool1.svg and MyTool2.svg are their icons.

MyPlugin.json is a JSON file with metadata about our plugin.

Metadata JSON File

To tell QCAD more about our plugin, we need to include a simple metadata file with some information about our plugin. This information is shown in the about dialog of QCAD under "Plugins".

The MyPlugin.json file of our plugin contains the following:

{
 "ID": "MYPLUGIN",
 "Name": "My Plugin",
 "License": "Proprietary",
 "Version": "1.0.0",
 "Description": "Example RCC Plugin for QCAD",
 "URL": "https://qcad.org"
} 

While we can add any other information here, these are the keys QCAD reads and displays in the about dialog.

QRC File

To tell the rcc utility which files and directories we want to include in our virtual file system of our RCC file, we have to create a QRC file which defines how each file is mapped into the virtual file system of the RCC plugin:

<!DOCTYPE RCC><RCC version="1.0">
 <qresource>
  <file alias="MyPlugin.json">MyPlugin.json</file>
  <file alias="scripts/MyTool1/MyTool1.js">scripts/MyTool1/MyTool1.js</file>
  <file alias="scripts/MyTool1/MyTool1.svg">scripts/MyTool1/MyTool1.svg</file>
  <file alias="scripts/MyTool2/MyTool2.js">scripts/MyTool2/MyTool2.js</file>
  <file alias="scripts/MyTool2/MyTool2.svg">scripts/MyTool2/MyTool2.svg</file>
 </qresource>
</RCC> 

The Qt rcc Utility

To pack our files and directories into a single RCC plugin, we need the rcc utility that comes with every Qt installation. The rcc executable is located in the "bin" folder of your Qt installation on Windows or in the "libexec" folder on macOS or Linux.

The rcc utility is a command line tool. It does not come with a graphical user interface but has to be run on the command line or terminal of the operating system.

In the command line or terminal, we switch to the directory where we have prepared the scripts and other resources and run the rcc utility as follows:

rcc -binary MyPlugin.qrc -o MyPlugin.rcc

Additional switches are available for compression and other options. Please refer to the Qt website for details.

Deployment

To deploy the plugin on any platform (Windows, macOS or Linux), simply copy the MyPlugin.rcc file to the "plugins" directory of a QCAD Professional installation. QCAD supports RCC plugins starting from version 3.32.

The scripts of our tools will now be available to QCAD, almost as if we would have copied the contents of our scripts folder to the scripts folder of QCAD, with one difference: the files in RCC plugins are referenced with a leading colon, for example ":scripts/MyTool1/MyTool1.js". In most situations this does not have any effect for our scripts as QCAD automatically initializes all scripts from the virtual ":scripts" directory. However, if we want to, for example, check the existence of a script file, we need to use the path with a leading colon, for example:

if (new QFileInfo(":scripts/MyTool1/MyTool1.js").exists()) {
  ...
}