<?xml version="1.0" ?>
<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
"dtd/kdedbx45.dtd" [
<!ENTITY % English "INCLUDE">
]>

<refentry lang="&language;">

<refentryinfo>
  <title>&kde; Frameworks: KDesignerPlugin</title>
  <author>
    <firstname>Richard</firstname>
    <surname>Johnson</surname>
    <contrib>Wrote the original documentation.</contrib>
    <affiliation>
      <address><email>rjohnson@kde.org</email></address>
    </affiliation>
  </author>
  <author>
    <firstname>Alex</firstname>
    <surname>Merry</surname>
    <contrib>Updated the documentation for &kde; Frameworks 5.</contrib>
    <affiliation>
      <address><email>alexmerry@kde.org</email></address>
    </affiliation>
  </author>
  <date>2014-05-28</date>
  <releaseinfo>5.0</releaseinfo>
</refentryinfo>

<refmeta>
  <refentrytitle><command>kgendesignerplugin</command></refentrytitle>
  <manvolnum>1</manvolnum>
</refmeta>



<refnamediv>
  <refname><command>kgendesignerplugin</command></refname>
  <refpurpose>
    Generates widget plugins for &Qt; Designer.
  </refpurpose>
</refnamediv>



<refsynopsisdiv>
  <cmdsynopsis>
    <command>kgendesignerplugin</command>
    <group choice="opt" rep="repeat"><replaceable class="option">OPTIONS</replaceable></group>
    <arg choice="plain"><replaceable>file</replaceable></arg>
  </cmdsynopsis>
</refsynopsisdiv>



<refsect1>
  <title>Description</title>
  <para>
    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. <command>kgendesignerplugin</command>
    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.
  </para>

  <para>
    <command>kgendesignerplugin</command> chooses sensible defaults for most
    settings, so minimal configuration is usually necessary.
  </para>
</refsect1>



<refsect1>
  <title>Options</title>
  <variablelist>
    <varlistentry>
      <term><option>-o <replaceable>file</replaceable></option></term>
      <listitem>
        <para>
          The name for the generated C++ file. If not given,
          <varname>stdout</varname> will be used.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-n <replaceable>plugin-name</replaceable></option></term>
      <listitem>
        <para>
          Provided for compatibility. The default value for the PluginName option in
          the input file.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-g <replaceable>group</replaceable></option></term>
      <listitem>
        <para>
          Provided for compatibility. The default value for the DefaultGroup
          option in the input file.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>--author</option></term>
      <listitem>
        <para>Show author information.</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>--license</option></term>
      <listitem>
        <para>Show license information.</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-h, --help</option></term>
      <listitem>
        <para>Show a brief help text.</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-v , --version</option></term>
      <listitem>
        <para>Show version information.</para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>



