New_plugin_from_scratch

Table of Contents

• Brief
• Short instruction
• Full instructions
  • Create new project
  • Include "pri" files
  • Add GUI dependency if necessary
  • Remove redundant statements
  • Plugin class

Brief

This tutorial covers creating plugins using QtCreator. Under Windows it's QtCreator with mingw support.

Short instruction

1. Create your plugin project from QtCreator (a shared library project), place it in directory next to the SQLiteStudio3.

2. Edit yourplugin.pro file and add at the top:

   include($$PWD/../SQLiteStudio3/plugins.pri)

3. Add yourplugin.json to your project and fill it with plugin's metadata information - see bottom of this page for example.

4. For instructions on how to write plugin class for each specific plugin see tutorial for that specific plugin.

Full instructions

Create new project

The project has to be of "Shared library" type. It's directory has to be placed next to the SQLiteStudio3 and Plugins directories (see the required directory structure).

If you want you can put your plugin into the Plugins directory as another plugin subproject. In that case you will also need to add your plugin's directory name to plugins.pro file.

Usually you will want to create a separate project, next to Plugins directory, not inside. It's easier this way for external plugins.

In the end you should have SQLiteStudio3, Plugins and YourPluginDir all in the same directory.

Include "pri" files

Currently there's only one file to include - a plugins.pri.

Add plugin-related "pri" files to your "PluginName.pro" file, so it knows all necessary paths and settings. Add it at the top of the "pro" file:

include($$PWD/../SQLiteStudio3/plugins.pri)

If you the plugin is placed as a subproject to the "Plugins" official SQLiteStudio project, then the path needs to reach one more level up:

include($$PWD/../../SQLiteStudio3/plugins.pri)

Add GUI dependency if necessary

This step is required only if your plugin is going to use anything from GUI client of SQLiteStudio, that is anything from SQLiteStudio3/SQLiteStudio directory. This is for example when you want to add some elements to the UI (buttons, menus, etc), or you want to use any symbols from GUI project, like functions from uiutils.h.

To enable GUI dependency for plugin, you have to add:

"gui": true

to your plugin's json file (see bottom of this page for more details on json file).

If you don't do that, SQLiteStudio will be trying to load GUI plugin even the CLI was started by the user and plugin will fail to load. While this is not a critical failure (plugin will just not load in CLI), it's still better to let SQLiteStudio know, that this is a GUI plugin in json file.

Remove redundant statements

You can remove following (or similar) statement from the "pro" file:

unix:!symbian {
    maemo5 {
        target.path = /opt/usr/lib
    } else {
        target.path = /usr/lib
    }
    INSTALLS += target
}

The necessary statements are already covered by the "plugins.pri" file included earlier. The one above would only cause warnings from the qmake.

Plugin class

The main plugin's class (the one that the QtCreator created by default for you) should have following declaration:

class YOURPLUGINSHARED_EXPORT YourPluginExport : public GenericPlugin, public GeneralPurposePlugin
{
    Q_OBJECT
    SQLITESTUDIO_PLUGIN("yourplugin.json")
    // ...
};

You can read about GenericPlugin here. The GeneralPurposePlugin is an interface class that your plugin will implement. You can pick other type, depending on the kind of plugin you want to implement. This is also a name of plugin type that you will put into Plugin's json file (see below).

The SQLITESTUDIO_PLUGIN macro is mandatory. It provides all necessary declarations for the class to become a valid SQLiteStudio plugin. It has a single argument, which is a name of the json file (see below). If the json file is in any subdirectory, provide a relative path to the file as an argument to this macro.