'\" t .\" Title: \fBkgendesignerplugin\fR .\" Author: Richard Johnson .\" Generator: DocBook XSL Stylesheets v1.79.1 .\" Date: 2014-05-28 .\" Manual: KDE Frameworks: KDesignerPlugin .\" Source: KDE Frameworks Frameworks 5.0 .\" Language: English .\" .TH "\FBKGENDESIGNERPLUGI" "1" "2014\-05\-28" "KDE Frameworks Frameworks 5.0" "KDE Frameworks: KDesignerPlugi" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" kgendesignerplugin \- Generates widget plugins for Qt(TM) Designer\&. .SH "SYNOPSIS" .HP \w'\fBkgendesignerplugin\fR\ 'u \fBkgendesignerplugin\fR [\fIOPTIONS\fR...] \fIfile\fR .SH "DESCRIPTION" .PP The custom widget plugins for Qt(TM) 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\&. \fBkgendesignerplugin\fR 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\&. .PP \fBkgendesignerplugin\fR chooses sensible defaults for most settings, so minimal configuration is usually necessary\&. .SH "OPTIONS" .PP \fB\-o \fR\fB\fIfile\fR\fR .RS 4 The name for the generated C++ file\&. If not given, \fIstdout\fR will be used\&. .RE .PP \fB\-n \fR\fB\fIplugin\-name\fR\fR .RS 4 Provided for compatibility\&. The default value for the PluginName option in the input file\&. .RE .PP \fB\-g \fR\fB\fIgroup\fR\fR .RS 4 Provided for compatibility\&. The default value for the DefaultGroup option in the input file\&. .RE .PP \fB\-\-author\fR .RS 4 Show author information\&. .RE .PP \fB\-\-license\fR .RS 4 Show license information\&. .RE .PP \fB\-h, \-\-help\fR .RS 4 Show a brief help text\&. .RE .PP \fB\-v , \-\-version\fR .RS 4 Show version information\&. .RE .SH "FILE FORMAT" .PP 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 [Global] section, providing general information about the plugin, and a section for each widget that should be included in the plugin\&. .PP The [Global] section can have the following entries: .PP \fIDefaultGroup\fR .RS 4 The default value for the \fIGroup\fR entry in the class sections (default: "Custom", unless the \fB\-g\fR option is given)\&. .RE .PP \fIIncludes\fR .RS 4 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\*(Aqs own use, like those for classes providing previews\&. .RE .PP \fIPluginName\fR .RS 4 The name of the main C++ class in the plugin (default: "WidgetsPlugin", unless the \fB\-n\fR option is given)\&. .RE .PP Each class should have its own [\fIClassName\fR] section, which can include the following entries: .PP \fICodeTemplate\fR .RS 4 The value returned by the codeTemplate() function of the plugin, which is marked for "future use" by Qt(TM) Designer (default: empty)\&. .RE .PP \fIConstructorArgs\fR .RS 4 The arguments to pass to the constructor of the class given by ImplClass; these must be surrounded by parentheses (default: "(parent)")\&. The only variable guaranteed to be available is \fIparent\fR, which is the parent QWidget passed by Qt(TM) Designer\&. .sp This entry is ignored if CreateWidget is set\&. .RE .PP \fICreateWidget\fR .RS 4 The code necessary to create an instance of the widget (default: uses new to create an instance of the class given by the ImplClass entry, passing the arguments specified by ConstructorArgs)\&. See the notes for ImplClass and ConstructorArgs\&. .RE .PP \fIDomXML\fR .RS 4 An XML UI description of the widget (default: the default provided by the Qt(TM) Designer plugin headers)\&. .RE .PP \fIGroup\fR .RS 4 The group to display the widget under in Qt(TM) Designer (default: the value of the \fIDefaultGroup\fR entry in the [Global] section)\&. .RE .PP \fIIconName\fR .RS 4 The image file or standard icon name to use as the icon for this widget in the Qt(TM) 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, :/pics/Foo\&.png in the section [Foo], or :/pics/FooBar\&.png in the section [Foo::Bar])\&. .RE .PP \fIImplClass\fR .RS 4 The class that should be used to create an instance of the widget for the use of Qt(TM) 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 DomXML\&. .sp This entry is ignored if CreateWidget is set\&. .RE .PP \fIIncludeFile\fR .RS 4 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, foo\&.h in the section [Foo], or foobar\&.h in the section [Foo::Bar])\&. .RE .PP \fIIsContainer\fR .RS 4 Whether this widget can contain other widgets (default: false)\&. .RE .PP \fIToolTip\fR .RS 4 The tooltip to display when hovering over the widget in the widget list of Qt(TM) Designer (default: the section name, with " Widget" appended; for example, Foo Widget in the section [Foo])\&. .RE .PP \fIWhatsThis\fR .RS 4 The What\*(Aqs This text associated with the widget in Qt(TM) Designer (default: the section name, with " Widget" appended; for example, Foo Widget in the section [Foo])\&. .RE .SH "EXAMPLES" .PP The simplest description file might look like .sp .if n \{\ .RS 4 .\} .nf [Foo] ToolTip=Displays foos [Bar] ToolTip=Bar editor .fi .if n \{\ .RE .\} .sp Note that each class must have at least one key set (ToolTip was used in this example), otherwise it will be ignored\&. .PP Usually, you want to change at least the user\-visible text, which means the ToolTip, WhatsThis and Group 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): .sp .if n \{\ .RS 4 .\} .nf [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 .fi .if n \{\ .RE .\} .PP More complex files may be necessary if you have namespaced classes or extra options that need supplying to constructors, for example: .sp .if n \{\ .RS 4 .\} .nf [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 .fi .if n \{\ .RE .\} .PP Sometimes especially complex widgets might need a special "preview class" implementation for use in Qt(TM) Designer; this might be a subclass of the real widget that just does some extra setup, or it might be a completely different implementation\&. .sp .if n \{\ .RS 4 .\} .nf [Global] Includes=foopreviews\&.h [FancyWidget] ImplClass=FancyWidgetPreview .fi .if n \{\ .RE .\} .sp .SH "SEE ALSO" .PP http://qt\-project\&.org/doc/qt\-5/designer\-creating\-custom\-widgets\&.html .RS 4 The Qt(TM) Designer documentation on creating plugins for custom widgets\&. .RE .SH "BUGS" .PP Please use \m[blue]\fBbugs\&.kde\&.org\fR\m[]\&\s-2\u[1]\d\s+2 to report bugs, do not mail the authors directly\&. .SH "AUTHORS" .PP \fBRichard Johnson\fR <\&rjohnson@kde\&.org\&> .RS 4 Wrote the original documentation\&. .RE .PP \fBAlex Merry\fR <\&alexmerry@kde\&.org\&> .RS 4 Updated the documentation for KDE Frameworks 5\&. .RE .SH "NOTES" .IP " 1." 4 bugs.kde.org .RS 4 \%http://bugs.kde.org .RE