Jak se dělá Plasmoid – 4 (Runnery)

29. 1. 2010 | Dan Vrátil | Programování | 3010×

Runner je knihovna, kterou využívá KRunner (dialog (nejen) pro spouštění programů). Když píšete název nějaké aplikace, KRunner postupně volá hlavní funkce všech dostupných runnerů a předává jim zadaný řetězec.

Co je to Runner

Plasmoidy, to nejsou jen applety na plochu, ale zahrnují i tzv. runnery. Runner je knihovna, kterou využívá KRunner. Když píšete název nějaké aplikace, KRunner postupně volá hlavní funkce všech dostupných runnerů a předává jim zadaný řetězec (tzv. Context). Každý runner vrací seznam relativních položek (Plasma::QueryMatch). Při kliknutí na vybraný QueryMatch KRunner zavolá funkci run příslušného Runneru, který zařídí, aby se vykonala příslušná událost.

Jako příklad pro dnešní článek použijeme jeden můj starší runner, který umožňuje prohledávat kontakty z Kopete. Kliknutím na kontakt se rovnou otevře chatovací okno Kopete. Celá komunikace probíha přes rozhraní DBus. Podobný, ale ještě o něco propracovanější runner najdete v KDE SC 4.4.

Trocha teorie

Runner je třída odvozená od Plasma::AbstractRunner a musí implementovat tři metody:

• Konstruktor, ve kterém se nastavují výchozí vlastnosti Runneru.

• match(Plasma::RunnerContext &context), která se volá vždy, když se změní text v KRunneru. Ten získáme pomocí metody Plasma::RunnerContext.query(). Plasma::RunnerContext má ještě jednu další šikovnou vlastnost, kterou zjistíme pomocí metody isValid(). Ta vrací true, pokud je RunnerContext stále platný, a false, pokud se RunnerContext mezitím změnil (např. uživatel napsal další znak) – v takovém případě runner zpravidla skončí, protože už běží jeho nová instance s novým kontextem a ten stavající je zneplatněn (jeho výstup nebude zobrazen).

• Třetí metodou, kterou musí runnery implementovat, je run(Plasma::RunnerContext &context, Plasma::QueryMatch &match), která se volá, když uživatel klikne na položku v seznamu výsledků. Jako parametr přijímá ukazatel na příslušný QueryMatch. V QueryMatch lze, kromě zobrazovaných hodnot, uložit ještě hodnotu skrytou, která obsahuje například URL, která se má otevřít a podobně. Context obsahuje aktuální kontext, pro který je daný QueryMatch platný.

Kód

A teď od teorie k praxi.

kopetecontacts.h

#ifndef KOPETECONTACTS_H
#define KOPETECONTACTS_H

#include <Plasma/AbstractRunner>

#include <KIcon>

class KopeteContactsRunner : public Plasma::AbstractRunner
{
    Q_OBJECT

    public:
        KopeteContactsRunner(QObject *parent, const QVariantList& args );
        ~KopeteContactsRunner() { }

        void match(Plasma::RunnerContext &context);
        void run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match);

    private:
        KIcon m_icon;
};

// Makro pro registraci runneru
K_EXPORT_PLASMA_RUNNER(kopetecontacts, KopeteContactsRunner)

#endif // KOPETECONTACTS_H


#endif

Důležité je nezapomenout na makro pro registraci runneru do KDE. První parametr je název pluginu, pod kterým ho systém bude znát. Musí odpovídat hodnotě X-KDE-PluginInfo-Name v souboru .desktop. Druhým parametrem je název třídy runneru.

kopetecontacts.cpp

#include "kopetecontactsrunner.h"

// Vloží podporu QtDbus
#include <QtDBus/QDBusInterface>
#include <QtDBus/QDBusReply>

#include <KIcon>

KopeteContactsRunner::KopeteContactsRunner(QObject *parent, const QVariantList& args)
    : Plasma::AbstractRunner(parent, args)
{
    // Umlčí překladač
    Q_UNUSED(args);
    // Název runneru
    setObjectName("KopeteContacts");

    // Použije ikonku Kopete
    m_icon = KIcon("kopete");
    // Bude ignorovat všechny generické typy kontextu
    setIgnoredTypes(Plasma::RunnerContext::Directory | 
		    Plasma::RunnerContext::File |
                    Plasma::RunnerContext::NetworkLocation |
		    Plasma::RunnerContext::Executable |
		    Plasma::RunnerContext::ShellCommand);
    // Přiklad syntaxe
    addSyntax(Plasma::RunnerSyntax(":q:", "Zahaji chat s :q:")); 
    // DBus protocol je pomalý…
    setSpeed(AbstractRunner::SlowSpeed);
}

