kgendesignerplugin(1)

1KGENDESIGNERPLUGI(1)    KDE Frameworks: KDesignerPlugi    KGENDESIGNERPLUGI(1)
2
3
4

NAME

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

SYNOPSIS

9       kgendesignerplugin [OPTIONS...] file
10

DESCRIPTION

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
20       kgendesignerplugin chooses sensible defaults for most settings, so
21       minimal configuration is usually necessary.
22

OPTIONS

24       -o file
25           The name for the generated C++ file. If not given, stdout will be
26           used.
27
28       -n plugin-name
29           Provided for compatibility. The default value for the PluginName
30           option in the input file.
31
32       -g group
33           Provided for compatibility. The default value for the DefaultGroup
34           option in the input file.
35
36       --author
37           Show author information.
38
39       --license
40           Show license information.
41
42       -h, --help
43           Show a brief help text.
44
45       -v , --version
46           Show version information.
47

FILE FORMAT

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
55       The [Global] section can have the following entries:
56
57       DefaultGroup
58           The default value for the Group entry in the class sections
59           (default: "Custom", unless the -g option is given).
60
61       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
67       PluginName
68           The name of the main C++ class in the plugin (default:
69           "WidgetsPlugin", unless the -n option is given).
70
71       Each class should have its own [ClassName] section, which can include
72       the following entries:
73
74       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
79       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
85           This entry is ignored if CreateWidget is set.
86
87       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
93       DomXML
94           An XML UI description of the widget (default: the default provided
95           by the Qt(TM) Designer plugin headers).
96
97       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
101       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
109       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
115           This entry is ignored if CreateWidget is set.
116
117       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
123       IsContainer
124           Whether this widget can contain other widgets (default: false).
125
126       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
131       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

EXAMPLES

137       The simplest description file might look like
138
139
140           [Foo]
141           ToolTip=Displays foos
142           [Bar]
143           ToolTip=Bar editor
144
145
146
147       Note that each class must have at least one key set (ToolTip was used
148       in this example), otherwise it will be ignored.
149
150       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
156
157           [Global]
158           PluginName=FooWidgets
159           DefaultGroup=Display
160
161           [Foo]
162           ToolTip=Displays bears
163           WhatsThis=An image widget that displays dancing bears
164
165           [Bar]
166           ToolTip=Bar editor
167           WhatsThis=An editor interface for bars for bears
168           Group=Editing
169
170
171
172       More complex files may be necessary if you have namespaced classes or
173       extra options that need supplying to constructors, for example:
174
175
176           [Global]
177           PluginName=FooWidgets
178           DefaultGroup=Foo
179
180           [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
186           [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
193
194
195       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
200
201           [Global]
202           Includes=foopreviews.h
203
204           [FancyWidget]
205           ImplClass=FancyWidgetPreview
206
207
208
209

BUGS

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

AUTHORS

220       Richard Johnson <rjohnson@kde.org>
221           Wrote the original documentation.
222
223       Alex Merry <alexmerry@kde.org>
224           Updated the documentation for KDE Frameworks 5.
225

NOTES

227        1. bugs.kde.org
228           http://bugs.kde.org
229
230
231
232KDE Frameworks Frameworks 5.0     2014-05-28              KGENDESIGNERPLUGI(1)