# &kde-frameworks;: KDesignerPlugin

`kgendesignerplugin`

1

`kgendesignerplugin`

Generates widget plugins for &Qt; Designer.

        kgendesignerplugin
        OPTIONS
        file

## Description

The custom widget plugins for &Qt; Designer usually follow a standard pattern, and the classes provided by the plugin mostly provide static information, along with function to create an instance that is normally just a simple constructor call. `kgendesignerplugin` allows developers of libraries that provide new widgets to create such a plugin without creating all the associated boilerplate code, by providing a simple ini-style description file.

`kgendesignerplugin` chooses sensible defaults for most settings, so minimal configuration is usually necessary.

## Options

`-o `file``

- The name for the generated C++ file. If not given, `stdout` will be used.

`-n `plugin-name``

- Provided for compatibility. The default value for the PluginName option in the input file.

`-g `group``

- Provided for compatibility. The default value for the DefaultGroup option in the input file.

`--author`

- Show author information.

`--license`

- Show license information.

`-h, --help`

- Show a brief help text.

`-v , --version`

- Show version information.

## File Format

The input file is an ini-style configuration file (specifically, it is in the format supported by the KConfig framework) that describes a set of widgets. It contains a `[Global]` section, providing general information about the plugin, and a section for each widget that should be included in the plugin.

The `[Global]` section can have the following entries:

`DefaultGroup`

- The default value for the `Group` entry in the class sections (default: "`Custom`", unless the `-g` option is given).

`Includes`

- A (comma-separated) list of required includes (default: empty). Note that the header files for the widgets specified later in file should not be listed here; instead, this is for special headers for the plugin's own use, like those for classes providing previews.

`PluginName`

- The name of the main C++ class in the plugin (default: "`WidgetsPlugin`", unless the `-n` option is given).

Each class should have its own `[`ClassName`]` section, which can include the following entries:

`CodeTemplate`

- The value returned by the `codeTemplate()` function of the plugin, which is marked for "future use" by &Qt; Designer (default: empty).

`ConstructorArgs`

- The arguments to pass to the constructor of the class given by `ImplClass`; these must be surrounded by parentheses (default: "`(parent)`"). The only variable guaranteed to be available is `parent`, which is the parent `QWidget` passed by &Qt; Designer.

  This entry is ignored if `CreateWidget` is set.

`CreateWidget`

- The code necessary to create an instance of the widget (default: uses `new` to create an instance of the class given by the `ImplClass` entry, passing the arguments specified by `ConstructorArgs`). See the notes for `ImplClass` and `ConstructorArgs`.

`DomXML`

- An &XML; UI description of the widget (default: the default provided by the &Qt; Designer plugin headers).

`Group`

- The group to display the widget under in &Qt; Designer (default: the value of the `DefaultGroup` entry in the `[Global]` section).

`IconName`

- The image file or standard icon name to use as the icon for this widget in the &Qt; Designer widget list (default: a PNG file named with the section name, with any double colons removed, in the "pics" directory of a compiled-in resource file; for example, `:/pics/Foo.png` in the section `[Foo]`, or `:/pics/FooBar.png` in the section `[Foo::Bar]`).

`ImplClass`

- The class that should be used to create an instance of the widget for the use of &Qt; Designer (default: the section name). Note that this does not actually have to be the class that would be created for an end application: that is determined by the `DomXML`.

  This entry is ignored if `CreateWidget` is set.

`IncludeFile`

- The header that needs to be included to use this widget (default: the lowercase version of the section name, with any colons removed and ".h" appended; for example, `foo.h` in the section `[Foo]`, or `foobar.h` in the section `[Foo::Bar]`).

`IsContainer`

- Whether this widget can contain other widgets (default: `false`).

`ToolTip`

- The tooltip to display when hovering over the widget in the widget list of &Qt; Designer (default: the section name, with " Widget" appended; for example, `Foo Widget` in the section `[Foo]`).

`WhatsThis`

- The What's This text associated with the widget in &Qt; Designer (default: the section name, with " Widget" appended; for example, `Foo Widget` in the section `[Foo]`).

## Examples

The simplest description file might look like:

    [Foo]
    ToolTip=Displays foos
    [Bar]
    ToolTip=Bar editor

Note that each class must have at least one key set (`ToolTip` was used in this example), otherwise it will be ignored.

Usually, you want to change at least the user-visible text, which means the `ToolTip`, `WhatsThis` and `Group` entries. Additionally, setting the plugin name can be a good idea to prevent possible symbol clashes and not confuse debuggers (both the debugger application and the person doing the debugging):

    [Global]
    PluginName=FooWidgets
    DefaultGroup=Display

    [Foo]
    ToolTip=Displays bears
    WhatsThis=An image widget that displays dancing bears

    [Bar]
    ToolTip=Bar editor
    WhatsThis=An editor interface for bars for bears
    Group=Editing

More complex files may be necessary if you have namespaced classes or extra options that need supplying to constructors, for example:

    [Global]
    PluginName=FooWidgets
    DefaultGroup=Foo

    [Foo::Bar]
    ToolTip=Displays bars
    WhatsThis=A widget that displays bars in a particular way
    IncludeFile=foo/bar.h
    IconName=:/previews/bar.png

    [Foo::Baz]
    IncludeFile=foo/baz.h
    ConstructorArgs=(Foo::Baz::SomeOption, parent)
    Group=Foo (Special)
    IsContainer=true
    IconName=:/previews/baz.png

Sometimes especially complex widgets might need a special "preview class" implementation for use in &Qt; Designer; this might be a subclass of the real widget that just does some extra setup, or it might be a completely different implementation.

    [Global]
    Includes=foopreviews.h

    [FancyWidget]
    ImplClass=FancyWidgetPreview

## See Also

https://doc.qt.io/qt-5/designer-creating-custom-widgets.html

- The &Qt; Designer documentation on creating plugins for custom widgets.

## Bugs

Please use &kde;'s bugtracker to report bugs, do not mail the authors directly.