NAME

       kgendesignerplugin - Generates widget plugins for Qt(TM) Designer.

SYNOPSIS

       kgendesignerplugin [OPTIONS...] file

DESCRIPTION

       The custom widget plugins for Qt(TM) 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(TM) 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(TM) 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(TM) Designer plugin
           headers).

       Group
           The group to display the widget under in Qt(TM) 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(TM) 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(TM) 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(TM) 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(TM) 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(TM) 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(TM) Designer documentation on creating plugins for custom widgets.

BUGS

       Please use bugs.kde.org[1] to report bugs, do not mail the authors directly.

AUTHORS

       Richard Johnson <rjohnson@kde.org>
           Wrote the original documentation.

       Alex Merry <alexmerry@kde.org>
           Updated the documentation for KDE Frameworks 5.

NOTES

        1. bugs.kde.org
           http://bugs.kde.org