<para>These are the two most important methods, where the bulk of the
functional code goes.
<emphasis>QString KomLineEdit::widgetText() const</emphasis> method returns the widget text of the
widget (the text that the <emphasis>@widgetText</emphasis> special is expanded to in text
associations). For our widget, the widget text is simply the text inside
the line edit, so we just return that. Similarly when setting the widget text,
we just set the text inside the line edit. We emit the <emphasis>widgetTextChanged()</emphasis>
signal after setting the widget text so other widgets can recognize the fact
that this widget was updated.
</para>
<para>
In order to add functionality to the widget, you need to register some function and add code to handle them. Here is the code to be used to register, put it in the beginning of the cpp file, above the constructor:
KommanderPlugin::registerFunction(Function1, "function1(QString widget, QString arg1, int arg2)", i18n("Call function1 with two arguments, second is optional."), 2, 3);
KommanderPlugin::registerFunction(function2, "function2(QString widget)", i18n("Get a QString as a result of function2."), 1);
}
</screen>
<para>This registers two functions: <emphasis>function1 and function2</emphasis>. The number assigned to the functions (here <emphasis>1160</emphasis> and <emphasis>1161</emphasis>) must be unique, not used in any other plugin or
inside &kommander;. <emphasis>function1</emphasis> takes two arguments, one is optional, <emphasis>function2</emphasis> takes no argument and returns a string. The <emphasis>QString widget</emphasis> argument in the signatures notes that this functions work on a widget, like: <emphasis>KomLineEdit.function1("foo", 1)</emphasis>.
</para>
<para>To teach &kommander; that the widget supports these functions, add a method like this:
</para>
<screen>
bool KomLineEdit::isFunctionSupported(int f)
{
return (f > FirstFunction && f < LastFunction) || f == DCOP::text;
}
</screen>
<para>This means that KomLineEdit supports the above functions and the standard <emphasis>text</emphasis>
function.
The function code should be handled inside the handleDCOP method:
<para>There are cases when the widget should appear differently in the editor than in
the executor, like the case of ScriptObjects, about dialog, etc. The usual solution is to show a QLabel instead of the widget. For this, your widget must
derive from QLabel, and use this in the constructor:
We then create a KommanderPlugin sub-class called <emphasis>MyKomPlugin</emphasis>.
This class simply has a constructor and an overridden create method.
</para>
<screen>
MyKomPlugin::MyKomPlugin()
{
addWidget( "KomLineEdit", "My Widget Group", i18n("A Kommander line edit widget") new QIconSet(KGlobal::iconLoader()->loadIcon("iconname", KIcon::NoGroup, KIcon::SizeMedium)));
//add my other widgets here
}
</screen>
<para>In the constructor of the plugin, we call <emphasis>addWidget()</emphasis> for each widget we wish
to provide in this plugin. <emphasis>addWidget()</emphasis> takes 6 arguments but only the first 4
are required. In order, the arguments are the widget's class name, group,
tool tip, an iconset for the icon used in the editor toolbar, what's this information, and a bool indicating whether the widget
is a container for other widgets or not. This information is used
by the editor when grouping your widget in menus, providing help information
etc.
</para>
<para>
Regarding the icon, the above example loads a medium sized icon called <emphasis>iconname</emphasis> from the standard &kde; icon location.
<note><para>If you use the KDevelop project generator, you will not need to do the above, but instead adapt the Makefile.am to link against extra libraries. By default, it will link to &Qt; and &kde; libraries and generate all the needed object files. Just run <command>make</command> to build, and <command>su -c make install</command> to install.</para></note>
</sect2>
<sect2 id="config-plugin">
<title>Configure the installed plugins</title>
<para>
Now that the plugin is installed, run the <command>kmdr-plugins</command> program or choose <guimenu>Settings->Configure Plugins</guimenu> from the Editor. The list in this program displays the
plugins that are currently loaded by &kommander;. Add the new plugin to the
list by clicking the <guilabel>Add</guilabel> button in the toolbar and choosing your plugin.
Closing the program saves changes.
</para>
<para>
If you now restart the &kommander; editor, the widgets your new plugin
provides should be available in the menus and toolbars. You can
now use your new widgets in &kommander; dialogs.
</para>
</sect2>
<sect2 id="add-widget">
<title>Add the widget directly to &kommander;</title>
<para>This section is for &kommander; developers and describes how to add a new widget directly to &kommander;.</para>
<para>
Ironically, this one is more complicated, especially if the widget needs
extra editing methods.
First you create the widget like above. After that you need to register the
widget to the editor and the executor.
To register it inside the editor, add it to <emphasis>editor/widgetdatabase.cpp</emphasis>:
</para>
<screen>
...
#include "mywidget.h"
...
void WidgetDatabase::setupDataBase( int id )
{
...
r = new WidgetDatabaseRecord;
r->name = "MyWidgetName";
r->iconName = "icon.png";
r->group = widgetGroup( "Kommander" );
r->toolTip = i18n("My new widget");
append(r);
...
}
</screen>
<para>
You need to add to the <emphasis>editor/widgetfactory.cpp</emphasis> as well:
