Warning, /frameworks/kdesignerplugin/docs/kgendesignerplugin/man-kgendesignerplugin.1.docbook is written in an unsupported language. File is not indexed.
0001 <?xml version="1.0" ?> 0002 <!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" 0003 "dtd/kdedbx45.dtd" [ 0004 <!ENTITY % English "INCLUDE"> 0005 ]> 0006 0007 <refentry lang="&language;"> 0008 0009 <refentryinfo> 0010 <title>&kde-frameworks;: KDesignerPlugin</title> 0011 <author> 0012 <firstname>Richard</firstname> 0013 <surname>Johnson</surname> 0014 <contrib>Wrote the original documentation.</contrib> 0015 <affiliation> 0016 <address><email>rjohnson@kde.org</email></address> 0017 </affiliation> 0018 </author> 0019 <author> 0020 <firstname>Alex</firstname> 0021 <surname>Merry</surname> 0022 <contrib>Updated the documentation for &kf5-full;.</contrib> 0023 <affiliation> 0024 <address><email>alexmerry@kde.org</email></address> 0025 </affiliation> 0026 </author> 0027 <date>2014-05-28</date> 0028 <releaseinfo>Frameworks 5.0</releaseinfo> 0029 <productname>KDE Frameworks</productname> 0030 </refentryinfo> 0031 0032 <refmeta> 0033 <refentrytitle><command>kgendesignerplugin</command></refentrytitle> 0034 <manvolnum>1</manvolnum> 0035 </refmeta> 0036 0037 0038 0039 <refnamediv> 0040 <refname><command>kgendesignerplugin</command></refname> 0041 <refpurpose> 0042 Generates widget plugins for &Qt; Designer. 0043 </refpurpose> 0044 </refnamediv> 0045 0046 0047 0048 <refsynopsisdiv> 0049 <cmdsynopsis> 0050 <command>kgendesignerplugin</command> 0051 <group choice="opt" rep="repeat"><replaceable class="option">OPTIONS</replaceable></group> 0052 <arg choice="plain"><replaceable>file</replaceable></arg> 0053 </cmdsynopsis> 0054 </refsynopsisdiv> 0055 0056 0057 0058 <refsect1> 0059 <title>Description</title> 0060 <para> 0061 The custom widget plugins for &Qt; Designer usually follow a standard 0062 pattern, and the classes provided by the plugin mostly provide static 0063 information, along with function to create an instance that is normally 0064 just a simple constructor call. <command>kgendesignerplugin</command> 0065 allows developers of libraries that provide new widgets to create such a 0066 plugin without creating all the associated boilerplate code, by providing a 0067 simple ini-style description file. 0068 </para> 0069 0070 <para> 0071 <command>kgendesignerplugin</command> chooses sensible defaults for most 0072 settings, so minimal configuration is usually necessary. 0073 </para> 0074 </refsect1> 0075 0076 0077 0078 <refsect1> 0079 <title>Options</title> 0080 <variablelist> 0081 <varlistentry> 0082 <term><option>-o <replaceable>file</replaceable></option></term> 0083 <listitem> 0084 <para> 0085 The name for the generated C++ file. If not given, 0086 <varname>stdout</varname> will be used. 0087 </para> 0088 </listitem> 0089 </varlistentry> 0090 <varlistentry> 0091 <term><option>-n <replaceable>plugin-name</replaceable></option></term> 0092 <listitem> 0093 <para> 0094 Provided for compatibility. The default value for the PluginName option in 0095 the input file. 0096 </para> 0097 </listitem> 0098 </varlistentry> 0099 <varlistentry> 0100 <term><option>-g <replaceable>group</replaceable></option></term> 0101 <listitem> 0102 <para> 0103 Provided for compatibility. The default value for the DefaultGroup 0104 option in the input file. 0105 </para> 0106 </listitem> 0107 </varlistentry> 0108 <varlistentry> 0109 <term><option>--author</option></term> 0110 <listitem> 0111 <para>Show author information.</para> 0112 </listitem> 0113 </varlistentry> 0114 <varlistentry> 0115 <term><option>--license</option></term> 0116 <listitem> 0117 <para>Show license information.</para> 0118 </listitem> 0119 </varlistentry> 0120 <varlistentry> 0121 <term><option>-h, --help</option></term> 0122 <listitem> 0123 <para>Show a brief help text.</para> 0124 </listitem> 0125 </varlistentry> 0126 <varlistentry> 0127 <term><option>-v , --version</option></term> 0128 <listitem> 0129 <para>Show version information.</para> 0130 </listitem> 0131 </varlistentry> 0132 </variablelist> 0133 </refsect1> 0134 0135 0136 0137 <refsect1> 0138 <title>File Format</title> 0139 <para> 0140 The input file is an ini-style configuration file (specifically, it is in the 0141 format supported by the KConfig framework) that describes a set of widgets. It 0142 contains a <literal>[Global]</literal> section, providing general information 0143 about the plugin, and a section for each widget that should be included in the 0144 plugin. 0145 </para> 0146 0147 <para> 0148 The <literal>[Global]</literal> section can have the following entries: 0149 <variablelist> 0150 <varlistentry> 0151 <term><varname>DefaultGroup</varname></term> 0152 <listitem> 0153 <para> 0154 The default value for the <varname>Group</varname> 0155 entry in the class sections (default: "<literal>Custom</literal>", 0156 unless the <option>-g</option> option is given). 0157 </para> 0158 </listitem> 0159 </varlistentry> 0160 <varlistentry> 0161 <term><varname>Includes</varname></term> 0162 <listitem> 0163 <para> 0164 A (comma-separated) list of required includes (default: 0165 empty). Note that the header files for the widgets specified later 0166 in file should not be listed here; instead, this is for special 0167 headers for the plugin's own use, like those for classes providing 0168 previews. 0169 </para> 0170 </listitem> 0171 </varlistentry> 0172 <varlistentry> 0173 <term><varname>PluginName</varname></term> 0174 <listitem> 0175 <para> 0176 The name of the main C++ class in the plugin (default: 0177 "<literal>WidgetsPlugin</literal>", unless the <option>-n</option> 0178 option is given). 0179 </para> 0180 </listitem> 0181 </varlistentry> 0182 </variablelist> 0183 </para> 0184 0185 <para> 0186 Each class should have its own 0187 <literal>[<replaceable>ClassName</replaceable>]</literal> section, which can include 0188 the following entries: 0189 <variablelist> 0190 <varlistentry> 0191 <term><varname>CodeTemplate</varname></term> 0192 <listitem> 0193 <para> 0194 The value returned by the <code>codeTemplate()</code> function of 0195 the plugin, which is marked for "future use" by &Qt; Designer 0196 (default: empty). 0197 </para> 0198 </listitem> 0199 </varlistentry> 0200 <varlistentry> 0201 <term><varname>ConstructorArgs</varname></term> 0202 <listitem> 0203 <para> 0204 The arguments to pass to the constructor of the class given by 0205 <literal>ImplClass</literal>; these must be surrounded by 0206 parentheses (default: "<literal>(parent)</literal>"). The only 0207 variable guaranteed to be available is <varname>parent</varname>, 0208 which is the parent <code>QWidget</code> passed by &Qt; Designer. 0209 </para> 0210 <para> 0211 This entry is ignored if <literal>CreateWidget</literal> is 0212 set. 0213 </para> 0214 </listitem> 0215 </varlistentry> 0216 <varlistentry> 0217 <term><varname>CreateWidget</varname></term> 0218 <listitem> 0219 <para> 0220 The code necessary to create an instance of the widget (default: 0221 uses <code>new</code> to create an instance of the class given by 0222 the <literal>ImplClass</literal> entry, passing the arguments 0223 specified by <literal>ConstructorArgs</literal>). See the notes for 0224 <literal>ImplClass</literal> and <literal>ConstructorArgs</literal>. 0225 </para> 0226 </listitem> 0227 </varlistentry> 0228 <varlistentry> 0229 <term><varname>DomXML</varname></term> 0230 <listitem> 0231 <para> 0232 An &XML; UI description of the widget (default: the default provided 0233 by the &Qt; Designer plugin headers). 0234 </para> 0235 </listitem> 0236 </varlistentry> 0237 <varlistentry> 0238 <term><varname>Group</varname></term> 0239 <listitem> 0240 <para> 0241 The group to display the widget under in &Qt; Designer (default: the 0242 value of the <varname>DefaultGroup</varname> entry in the 0243 <literal>[Global]</literal> section). 0244 </para> 0245 </listitem> 0246 </varlistentry> 0247 <varlistentry> 0248 <term><varname>IconName</varname></term> 0249 <listitem> 0250 <para> 0251 The image file or standard icon name to use as the icon for this 0252 widget in the &Qt; Designer widget list (default: a PNG file named 0253 with the section name, with any double colons removed, in the "pics" 0254 directory of a compiled-in resource file; for example, 0255 <filename>:/pics/Foo.png</filename> in the section 0256 <literal>[Foo]</literal>, or <filename>:/pics/FooBar.png</filename> 0257 in the section <literal>[Foo::Bar]</literal>). 0258 </para> 0259 </listitem> 0260 </varlistentry> 0261 <varlistentry> 0262 <term><varname>ImplClass</varname></term> 0263 <listitem> 0264 <para> 0265 The class that should be used to create an instance of the widget for 0266 the use of &Qt; Designer (default: the section name). Note that this 0267 does not actually have to be the class that would be created for an 0268 end application: that is determined by the 0269 <literal>DomXML</literal>. 0270 </para> 0271 <para> 0272 This entry is ignored if <literal>CreateWidget</literal> is 0273 set. 0274 </para> 0275 </listitem> 0276 </varlistentry> 0277 <varlistentry> 0278 <term><varname>IncludeFile</varname></term> 0279 <listitem> 0280 <para> 0281 The header that needs to be included to use this widget (default: 0282 the lowercase version of the section name, with any colons removed 0283 and ".h" appended; for example, <literal>foo.h</literal> in the 0284 section <literal>[Foo]</literal>, or <literal>foobar.h</literal> in 0285 the section <literal>[Foo::Bar]</literal>). 0286 </para> 0287 </listitem> 0288 </varlistentry> 0289 <varlistentry> 0290 <term><varname>IsContainer</varname></term> 0291 <listitem> 0292 <para> 0293 Whether this widget can contain other widgets (default: 0294 <literal>false</literal>). 0295 </para> 0296 </listitem> 0297 </varlistentry> 0298 <varlistentry> 0299 <term><varname>ToolTip</varname></term> 0300 <listitem> 0301 <para> 0302 The tooltip to display when hovering over the widget in the widget 0303 list of &Qt; Designer (default: the section name, with " Widget" 0304 appended; for example, <literal>Foo Widget</literal> in the section 0305 <literal>[Foo]</literal>). 0306 </para> 0307 </listitem> 0308 </varlistentry> 0309 <varlistentry> 0310 <term><varname>WhatsThis</varname></term> 0311 <listitem> 0312 <para> 0313 The What's This text associated with the widget in &Qt; Designer 0314 (default: the section name, with " Widget" appended; for example, 0315 <literal>Foo Widget</literal> in the section 0316 <literal>[Foo]</literal>). 0317 </para> 0318 </listitem> 0319 </varlistentry> 0320 </variablelist> 0321 </para> 0322 </refsect1> 0323 0324 0325 0326 <refsect1> 0327 <title>Examples</title> 0328 <para> 0329 The simplest description file might look like: 0330 <screen language="ini"> 0331 <![CDATA[ 0332 [Foo] 0333 ToolTip=Displays foos 0334 [Bar] 0335 ToolTip=Bar editor 0336 ]]> 0337 </screen> 0338 Note that each class must have at least one key set 0339 (<literal>ToolTip</literal> was used in this example), otherwise it will be 0340 ignored. 0341 </para> 0342 <para> 0343 Usually, you want to change at least the user-visible text, which means the 0344 <literal>ToolTip</literal>, <literal>WhatsThis</literal> and 0345 <literal>Group</literal> entries. Additionally, setting the plugin name 0346 can be a good idea to prevent possible symbol clashes and not confuse 0347 debuggers (both the debugger application and the person doing the 0348 debugging): 0349 <screen language="ini"> 0350 <![CDATA[ 0351 [Global] 0352 PluginName=FooWidgets 0353 DefaultGroup=Display 0354 0355 [Foo] 0356 ToolTip=Displays bears 0357 WhatsThis=An image widget that displays dancing bears 0358 0359 [Bar] 0360 ToolTip=Bar editor 0361 WhatsThis=An editor interface for bars for bears 0362 Group=Editing 0363 ]]> 0364 </screen> 0365 </para> 0366 <para> 0367 More complex files may be necessary if you have namespaced classes or extra 0368 options that need supplying to constructors, for example: 0369 <screen language="ini"> 0370 <![CDATA[ 0371 [Global] 0372 PluginName=FooWidgets 0373 DefaultGroup=Foo 0374 0375 [Foo::Bar] 0376 ToolTip=Displays bars 0377 WhatsThis=A widget that displays bars in a particular way 0378 IncludeFile=foo/bar.h 0379 IconName=:/previews/bar.png 0380 0381 [Foo::Baz] 0382 IncludeFile=foo/baz.h 0383 ConstructorArgs=(Foo::Baz::SomeOption, parent) 0384 Group=Foo (Special) 0385 IsContainer=true 0386 IconName=:/previews/baz.png 0387 ]]> 0388 </screen> 0389 </para> 0390 <para> 0391 Sometimes especially complex widgets might need a special "preview class" 0392 implementation for use in &Qt; Designer; this might be a subclass of the 0393 real widget that just does some extra setup, or it might be a completely 0394 different implementation. 0395 <screen language="ini"> 0396 <![CDATA[ 0397 [Global] 0398 Includes=foopreviews.h 0399 0400 [FancyWidget] 0401 ImplClass=FancyWidgetPreview 0402 ]]> 0403 </screen> 0404 </para> 0405 </refsect1> 0406 0407 0408 0409 <refsect1> 0410 <title>See Also</title> 0411 <variablelist> 0412 <varlistentry> 0413 <term> 0414 <uri>https://doc.qt.io/qt-5/designer-creating-custom-widgets.html</uri> 0415 </term> 0416 <listitem> 0417 <para>The &Qt; Designer documentation on creating plugins for custom widgets.</para> 0418 </listitem> 0419 </varlistentry> 0420 </variablelist> 0421 </refsect1> 0422 0423 0424 0425 <refsect1> 0426 <title>Bugs</title> 0427 <para> 0428 Please use <ulink url="https://bugs.kde.org">&kde;'s bugtracker</ulink> to report 0429 bugs, do not mail the authors directly. 0430 </para> 0431 </refsect1> 0432 0433 </refentry> 0434 <!-- 0435 vim:sts=2:sw=2:et 0436 -->