[kde-doc-english] [kdesignerplugin] docs/kgendesignerplugin: Improve the kgendesignerplugin man page
Alex Merry
alex.merry at kde.org
Sun Jun 1 10:14:51 UTC 2014
Git commit 06639fdb89820bc62805a9ae680f97d5e39db4dd by Alex Merry.
Committed on 28/05/2014 at 15:44.
Pushed by alexmerry into branch 'master'.
Improve the kgendesignerplugin man page
The options now match what is actually accepted, the authors section
properly reflects the authors of the man page, rather than the tool, the
description is more comprehensive and the input file format is
documented.
REVIEW: 118384
M +402 -133 docs/kgendesignerplugin/man-kgendesignerplugin.1.docbook
http://commits.kde.org/kdesignerplugin/06639fdb89820bc62805a9ae680f97d5e39db4dd
diff --git a/docs/kgendesignerplugin/man-kgendesignerplugin.1.docbook b/docs/kgendesignerplugin/man-kgendesignerplugin.1.docbook
index c1c349d..57aea63 100644
--- a/docs/kgendesignerplugin/man-kgendesignerplugin.1.docbook
+++ b/docs/kgendesignerplugin/man-kgendesignerplugin.1.docbook
@@ -5,162 +5,431 @@
]>
<refentry lang="&language;">
+
<refentryinfo>
-<title>Programming Tool</title>
-
-<author>
-<firstname>Ian</firstname>
-<othername>Reinhart</othername>
-<surname>Geiser</surname>
-<affiliation>
-<address>
-<email>geiseri at kde.org</email>
-</address>
-</affiliation>
-</author>
-
-<date>2006-06-01</date>
-<productname>K Desktop Environment</productname>
+ <title>&kde; Frameworks: KDesignerPlugin</title>
+ <author>
+ <firstname>Richard</firstname>
+ <surname>Johnson</surname>
+ <contrib>Wrote the original documentation.</contrib>
+ <affiliation>
+ <address><email>rjohnson at 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 at 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>
+ <refentrytitle><command>kgendesignerplugin</command></refentrytitle>
+ <manvolnum>1</manvolnum>
</refmeta>
+
+
<refnamediv>
-<refname>kgendesignerplugin</refname>
-<refpurpose>
-Builds &Qt; widget plugins from an ini style description file.
-</refpurpose>
+ <refname><command>kgendesignerplugin</command></refname>
+ <refpurpose>
+ Generates widget plugins for &Qt; Designer.
+ </refpurpose>
</refnamediv>
+
+
<refsynopsisdiv>
-<cmdsynopsis>
-<command>kgendesignerplugin</command>
-<arg>&Qt;-options</arg>
-<arg>&kde;-options</arg>
-<arg choice="plain"><replaceable>file</replaceable></arg>
-</cmdsynopsis>
+ <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>Description</title>
-<para>
-<command>kgendesignerplugin</command> builds &Qt; widget plugins from an ini style description file.
-</para>
+ <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>Options</title>
-
-<para>
-<variablelist>
-<title><emphasis role="bold">Arguments:</emphasis></title>
-<varlistentry>
-<term>
-<replaceable>file</replaceable>
-</term>
-<listitem>
-<para>Input file</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<para>
-<variablelist>
-<title><emphasis role="bold">Options:</emphasis></title>
-<varlistentry>
-<term>
-<option>-o <file></option>
-</term>
-<listitem>
-<para>Output file</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>
-<option>-n <plugin name></option>
-</term>
-<listitem>
-<para>Name of the plugin class to generate (deprecated, use PluginName in the input file) [WidgetsPlugin]</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>
-<option>-g <group></option>
-</term>
-<listitem>
-<para>Default widget group name to display in designer (deprecated, use DefaultGroup in the input file) [Custom]</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<para>
-<variablelist>
-<title><emphasis role="bold">Generic options:</emphasis></title>
-
-<varlistentry>
-<term>
-<option>--help</option>
-</term>
-<listitem>
-<para>Show help about options</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-<option>--author</option>
-</term>
-<listitem>
-<para>Show author information</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-<option>-v, --version</option>
-</term>
-<listitem>
-<para>Show version information</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-<option>--license</option>
-</term>
-<listitem>
-<para>Show license information</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
+ <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>
-<option>http://developer.kde.org</option>
-</term>
-<listitem>
-<para>&kde; Developer's Corner website</para>
-</listitem>
-</varlistentry>
-</variablelist>
+ <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>
+ <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
+-->
More information about the kde-doc-english
mailing list