<refsect1>
  <title>File Format</title>
  <para>
    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 <literal>[Global]</literal> section, providing general information
    about the plugin, and a section for each widget that should be included in the
    plugin.
  </para>

  <para>
    The <literal>[Global]</literal> section can have the following entries:
    <variablelist>
      <varlistentry>
        <term><varname>DefaultGroup</varname></term>
        <listitem>
          <para>
            The default value for the <varname>Group</varname>
            entry in the class sections (default: "<literal>Custom</literal>",
            unless the <option>-g</option> option is given).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>Includes</varname></term>
        <listitem>
          <para>
            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.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>PluginName</varname></term>
        <listitem>
          <para>
            The name of the main C++ class in the plugin (default:
            "<literal>WidgetsPlugin</literal>", unless the <option>-n</option>
            option is given).
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </para>

  <para>
    Each class should have its own
    <literal>[<replaceable>ClassName</replaceable>]</literal> section, which can include
    the following entries:
    <variablelist>
      <varlistentry>
        <term><varname>CodeTemplate</varname></term>
        <listitem>
          <para>
            The value returned by the <code>codeTemplate()</code> function of
            the plugin, which is marked for "future use" by &Qt; Designer
            (default: empty).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>ConstructorArgs</varname></term>
        <listitem>
          <para>
            The arguments to pass to the constructor of the class given by
            <literal>ImplClass</literal>; these must be surrounded by
            parentheses (default: "<literal>(parent)</literal>"). The only
            variable guaranteed to be available is <varname>parent</varname>,
            which is the parent <code>QWidget</code> passed by &Qt; Designer.
          </para>
          <para>
            This entry is ignored if <literal>CreateWidget</literal> is
            set.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>CreateWidget</varname></term>
        <listitem>
          <para>
            The code necessary to create an instance of the widget (default:
            uses <code>new</code> to create an instance of the class given by
            the <literal>ImplClass</literal> entry, passing the arguments
            specified by <literal>ConstructorArgs</literal>). See the notes for
            <literal>ImplClass</literal> and <literal>ConstructorArgs</literal>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>DomXML</varname></term>
        <listitem>
          <para>
            An XML UI description of the widget (default: the default provided
            by the &Qt; Designer plugin headers).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>Group</varname></term>
        <listitem>
          <para>
            The group to display the widget under in &Qt; Designer (default: the
            value of the <varname>DefaultGroup</varname> entry in the
            <literal>[Global]</literal> section).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>IconName</varname></term>
        <listitem>
          <para>
            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,
            <filename>:/pics/Foo.png</filename> in the section
            <literal>[Foo]</literal>, or <filename>:/pics/FooBar.png</filename>
            in the section <literal>[Foo::Bar]</literal>).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>ImplClass</varname></term>
        <listitem>
          <para>
            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
            <literal>DomXML</literal>.
          </para>
          <para>
            This entry is ignored if <literal>CreateWidget</literal> is
            set.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>IncludeFile</varname></term>
        <listitem>
          <para>
            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, <literal>foo.h</literal> in the
            section <literal>[Foo]</literal>, or <literal>foobar.h</literal> in
            the section <literal>[Foo::Bar]</literal>).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>IsContainer</varname></term>
        <listitem>
          <para>
            Whether this widget can contain other widgets (default:
            <literal>false</literal>).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>ToolTip</varname></term>
        <listitem>
          <para>
            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, <literal>Foo Widget</literal> in the section
            <literal>[Foo]</literal>).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>WhatsThis</varname></term>
        <listitem>
          <para>
            The What's This text associated with the widget in &Qt; Designer
            (default: the section name, with " Widget" appended; for example,
            <literal>Foo Widget</literal> in the section
            <literal>[Foo]</literal>).
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </para>
</refsect1>



<refsect1>
  <title>Examples</title>
  <para>
    The simplest description file might look like
    <screen language="ini">
<![CDATA[
[Foo]
ToolTip=Displays foos
[Bar]
ToolTip=Bar editor
]]>
    </screen>
    Note that each class must have at least one key set
    (<literal>ToolTip</literal> was used in this example), otherwise it will be
    ignored.
  </para>
  <para>
    Usually, you want to change at least the user-visible text, which means the
    <literal>ToolTip</literal>, <literal>WhatsThis</literal> and
    <literal>Group</literal> 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):
    <screen language="ini">
<![CDATA[
[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
]]>
    </screen>
  </para>
  <para>
    More complex files may be necessary if you have namespaced classes or extra
    options that need supplying to constructors, for example:
    <screen language="ini">
<![CDATA[
[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
]]>
    </screen>
  </para>
  <para>
    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.
    <screen language="ini">
<![CDATA[
[Global]
Includes=foopreviews.h

[FancyWidget]
ImplClass=FancyWidgetPreview
]]>
    </screen>
  </para>
</refsect1>



<refsect1>
  <title>See Also</title>
  <variablelist>
    <varlistentry>
      <term>
        <uri>http://qt-project.org/doc/qt-5/designer-creating-custom-widgets.html</uri>
      </term>
      <listitem>
        <para>The &Qt; Designer documentation on creating plugins for custom widgets.</para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>



<refsect1>
  <title>Bugs</title>
  <para>
    Please use <ulink url="http://bugs.kde.org">bugs.kde.org</ulink> to report
    bugs, do not mail the authors directly.
  </para>
</refsect1>

</refentry>
<!--
vim:sts=2:sw=2:et
-->
