Andras Mantia

amantia@kde.org

Michal Rudolf

mrudolf@tdewebdev.org

Marek Laane

bald@smail.ee

Tõlge eesti keelde &kommander;iga saab päris lihtsalt luua uusi vidinaid ka &kommander;i-väliste vidinate põhjal. &kommander;ile saab uusi vidinaid luua kahel viisil: luues pluginaid või lisades neid otseselt &kommander;i lähtekoodi. Esimeseks sammuks on vidinaklassi loomine. Selleks tuleb tuletada oma uus &kommander;i vidina klass &Qt;/&kde; vidinast, mida soovid &kommander;iga põimida, ning seejärel ka klassist KommanderWidget. Selle klassi alistamismeetodid annavadki &kommander;i vidinale vajalikud funktsioonid. Enamik &kommander;i vidina koodist on lihtsalt mallkood. Seepärast saab enamiku &kommander;i vidina koodi genereerimiseks ära kasutada KDevelopi &kommander;i plugina malli. Selleks käivita KDevelop (soovitavalt vähemalt versioon 3.5), vali Projekt->Uus projekt, märgi ära kastike Kõigi projektimallide näitamine ja vali C++/&kommander;/KommanderPlugin mall. Anna oma pluginale nimi ja järgi nõustaja juhiseid. Sul tuleb vaid täita vidinale olulised komponendid, näiteks olekuteave, vidina tekst jms. Oletame, et soovid luua &kommander;ile uue tekstikasti, võttes selle aluseks &kde; vidina KLineEdit. &kommander;i vidina genereerimise dialoogi kasutades võtab päisefail umbes sellise kuju: #include <kommanderwidget.h> class QShowEvent; class KomLineEdit : public KLineEdit, public KommanderWidget { Q_OBJECT Q_PROPERTY(QString populationText READ populationText WRITE setPopulationText DESIGNABLE false) Q_PROPERTY(QStringList associations READ associatedText WRITE setAssociatedText DESIGNABLE false) Q_PROPERTY(bool KommanderWidget READ isKommanderWidget) public: KomLineEdit(QWidget *a_parent, const char *a_name); ~KomLineEdit(); virtual QString widgetText() const; virtual bool isKommanderWidget() const; virtual void setAssociatedText(const QStringList&); virtual QStringList associatedText() const; virtual QString currentState() const; virtual QString populationText() const; virtual void setPopulationText(const QString&); public slots: virtual void setWidgetText(const QString &); virtual void populate(); protected: void showEvent( QShowEvent *e ); signals: void widgetOpened(); void widgetTextChanged(const QString &); }; Peamiselt on tegemist mallkoodiga, mille üle ei tasu pead murda. Tähele tuleb panna vaid kaht asja: fail kommanderwidget.h peab olema kaasatud kohe alguses ning klass peab olema esmalt tuletatud vidinast, mida me soovime lõimida &kommander;iga ja teiseks KommanderWidget'ist. cpp-failis on teatud osad, mida tuleb iga konkreetse vidina puhul tähele panna. KomLineEdit::KomLineEdit(QWidget *a_parent, const char *a_name) : KLineEdit(a_parent, a_name), KommanderWidget(this) { QStringList states; states << "default"; setStates(states); setDisplayStates(states); } Konstruktoris saab määrata vidina võimalikud olekud. Meie tekstikastil ei ole mingeid olekuid, sestap anname talle ainult ühe, vaikimisi oleku default. Kui lood vidina, millel võib olla mitu olekut, näiteks märkekasti, siis saab siin määrata kolm olekut: märkimata (unchecked), poolmärgitud (semichecked) ja märgitudchecked. QString KomLineEdit::currentState() const { return QString("default"); } Eespool määrasime konstruktoris olekud ning see tagastab lihtsalt vidina aktiivse oleku. Meie vidina puhul on see alati default, aga muidu tuleb siia kirjutada kood, mis kontrollib, millises olekus vidin parasjagu on, ning tagastab vajaliku teate. QString KomLineEdit::widgetText() const { return KLineEdit::text(); } void KomLineEdit::setWidgetText(const QString &a_text) { KLineEdit::setText(a_text); emit widgetTextChanged(a_text); } Need on kaks kõige tähtsamat meetodit, mis sisaldavat põhiosa funktsionaalsest koodist. Meetod QString KomLineEdit::widgetText() const tagastab vidina teksti (teksti, milleks tekstiseoses laiendatakse eri @widgetText. Meie vidina puhul on tekst see, mida kirjutatakse tekstikasti, nii et see tagastataksegi. Vidina teksti määramisel tuleb meil määrata tekstikasti kirjutatav tekst. Me saadame pärast vidina teksti määramist signaali widgetTextChanged(), et teised vidinat teaksid, et seda vidinat on uuendatud. Vidinale funktsionaalsuse lisamiseks tuleb registreerida vastavad funktsioonid ja lisada neile vajalik kood. Registreerimiseks mõeldud kood tuleb asetada cpp-faili algusse konstruktori ette: #include <klocale.h> //for i18n #include "kommanderplugin.h" #include "specials.h" enum Functions { FirstFunction = 1159, Function1, Function2, LastFunction }; KomLineEdit::KomLineEdit(QWidget *a_parent, const char *a_name) : KLineEdit(a_parent, a_name), KommanderWidget(this) { ... //code like described above KommanderPlugin::setDefaultGroup(Group::DCOP); 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); } See registreerib kaks funktsiooni: function1 ja function2. Funktsioonile omistatav number (siin 1160 ja 1161) peab olema unikaalne, seda ei tohi kasutada üheski muus pluginas ega &kommander;is endas. Funktsioonile function1 võib anda kaks argumenti, millest üks pole kohustuslik; funktsioonil function2 ei saa anda ühtegi argumenti ja see tagastab stringi. Argument QString widget näitab, et funktsioonid tegutsevad vidinas, näiteks: KomLineEdit.function1("foo", 1). Et ka &kommander; teaks ,et vidin neid funktsioone toetab, lisa selline meetod: bool KomLineEdit::isFunctionSupported(int f) { return (f > FirstFunction && f < LastFunction) || f == DCOP::text; } See tähendab, et KomLineEdit toetab ülaltoodud funktsioone ja standardset funktsiooni text. Funktsiooni koodi saab käsitleda meetodi handleDCOP raames: QString KomLineEdit::handleDCOP(int function, const QStringList& args) { switch (function) { case function1: handleFunction1(arg[0], arg[1].toInt()); //call your function1 handler break; case function2: return handleFunction2(); //call function2 break; case DCOP::text: return text(); //call the standard KLineEdit::text() method break; default: return KommanderWidget::handleDCOP(function, args); } return QString::null; } Tegemist on juhtudega, kus vidin võib olla redaktoris ja executoris erinev, näiteks skriptiobjektide, infodialoogi vms. puhul. Tavaliselt näidatakse vidina asemel QLabel'it. Selleks peab vidin tulenema QLabel'ist, milleks konstruktoris peab seisma järgmine kood: if (KommanderWidget::inEditor) { setPixmap(KGlobal::iconLoader()->loadIcon("iconname", KIcon::NoGroup, KIcon::SizeMedium)); setFrameStyle(QFrame::Box | QFrame::Plain); setLineWidth(1); setFixedSize(pixmap()->size()); } else setHidden(true); Ka vidina enda (kui sul läheb üldse vidinat tarvis - vahest pakub sinu "vidin" kõigest võimalust kasutada andmebaasi vms.) võib luua mõnes funktsioonis, näiteks funktsioonis execute. Toome näite infodialoogi põhjal: QString AboutDialog::handleDCOP(int function, const QStringList& args) { switch (function) { ... case DCOP::execute: { if (m_aboutData) { KAboutApplication dialog(m_aboutData, this); dialog.exec(); } break; } ... } Nüüd ongi &kommander;i vidin valmis. Jääb üle vaid muuta see &kommander;ile kättesaadavaks pluginate abil. Kõiki &kommander;i vidinaid pakuvad pluginad. Standardvidinad laaditakse vidinapluginatena, kuid &kommander;i redaktor on samuti lingitud selle teegiga, sest teatud mehhanismid redaktoris on seotud spetsiaalselt standardvidinatega. &kommander;i plugin on lihtsalt ühisteek sümboliga 'kommander_plugin'. See sümbol on funktsioon, mis tagastab viida klassi KommanderPlugin isendile. &kommander; võimaldab väga lihtsalt luua vidinatele pluginat, nii et kirjeldatud süvateadmiste pärast ei tasu muret tunda. Põhiline on tuletada oma vidinate uus pluginaklass baasklassist KommanderPlugin ja teostada mõned konkreetsed üksikasjad. Mallkoodi saab genereeriga ülalmainitud KDevelopi projektimallist. Järgnev kood jätkab meie näidet, milles me lõime Kommanderi tekstikasti. #include <kommanderplugin.h> /* WIDGET INCLUDES */ #include "komlineedit.h" Kõigepealt tuleb kaasata kommanderplugin.h. See sisaldab klassi KommanderPlugin definitsiooni. Samuti tuleb kaasata kõigi vidinate päisefailid, mida antud plugin pakub - praegusel juhul on selleks ainult komlineedit.h. class MinuKomPlugin : public KommanderPlugin { public: MinuKomPlugin(); virtual QWidget *create( const QString &className, QWidget *parent = 0, const char *name = 0 ); }; Seejärel loome KommanderPlugin'i alamklassi MyKomPlugin. See sisaldab lihtsalt konstruktorit ja tühistavat loomismeetodit. MinuKomPlugin::MinuKomPlugin() { addWidget( "KomLineEdit", "My Widget Group", i18n("A Kommander line edit widget") new QIconSet(KGlobal::iconLoader()->loadIcon("ikooninimi", KIcon::NoGroup, KIcon::SizeMedium))); //add my other widgets here } Plugina konstruktoris kutsume addWidget() välja iga vidina puhul, mida plugin meie soovide kohaselt peab pakkuda. addWidget() võib kasutada kuut argumenti, aga vajalikud on ainult esimesed neli. Argumendid on järgmises järjekorras: vidina klassi nimi, grupp, kohtspikker, redaktori tööriistaribal kasutatava ikooni ikoonirühm, 'Mis see on?' teave ning tõeväärtus, mis osutab, kas vidin on teiste vidinate konteiner või mitte. Seda teavet kasutab redaktor vidinate rühmitamisel menüüs, abiinfo pakkumisel jne. Mis puutub ikooni, siis toodud näide laadib keskmise suurusega ikooni ikooninimi &kde; ikoonide standardsest asukohast. QWidget *MinuKomPlugin::create( const QString &className, QWidget *parent, const char *name ) { if( className == "KomLineEdit" ) return new KomLineEdit( parent, name ); //create my other widgets here return 0; } Just create() loob tegelikult meie vidinate isendid. Kui &kommander; soovib mõne meie plugina pakutava klassi isendit, kutsub ta välja create() soovitud klassi nimega, samuti selle eellase nime ja nimega, mida hakatakse kasutama. Kui className vastab mõnele teadaolevale vidinale, tagastatakse selle uus isend, vastasel juhul 0. Lõpuks tuleb plugin eksportida. See on meie plugina kättesaamiskoht, mille järel &kommander; oskab teda üles leida. Ilma selleta ei pea &kommander; meie teeki &kommander;i pluginaks. KOMMANDER_EXPORT_PLUGIN(MinuKomPlugin) Uue &kommander;i laiendi kompileerimiseks tuleb kompileerida kõik failid ühisteegina, linkides nad kommanderplugini, kommanderwidgeti ja kõigi vajalike KDE teekidega. Tekstikasti puhul, kus meil on komlineedit.h, komlineedit.cpp ja minukomplugin.cpp, peaks plugina kompileerimine ja paigaldamine käima umbes selliste käskudega: libtool --mode=compile g++ -$KDEDIR/include -IQTDIR/include \ -I. -fPIC -c komlineedit.cpp libtool --mode=compile g++ -$KDEDIR/include -IQTDIR/include \ -I. -fPIC -c minukomplugin.cpp libtool --mode=link g++ -shared -L$KDEDIR/lib -ltdeui -lkommanderwidget \ -lkommanderplugin komlineedit.cppkomlineedit.o minukomplugin.o -o libmykomplugin.so Kui soovid paigaldada uue plugina süsteemsena, kasuta järgmist käsku: su -c "cp libminukomplugin.so $KDEDIR/lib" Kui tarvitad KDevelopi projektigeneraatorit, ei ole ülaltoodut vaja, vaid tuleb kohandada Makefile.am-i, linkides selle täiendavate teekidega. Vaikimisi lingitakse &Qt; ja &kde; teekidega ning genereeritakse kõik vajalikud objektfailid. Anna ehitamiseks lihtsalt käsk make ja paigaldamiseks su -c make install. Kui plugin on paigaldatud, käivita programm kmdr-plugins või vali redaktoris menüükäsk Seadistused->Pluginate seadistamine. Programmi nimekirjas on parajasti &kommander;is laaditud pluginad. Lisa uus plugin, klõpsates tööriistaribal nupule Lisa ja valides oma plugina. Programmi sulgemisel salvestatakse muudatused. Kui nüüd &kommander;i redaktor uuesti käivitada, on uue plugina pakutavad vidinad kättesaadavad menüüdes ja tööriistaribadel. Nüüd saab ka uusi vidinaid kasutada &kommander;i dialoogides. See osa on mõeldud &kommander;i arendajatele ja kirjeldab, kuidas lisada uus vidin otse &kommander;ile. Mõneti irooniliselt on see omajagu keerulisem, eriti siis, kui vidin vajab täiendavaid redigeerimismeetodeid. Kõigepealt tuleb luua vidin, nagu eespool kirjeldatud. Seejärel tuleb vidin registreerida redaktoris ja executoris. Redaktoris registreerimiseks tuleb järgnev lisada faili editor/widgetdatabase.cpp: ... #include "minuvidin.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); ... } Lisada tuleb ka faili editor/widgetfactory.cpp: ... #include "minuvidin.h" ... QWidget *WidgetFactory::createWidget( const QString &className, QWidget *parent, const char *name, bool init, const QRect *r, Qt::Orientation orient ) { ... else if (className == "MyWidgetName") return new MinuVidin(parent, name); ... } Registreerimiseks executoris (sisuliselt pluginasüsteemis) tuleb järgnev lisada failile widgets/plugin.cpp: KomStdPlugin::KomStdPlugin() { ... addWidget("MyWidgetName", group, "", new QIconSet(KGlobal::iconLoader()->loadIcon("iconname", KIcon::NoGroup, KIcon::SizeMedium))); ... } See sarnaneb sellele, kuidas vidin registreeriti pluginasüsteemis esimesel juhul.