void KopeteContactsRunner::match(Plasma::RunnerContext &context)
{
     // Vyhledávání nebude case-sensitive
    QString searchedName = context.query().toLower();
    
    // Nebude se vyhledávat pro kontexty kratší než 3 znaky
    if (searchedName.length() < 3) {
	    return;
    }
	
    // Pokusí se navázat DBus spojení s Kopete
    QDBusInterface kopeteDBusTest("org.kde.kopete", "/Kopete", "org.freedesktop.DBus.Introspectable");
    QDBusReply<QString>kopeteReply = kopeteDBusTest.call("Introspect"); 
    if (!kopeteReply.isValid()) {
            return;
    }

    // Vytvoří seznam výsledků
    QList<Plasma::QueryMatch> matches;

    // Načte seznam všech kontaktu
    QDBusInterface kopeteDBus("org.kde.kopete","/Kopete","org.kde.Kopete");
    QDBusReply<QStringList> kopeteContacts = kopeteDBus.call("contacts");

    QString contactName;

    // Projde všechny kontakty
    for (int i = 0; i < kopeteContacts.value().size(); i++) {
	// Nemá smysl pokračovat, pokud aktuální kontext už neni platný
	if (!context.isValid()) {
		return;
	}
	// Načte informace o kontaktu
        QDBusReply<QVariantMap>contactData = kopeteDBus.call("contactProperties",kopeteContacts.value().at(i));
	// Uloží jméno kontaktu
	contactName = contactData.value().value("display_name").toString();
	// Zjistí, jestli kontext odpovídá kontaktu
	bool matched = contactName.contains(searchedName, Qt::CaseInsensitive);

	// Pokud ano, tak přidáme výsledek do QueryMatch
	if (matched) {
		// Vytvoří nový QueryMatch
		Plasma::QueryMatch matchItem(this);
		// Nastaví mu ikonu
		matchItem.setIcon(m_icon);
		// Jako hlavní název QueryMatch nastaví název kontaktu
		matchItem.setText(contactName);
		// Načte status kontaktu
		QString statusMessage = contactData.value().value("status_message").toString();
		if (not statusMessage.isEmpty()) {
		    statusMessage.prepend(": ");
		}
		// Jako popis QueryMatch nastaví název a popis statusu
		matchItem.setSubtext(contactData.value().value("status").toString().append(statusMessage));
		// Jako data (skrytá, nezobrazují se) nastaví UID
		matchItem.setData(kopeteContacts.value().at(i));
	
		// Pokud kontakt přesně odpovídá kontextu, nastavíme ExactMatch
		if (contactName == searchedName) {
		    matchItem.setType(Plasma::QueryMatch::ExactMatch);
		} else {
		    matchItem.setType(Plasma::QueryMatch::PossibleMatch);
		}
		// Přidá tento QueryMatch do seznamu
		matches.append(matchItem);
	}
    }

    // Uloží do kontextu seznam QueryMatchů
    context.addMatches(searchedName,matches);
}

void KopeteContactsRunner::run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match)
{
    // Umlčí překladač
    Q_UNUSED(context);
    
    QString uid = match.data().toString();
    
    //  Pokusí se navázat DBus spojení s Kopete
    QDBusInterface kopeteDBusTest("org.kde.kopete", "/Kopete", "org.freedesktop.DBus.Introspectable");
    QDBusReply<QString>kopeteReply = kopeteDBusTest.call("Introspect");
    if (!kopeteReply.isValid()) {
          return;
    }
    QDBusInterface kopeteDBus("org.kde.kopete","/Kopete","org.kde.Kopete");
    
    kopeteDBus.call("openChat",uid);

}

#include "kopetecontactsrunner.moc"

V konstruktoru se podíváme podrobněji na metody setSpeed a addSyntax. Metoda setSpeed nastavuje rychlost Plasmoidů. Výchozí hodnota je rychlá, ale pokud runner pužívá internetové připojení nebo DBus, měla by se rychlost nastavit na AbstractRunner::Slow – KRunner pak počítá s tím, že na takový runner musí čekat o něco déle. Metoda addSyntax přijímá objekt Plasma::RunnerSyntax. Plasma::RunnerSyntax v konstruktoru přijímá dva parametry – syntaxi vstupu, kde :q: je symbol pro vyhledávaný výraz a popis vstupu. Pokud například chcete, aby vstup vypadal „kontakt jméno_kontaktu“, vložili byste do addSyntax objekt Plasma::RunnerSyntax("kontakt :q:","Vyhledá kontakt :q:")).

