1KGENDESIGNERPLUGI(1) KDE Frameworks: KDesignerPlugi KGENDESIGNERPLUGI(1)
2
6 kgendesignerplugin - Generates widget plugins for Qt(TM) Designer.
7
9 kgendesignerplugin [OPTIONS...] file
10
12 The custom widget plugins for Qt(TM) Designer usually follow a standard
13 pattern, and the classes provided by the plugin mostly provide static
14 information, along with function to create an instance that is normally
15 just a simple constructor call. kgendesignerplugin allows developers
16 of libraries that provide new widgets to create such a plugin without
17 creating all the associated boilerplate code, by providing a simple
18 ini-style description file.
19 kgendesignerplugin chooses sensible defaults for most settings, so
21 minimal configuration is usually necessary.
22
24 -o file
25 The name for the generated C++ file. If not given, stdout will be
26 used.
27 -n plugin-name
29 Provided for compatibility. The default value for the PluginName
30 option in the input file.
31 -g group
33 Provided for compatibility. The default value for the DefaultGroup
34 option in the input file.
35 --author
37 Show author information.
38 --license
40 Show license information.
41 -h, --help
43 Show a brief help text.
44 -v , --version
46 Show version information.
47
49 The input file is an ini-style configuration file (specifically, it is
50 in the format supported by the KConfig framework) that describes a set
51 of widgets. It contains a [Global] section, providing general
52 information about the plugin, and a section for each widget that should
53 be included in the plugin.
54 The [Global] section can have the following entries:
56 DefaultGroup
58 The default value for the Group entry in the class sections
59 (default: "Custom", unless the -g option is given).
60 Includes
62 A (comma-separated) list of required includes (default: empty).
63 Note that the header files for the widgets specified later in file
64 should not be listed here; instead, this is for special headers for
65 the plugin's own use, like those for classes providing previews.
66 PluginName
68 The name of the main C++ class in the plugin (default:
69 "WidgetsPlugin", unless the -n option is given).
70 Each class should have its own [ClassName] section, which can include
72 the following entries:
73 CodeTemplate
75 The value returned by the codeTemplate() function of the plugin,
76 which is marked for "future use" by Qt(TM) Designer (default:
77 empty).
78 ConstructorArgs
80 The arguments to pass to the constructor of the class given by
81 ImplClass; these must be surrounded by parentheses (default:
82 "(parent)"). The only variable guaranteed to be available is
83 parent, which is the parent QWidget passed by Qt(TM) Designer.
84 This entry is ignored if CreateWidget is set.
86 CreateWidget
88 The code necessary to create an instance of the widget (default:
89 uses new to create an instance of the class given by the ImplClass
90 entry, passing the arguments specified by ConstructorArgs). See the
91 notes for ImplClass and ConstructorArgs.
92 DomXML
94 An XML UI description of the widget (default: the default provided
95 by the Qt(TM) Designer plugin headers).
96 Group
98 The group to display the widget under in Qt(TM) Designer (default:
99 the value of the DefaultGroup entry in the [Global] section).
100 IconName
102 The image file or standard icon name to use as the icon for this
103 widget in the Qt(TM) Designer widget list (default: a PNG file
104 named with the section name, with any double colons removed, in the
105 "pics" directory of a compiled-in resource file; for example,
106 :/pics/Foo.png in the section [Foo], or :/pics/FooBar.png in the
107 section [Foo::Bar]).
108 ImplClass
110 The class that should be used to create an instance of the widget
111 for the use of Qt(TM) Designer (default: the section name). Note
112 that this does not actually have to be the class that would be
113 created for an end application: that is determined by the DomXML.
114 This entry is ignored if CreateWidget is set.
116 IncludeFile
118 The header that needs to be included to use this widget (default:
119 the lowercase version of the section name, with any colons removed
120 and ".h" appended; for example, foo.h in the section [Foo], or
121 foobar.h in the section [Foo::Bar]).
122 IsContainer
124 Whether this widget can contain other widgets (default: false).
125 ToolTip
127 The tooltip to display when hovering over the widget in the widget
128 list of Qt(TM) Designer (default: the section name, with " Widget"
129 appended; for example, Foo Widget in the section [Foo]).
130 WhatsThis
132 The What's This text associated with the widget in Qt(TM) Designer
133 (default: the section name, with " Widget" appended; for example,
134 Foo Widget in the section [Foo]).
135
137 The simplest description file might look like:
138 [Foo]
141 ToolTip=Displays foos
142 [Bar]
143 ToolTip=Bar editor
144 Note that each class must have at least one key set (ToolTip was used
148 in this example), otherwise it will be ignored.
149 Usually, you want to change at least the user-visible text, which means
151 the ToolTip, WhatsThis and Group entries. Additionally, setting the
152 plugin name can be a good idea to prevent possible symbol clashes and
153 not confuse debuggers (both the debugger application and the person
154 doing the debugging):
155 [Global]
158 PluginName=FooWidgets
159 DefaultGroup=Display
160 [Foo]
162 ToolTip=Displays bears
163 WhatsThis=An image widget that displays dancing bears
164 [Bar]
166 ToolTip=Bar editor
167 WhatsThis=An editor interface for bars for bears
168 Group=Editing
169 More complex files may be necessary if you have namespaced classes or
173 extra options that need supplying to constructors, for example:
174 [Global]
177 PluginName=FooWidgets
178 DefaultGroup=Foo
179 [Foo::Bar]
181 ToolTip=Displays bars
182 WhatsThis=A widget that displays bars in a particular way
183 IncludeFile=foo/bar.h
184 IconName=:/previews/bar.png
185 [Foo::Baz]
187 IncludeFile=foo/baz.h
188 ConstructorArgs=(Foo::Baz::SomeOption, parent)
189 Group=Foo (Special)
190 IsContainer=true
191 IconName=:/previews/baz.png
192 Sometimes especially complex widgets might need a special "preview
196 class" implementation for use in Qt(TM) Designer; this might be a
197 subclass of the real widget that just does some extra setup, or it
198 might be a completely different implementation.
199 [Global]
202 Includes=foopreviews.h
203 [FancyWidget]
205 ImplClass=FancyWidgetPreview
206
211 https://doc.qt.io/qt-5/designer-creating-custom-widgets.html
212 The Qt(TM) Designer documentation on creating plugins for custom
213 widgets.
214
216 Please use KDE's bugtracker[1] to report bugs, do not mail the authors
217 directly.
218
220 Richard Johnson <rjohnson@kde.org>
221 Wrote the original documentation.
222 Alex Merry <alexmerry@kde.org>
224 Updated the documentation for KDE Frameworks 5.
225
227 1. KDE's bugtracker
228 https://bugs.kde.org
229KDE Frameworks Frameworks 5.0 2014-05-28 KGENDESIGNERPLUGI(1)