Plugin_UI_forms

Table of Contents

• Plugin forms for Configuration Dialog
  • Global/local, persistable/transient
  • Config model
  • UI form
  • Telling ConfigDialog about the form
  • Using configured values
• Plugin forms for specific usage
  • Global/local, persistable/transient
  • Config model
  • UI form
  • Telling ExportDialog about the form
  • What about other plugins?
• See also

All plugins can provide a *.ui file to SQLiteStudio, so they can be configurable in the ConfigDialog. There are also some plugin types, that support additional forms, like for example ExportPlugin, which supports form file for configuring individual exporting process (the form is displayed in the export dialog).

Plugin forms for Configuration Dialog

This chapter describes the case when we create UI form for configuring plugin in ConfigDialog.

Global/local, persistable/transient

This method assumes that the plugin has its own single global configuration object, which can be accessed by the ConfigDialog. The configuration values are also persisted in the SQLiteStudio configuration file and restored after next application start.

Config model

In the plugin's project define the config category and form file. How to do it? Just add something like this in plugin's header:

CFG_CATEGORIES(MyPluginConfig,
    CFG_CATEGORY(SomeCategory,
        CFG_ENTRY(bool, SomeKey1, true)
        CFG_ENTRY(QString, SomeKey2, "abc")
    )
)
#define CFG_MY_PLUGIN CFG_INSTANCE(MyPluginConfig)

and you have to also add following statement in the according cpp file:

CFG_DEFINE(SqlFormatterSimpleConfig)

Why do you need that? I'll explaint it to you in more details later. Keep reading.

UI form

Create a form file ("ui" file) as a part of plugin's project.

Such forms ("ui" files) should be created as a part of plugin project and added to plugin's resources (using Qt's resource management, the "qrc" files). Put the form under "forms" prefix in the resources file. Name it whatever you like, just try to be unique, so the form name doesn't conflict with forms from other plugins.

Put checkbox and lineedit on your form - they will be used for "SomeKey1" and "SomeKey2" configuration values.

Select checkbox and add dynamic property of type String:

Enter name of the property: "cfg". New property has appeared at the bottom of properties for checkbox.

Put the value of the property: SomeCategory.SomeKey1

What you just did is you connected your checkbox with the config entry you defined earlier in the header. Do the same with lineedit - select it, create dynamic property "cfg" and set its value to: SomeCategory.SomeKey2

Also rename the top-most widget to something related with your plugin name, so it's also unique across the application. In our example, we will rename it to "MyPluginConfig", just like we named our config categories.

Telling ConfigDialog about the form

The ConfigDialog has to be told, that your plugin wants to be configurable.

• If you implement plugin basing on GenericPlugin (this is usually the case), then do following: In plugin's json file define the "ui" key with value pointing to the top-most widget name from your form:

  "ui":          "MyPluginConfig"

• If you don't base on GenericPlugin, then do folloging: Implement the Plugin::getConfigUiForm() so it returns string: MyPluginConfig.

Using configured values

In the plugin code you can refer to config entries using macro defined earlier:

bool key1Value = CFG_MY_PLUGIN.SomeCategory.SomeKey1.get();
QString s = "test";
CFG_MY_PLUGIN.SomeCategory.SomeKey2.set(s);

Plugin forms for specific usage

This chapter describes the case when we create UI for for plugins like ExportPlugin, ImportPlugin, etc. That is for plugins that support UI form displaying per individual use case, out of the ConfigDialog.

In this example we will create UI form for ExportPlugin. Other plugin types use very similar concept (if not equal).

Global/local, persistable/transient

This method assumes that the configuration model is not global, it's a member field of a plugin instance and it's not persisted in SQLiteStudio configuration file, therefore it's transient.

Config model

Define a config model. It's almost the same as in the method above, except we don't define the macro:

CFG_CATEGORIES(MyPluginConfig,
    CFG_CATEGORY(SomeCategory,
        CFG_ENTRY(bool, SomeKey1, true)
        CFG_ENTRY(QString, SomeKey2, "abc")
    )
)

then add instance of that config to your plugin's class:

class MyPlugin
{
    // ...
    private:
        CFG_LOCAL(MyPluginConfig, cfg)
};

UI form

Create the UI form exactly the same way you would do in the method above.

Telling ExportDialog about the form

Since we deal with a local instance of config model, not a global one, we need to tell ExportDialog about both form name and the config model instance. ExportPlugin has interface methods for both:

• ExportPlugin::getExportConfigFormName()
• ExportPlugin::getConfig()

First method should return name of the top-most widget name from the "ui" file. Second should return pointer to the embedded config model object. In this case implementation of the second method would look like:

MyPlugin::getConfig()
{
    return &cfg;
}

What about other plugins?

Each plugin type can support one or more forms for various use cases. This is determinated by the individual plugin type interface class, which tells you what optional or mandatory form names are expected by the plugin. Just go through plugin's interface class and see what methods refer to form names.

Usually code that uses such plugins is written in a way, that if form name returned from the plugin is null, then no form is assumed and getConfig() result is ignored. If form name is not null, then application looks up the form that start with a matching widget name.

See also

The Model-view binding covers the full subject of model-view framework, that makes all of above possible. Read it if you want to learn more details, tricks and possibilities.