V metodě match je na konci volána metoda context.addMatches, která jako parametr přijímá seznam všech nalezených položek, které se mají zobrazit.

Stejně jako applet, i runner musí mít svůj soubor .desktop, podle kterého ho KDE může najít.

plasma-runner-idossearchrunner.desktop

[Desktop Entry]
Name=Kopete Contacts
Comment=Start chat with your Kopete contacts

ServiceTypes=Plasma/Runner
Type=Service
Icon=kopete
X-KDE-Library=krunner_kopetecontacts
X-KDE-PluginInfo-Author=Dan Vratil
X-KDE-PluginInfo-Email=vratil@progdansoft.com
X-KDE-PluginInfo-Name=kopetecontacts
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true

Důležité je, aby X-KDE-PluginInfo-Name odpovídalo hodnotě v makru v hlavičkovém souboru.

CMakeLists.txt

# Název projektu
project(kopetecontactsrunner)

set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake ${CMAKE_MODULE_PATH})

# Najde požadované komponenty
find_package(KDE4 REQUIRED)
find_package(Qt4 REQUIRED)
find_package(KDE4Workspace REQUIRED)
find_package(Kopete REQUIRED)
include (KDE4Defaults)

# Nastaví definice
add_definitions (${QT_DEFINITIONS} ${KDE4_DEFINITIONS})

# Nastaví adresáře s hlavičkovými soubory
include_directories (${KDE4_INCLUDES}
                     ${KDE4WORKSPACE_INCLUDE_DIR}
                     ${QT_INCLUDE_DIR}
                     ${QT_QTDBUS_INCLUDE_DIR}
                     ${CMAKE_CURRENT_SOURCE_DIR}/libs)
set(krunner_kopetecontacts_SRCS
    kopetecontactsrunner.cpp
)

# Přidá plugin do KDE
kde4_add_plugin(krunner_kopetecontacts ${krunner_kopetecontacts_SRCS})

# Slinkuje knihovnu
target_link_libraries(krunner_kopetecontacts ${KDE4_PLASMA_LIBS})

# Nainstaluje soubory
install(TARGETS krunner_kopetecontacts DESTINATION ${PLUGIN_INSTALL_DIR} )
install(FILES plasma-runner-kopetecontacts.desktop DESTINATION ${SERVICES_INSTALL_DIR})

Nyní je potřeba restartovat KRunner:

kquitap krunner
kstart krunner

Nyní můžete runner otestovat – když začnete psát název některého ze svých kontaktů v Kopete, budou se relevantní kontakty zobrazovat v KRunneru.

Závěrem

Možností, jak rozšířit KRunner, je mnoho. Runnery mohou, stejně jako applety, také používat DataEnginy a mít dialog pro konfiguraci. Jedinou nevýhodou je, že není možná interakce s uživatelem (kromě úvodního vstupu). Nakonec ještě přikládám tarball se zdrojovými kódy.

       

Komentáře

[Marián Kyral]

Díky, jsem netušil, že je to až tak primitivní

Hodilo by se udělat něco podobného pro psi, jenže tam by se nejdříve musely doimplementovat potřebné DBUS metody.

$qdbus org.psi-im.Psi /Main
method void org.psi_im.Psi.Main.openURI(QString uri)
method void org.psi_im.Psi.Main.raise()
method void org.psi_im.Psi.Main.setStatus(QString status, QString message)
method void org.psi_im.Psi.Main.sleep()
method void org.psi_im.Psi.Main.wake()
method QDBusVariant org.freedesktop.DBus.Properties.Get(QString interface_name, QString property_name)
method QVariantMap org.freedesktop.DBus.Properties.GetAll(QString interface_name)
method void org.freedesktop.DBus.Properties.Set(QString interface_name, QString property_name, QDBusVariant value)
method QString org.freedesktop.DBus.Introspectable.Introspect()

[progdan]

Resil jsem jak podporu PSI tak i podporu Pidginu, u obou jsem ale narazil na spatne nebo nedostatecne DBus rozhrani

[Honz]

Nedokázal by někdo udělat návod, jak si naprogramovat plasmoid pro sensory? Totiž hlavně tak, aby ukazoval čísla a ne nějaké pitomé otáčkoměry a stupnice? Byl bych neskonale šťastný, kdyby to nědko dokázal...

[psi]

Něco takového? http://www.ibm.com/developerworks/linux/library/l-kde-plasmoids/index.html

[Heevy]

Nejsem si úplně jistý, jestli tohle byl zrovna idealní příklad. Kvůli němu jsem totiž přestal KRunnner používat... Z mého pohledu je základní problém pluginu a potažmo i KRunneru v tom, že data tahá pokaždé on demand. Což v mém případě stovek kontaktů vyústilo v několik stovek dbus zpráv pro každé písmeno. Vlastně použití kopete pluginu znamenalo, že se to tak každé 3 hledání žačne tak "censored", že jediná možnost byla ten KRunner killnout. Někdo by mohl namítnout, že by nebylo složité do toho pluginu dopsat cache...ano nebylo. Ale pokud jedna plugina umožní bez problémů zablokovat celou aplikaci(a konkrétně v mém případě vyústit v nepoužívání celé aplikace), tak potom je asi na úrovni návrhu něco špatně. :( Bohužel. KDE mám sice rád (i když rychlost KDE4 je někdy naprosto tragická), ale třeba takové Gnome DO má architekturu výrazně lepší, protože cachování samo o sobě už vyžaduje. Resp. neuděláte to tak jak pro KRunner. Tam je pro změnu zase problém umět vyvolat invalaci cache. :( Nicméně pořád se jedná o čitější přístup než v případě KRunneru. Takže z mého pohledu buď by doplňky měly cachovat nebo by se mělo jednat o takovou kardinalitu dat, že tento přístup nebude problém.

PS: Jinak díky za ten, doplněk, protože jsem si z něj vzal inspiraci pro Gnome DO plugin, který v KDE spokojeně používám.

[progdan]

Zalezi samozrejme na mnozstvi kontaktu. Kdyz jsem ted koukal na DBus rozhrani Kopete tak sem zjistil, ze by to vsechno slo zajistit jedinou zpravou hned na zacatku (bez nutnosti zjistovat detaily pro kazdy kontakt zvlast novou zpravou)...inu, vzdy je prostor pro zlepseni

Co se rychlost tyce, ja sem si treba musel v KDE 4.4 vypnout Nepomuk Desktop Search runner protoze KRunner zabijelo cekani na odpoved z Virtuosa...kazdopadne mam moznost srovnat (sic jen subjektivne, ale preci) rychlost KRunneru v KDE 4.3 a v 4.4 a ten vyvoj je tam znatelny. Za hodne muze i optimalizace, kterou si prosla vetsina Runneru. Ale ne vzdy to plati (viz Virtuoso).

Nejakou cache bych samozrejme uvital, otazkou je jak zajistovat jeji aktualizaci, zejmena u veci, ktere se casto meni (statusy kontaktu napriklad).

[jiřík]

Já tedy programování na úrovni C++ nerozumím, ale to by byl problém si řekněme každých 5 minut šáhnout do Kopete pro statusy a dát je do cache? Něco jako automatický update dat v eshopu v PHP ...

[thingie]

No, to by bylo dost nerozumné. To jedno dbusové volání je docela levné, a ty statusy po pěti minutách by nemusely mít valnou hodnotu a hlavně vztah k aktuální realitě…

[jiřík]

Problém je v tom, že real-time hledání je náročné, jak jsem tak pochopil. A nemusí to být 5 minut, jestliže jeden dotaz na stažení všech dat do cache je fakt drobnost, tak to může být po minutě.

[thingie]

Je náročné, protože je blbě udělané, jak se z toho popisu zdá. Cachovat něco, co máte snadno a ve vhodném formátu dostupné přes laciné IPC o jeden proces dál, to je cesta leda do pekel. A když se bavíme zrovna o Kopete, to je software kde bych fakt neměl nejmenší výčitky ukázat prstem, že vaše dbusové API saje, a to nemálo.

[jiřík]

No hádat se nebudu, tam kde tomu pramálo rozumím :) Asi máte pravdu.

[thingie]

Ona by se tam asi spousta věcí zase určitě cachovat mohla. Ale tohle zrovna…

Druhá věc je, že KRunner to podle mě přehání, a měl by tyhle věci zobrazovat poněkud konzervativněji. Napíšu tři písmena, jakákoliv, a ono to šrotí a po třech sekundách nabídne hory nesmyslů, které se vyznačují tím, že mě vůbec nezajímají. Bylo by možná lepší, kdyby se to snažilo počkat do chvíle, kdy může aspoň odhadnout co třeba chci (no, to je jasný nesmysl, ale prostě… pokud najde tisíc potenciálně relevantních výsledků, mělo by to poznat, že nemá cenu nějaké nabízet).