Jak se dělá Plasmoid – 3 (DataEngine)

11. 1. 2010 | Dan Vrátil | Programování | 3281×

Dnes si představíme další prostředek pro tvorbu Plasmoidů: DataEngine – a ukážeme si nejen jak vytvořit vlastní DataEngine, ale i jak ho použít v Plasmoidech.

DataEngine

DataEngine je samostatná knihovna, která poskytuje data appletům. Applet ale nekomunikuje přímo s DataEnginem, ale připojuje se k jeho zdrojům. DataEngine může buď obsahovat přednastavené zdroje (například pro časová pásma), nebo je může vytvářet dynamicky na základě požadavku (například pro RSS kanál). U každého zdroje se dá nastavit, jak často se má aktualizovat. Zdroj pak bude v pravidelných intervalech posílat aktualizovaná data Plasmoidu. V našem příkladě budeme jako název zdroje uvádět URL stránky, která se má stáhnout a naparsovat. Plasma s sebou v základní instalaci nese několik připravených DataEnginů, například pro přístup ke zdrojům Akonadi, ke kalendáři, času, k souborům a mnoho dalších. Jeden applet může používat zároveň více DataEnginů i zdrojů a jeden DataEngine či zdroj může být současně využíván více applety.

Třída odvozená od Plasma::DataEngine musí implementovat dvě metody: sourceRequestEvent a updateSourceEvent. První z uvedených je zavolána vždy, když někdo požádá DataEngine o připojení ke zdroji. Druhá, když dojde k automatické aktualizaci zdroje.

Data se ve zdroji nastavují metodou setData. Ta přijímá tři parametry – název zdroje (QString) a pár klíč (QString) – data (QVariant). Místo páru klíč – data lze použít objekt Plasma::Data, který je definován jako QHash<QString,QVariant>. V appletu jsou pak data dostupná také v objektu Plasma::Data.

Důležité je také zmínit, že při připojování zdroje v appletu se musí nastavit objekt, který bude data přijímat. Může to být ten samý objekt, ve kterém se připojujeme, ale není to podmínkou. Applet, který má data přijímat, pak musí implementovat slot void dataUpdated(QString,Plasma::DataEngine::Data). Při změně dat ve zdroji zavolá DataEngine tuto funkci a applet má tak k dispozici nová data.

Přestože v našem případě toho nevyužijeme, určitě se také hodí znát metodu setMinimumPollingInterval, jež jako parametr přijímá nejkratší možný interval (v milisekundách), ve kterém se smí zdroj aktualizovat. Cílem je zabránit tomu, aby se některé applety pokoušely například obnovovat RSS zdroje každých 5 sekund (což by samozřejmě mělo negativní důsledek na výkon PC a vytížení internetového připojení). Pokud zadáte číslo menší než 0, budou automatické aktualizace zakázané.

Kód

idossearch.h

#ifndef IDOSENGINE_HEADER
#define IDOSENGINE_HEADER

#include <Plasma/DataEngine>

// Budeme potřebovat přístup k síťařině v Qt
#include <QtNetwork/QNetworkAccessManager>
#include <QtNetwork/QNetworkReply>

class IDOSEngine: public Plasma::DataEngine
{
    Q_OBJECT
    public:
	// Obligátní konstruktor a destruktor
        IDOSEngine(QObject *parent, const QVariantList &args);
        ~IDOSEngine() { }

    protected:
	// Tato metoda je volána, když je přijat požadavek na připojení zdroje.
	bool sourceRequestEvent(const QString &name);
	// Tato metoda je volána při automatické aktualizaci dat enginem.
	// V našem případě jsme automatické aktualizace vypnuli,
	// ale pro ukázku zde metodu uvádím
	bool updateSourceEvent(const QString &name);
	
    private:
	// Použijeme pro stažení dat z internetu
	QNetworkAccessManager *m_network_manager;
	
    private slots:
	// Slot, který se zavolá, když QNetworkAcessManager stáhne požadovanou stránku
	void onDataLoaded(QNetworkReply *reply);
	
};
 
#endif

Jak jsem zmínil výše, Plasma::DataEngine musí implementovat sourceRequestEvent a updateSourceEvent. Obě metody přijímají název zdroje, kterého se operace týká.

searchwidget.h

#include "idosengine.h"

#include <QNetworkRequest>

// Makro pro registraci enginu do KDE. První parametr je
// název enginu, druhý je název třídy enginu
K_EXPORT_PLASMA_DATAENGINE(idos, IDOSEngine)

IDOSEngine::IDOSEngine(QObject* parent, const QVariantList& args)
    : Plasma::DataEngine(parent, args)
{
    Q_UNUSED(args)
    
    // NIKDY automaticky neaktualizovat.
    setMinimumPollingInterval(-1);
    
    // Vytvoří QNetworkAccessManager pro získání dat ze stránek IDOSu
    m_network_manager = new QNetworkAccessManager(this);
    // Při dokončení požadavku se zavolá funkce onDataLoaded
    connect(m_network_manager,SIGNAL(finished(QNetworkReply*)),this,SLOT(onDataLoaded(QNetworkReply*)));
}
 

bool IDOSEngine::sourceRequestEvent(const QString &name)
{
    // Vytvoříme „prázdný“ engine
    setData(name,DataEngine::Data());

    // Nepotřebujeme rozlišovat mezi tím, jestli jsme
    // o data požádali ručně, nebo šlo o automatický požadavek
    // (i když k tomu by dojít nemělo, protože jsme to
    // zakázali v konstruktoru), v obou případech chceme stejná data
    return updateSourceEvent(name);
}
 
bool IDOSEngine::updateSourceEvent(const QString &name)
{
    // Stáhne wapovou stránku. Po dokončení je vyvolán signál finished()
    m_network_manager->get(QNetworkRequest(name));
    
    // Při asynchronním přístupu nemůžeme správně ověřit,
    // jestli byla data úspěšně stažena, nebo ne,
    // a proto musíme předpokládat, že se vše povedlo
    return true;
}

void IDOSEngine::onDataLoaded(QNetworkReply *reply)
{
   // Zpracování dat
   QString data = QString::fromUtf8(reply->readAll());
   
   // Odstraní celou hlavicku
   data.remove(QRegExp("^.+<p align=\"center\">"));
   data.remove(QRegExp("<img.+</wml>"));
   data.remove("</p>");
   data.remove(QRegExp("^<br />"));
   
   // Rozdělí data na 2 části – seznam stanic a odkazy
   QStringList sl = data.split("<p>");
   // Rozdělí stanice do QStringList (každá stanice + čas
   // odjezdu/příjezdu) je oddělena značkou <br />)
   QStringList stations = sl.at(1).split("<br />");

   // Získá odkazy na následující a předchozí spojení
   QRegExp urlRx("<a\\s+[^>]*href\\s*=\\s*\"([^\"]*)\"[^<]*>([^<]*)</a>*");
   int pos = urlRx.indexIn(sl.at(2));
   QString nextUrl = QString("http://ttwap.chaps.cz/").append(urlRx.capturedTexts().at(1)).replace("&amp;","&");
   urlRx.indexIn(sl.at(2),pos+urlRx.matchedLength());
   QString prevUrl = QString("http://ttwap.chaps.cz/").append(urlRx.capturedTexts().at(1)).replace("&amp;","&");

   // Nastaví data, která se vratí appletu. Jako identifikátor
   // zdroje používáme URL adresu stránky
   setData(reply->url().toString(),QString("stations"),stations);
   setData(reply->url().toString(),QString("previousUrl"),prevUrl);
   setData(reply->url().toString(),QString("nextUrl"),nextUrl);
  
}

#include "idosengine.moc"

Naparsováním stránek tedy získáme URL předchozího a následujícího spoje a seznam stanic včetně času příjezdu/odjezdu. Pokud bychom chtěli, aby byl náš engine univerzálnější, bylo by určitě vhodné ještě oddělit čas příjezdu a odjezdu od názvu stanice, délku trasy, cenu lístků a další informace, ale pro účely tohoto příkladu to stačí.

plasma-engine-idos.desktop

[Desktop Entry]
Name=IDOS Engine
Comment=Engine to retrieve data from IDOS
Type=Service
 
X-KDE-ServiceTypes=Plasma/DataEngine
X-KDE-Library=plasma_engine_idos
X-Plasma-EngineName=idos
X-KDE-PluginInfo-Author=Dan Vratil
X-KDE-PluginInfo-Email=vratil@progdansoft.com
X-KDE-PluginInfo-Name=idos
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-Website=http://www.abclinuxu.cz
X-KDE-PluginInfo-Category=Online Services
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true

X-KDE-Library je název knihovny s naším DataEnginem. X-Plasma-EngineName je název enginu, který jsme uvedli v makru v souboru idosengine.cpp. Plasma si před název sama přidá plasma_engine_, čemuž by měl být přizpůsoben náš název enginu.

CMakeLists.txt

project(plasma-idosengine)

find_package(KDE4 REQUIRED)
# Kvůli použití QtNetwork modulu budeme potřebovat u knihovny Qt
find_package(Qt4 REQUIRED)

include(KDE4Defaults)
include(${QT_USE_FILE})
 
add_definitions (${QT_DEFINITIONS} ${KDE4_DEFINITIONS})

include_directories(
   ${CMAKE_SOURCE_DIR}
   ${CMAKE_BINARY_DIR}
   ${KDE4_INCLUDES}
   ${QT_INCLUDE_DIR}
   ${QT_QTNETWORK_INDLUDE_DIR} )
 
# Povolí použití modulu QtNetwork (engine používá
# QNetworkAccessManager a další třídy z QtNetwork)
set(QT_USE_QTNETWORK TRUE)

# Zdrojové kódy ke kompilaci
set(idosengine_SRCS idosengine.cpp)
 
# Makro KDE
kde4_add_plugin(plasma_engine_idos ${idosengine_SRCS})

# Slinkujeme proti všem potřebným knihovnám
target_link_libraries(plasma_engine_idos
                      ${KDE4_PLASMA_LIBS} 
		      ${KDE4_KDEUI_LIBS}
		      ${QT_QTNETWORK_LIBRARY})
 
# Nainstaluje knihovnu a soubor .desktop na určená místa
install(TARGETS plasma_engine_idos
        DESTINATION ${PLUGIN_INSTALL_DIR})
 
install(FILES plasma-engine-idos.desktop
        DESTINATION ${SERVICES_INSTALL_DIR})

Testování

Když teď DataEngine přeložíme, musíme otestovat, jestli dělá to, co má. Buď si můžeme napsat widget, ale mnohem jednodušší způsob je použít program plasmaengineexplorer. V seznamu vybereme náš engine (IDOS). Jako zdroj uvedeme URL spojení a po kliknutí na tlačítko se dole zobrazí zdroj se seznamem dat.

Když vyberete DataEngine time, načte se seznam zdrojů, aniž byste nějaký zadávali. Time je příklad DataEnginu, který má zdroje předdefinované.

Applet

Budeme víceméně vycházet z appletu, který jsme vytvořili v minulém dílu. Odstraníme část pro stahování a parsování stránky a přidáme tlačítka pro přechod k následujícímu/předchozímu spoji a samozřejmě vytvoříme spojení s DataEnginem.

Kód

Soubory idossearch.h, idossearch.cpp a plasma-applet-idos_search.desktop se nijak nezměnily.

searchwidget.h

#ifndef SEARCHWIDGET_HEADER
#define SEARCHWIDGET_HEADER


#include <QObject>
#include <QWidget>
#include <QGraphicsLinearLayout>

#include <KIcon>

#include <Plasma/LineEdit>
#include <Plasma/Label>
#include <Plasma/PushButton>
#include <Plasma/TextBrowser>
#include <Plasma/DataEngine>

// Dopředné deklarace
namespace Plasma
{
  class Icon;
  class Dialog;
}

namespace IDOSSearchApplet
{
  
  class SearchWidget : public QGraphicsWidget
  {
    Q_OBJECT
    public:
      // Konstruktor a destruktor
      SearchWidget(QGraphicsWidget *parent = 0);
      ~SearchWidget() { }
      
    public slots:
      // Slot, který je volán DataEnginem, když jsou
      // ve zdroji dostupná nová data
      void dataUpdated(const QString& source, const Plasma::DataEngine::Data &data);
      
    private:
      // Vytvoří rozhraní
      void setUpInterface();
      
      Plasma::DataEngine *m_engine;
         
      QString m_previousUrl;
      QString m_nextUrl;
      QString m_currentUrl;
      
      KIcon m_icon;
      
      QGraphicsLinearLayout *m_layout;
      QGraphicsLinearLayout *m_buttons_layout;
      
      Plasma::LineEdit *m_from;
      Plasma::LineEdit *m_to;
      Plasma::Label *m_from_label;
      Plasma::Label *m_to_label;
      Plasma::PushButton *m_search_button;
      Plasma::PushButton *m_previous_button;
      Plasma::PushButton *m_next_button;
      Plasma::TextBrowser *m_text_browser;

    private slots:
      void onSearch();
      void onPrevious();
      void onNext();
  };
}

#endif

Zde nám přibyl pouze ukazatel na Plasma::DataEngine, metoda dataUpdated a místo WebView používáme TextBrowser. Sloty onPrevious() a onNext() jsou volány při použití tlačítek pro navigaci mezi spoji.

searchwidget.cpp

#include "searchwidget.h"

#include <Plasma/DataEngineManager>

#include <QSizePolicy>
#include <QRegExp>

using namespace Plasma;
using namespace IDOSSearchApplet;

SearchWidget::SearchWidget(QGraphicsWidget *parent): QGraphicsWidget(parent)
{
  // Umlčí kompilátor
  Q_UNUSED(parent);  
    
  // Připojí se k enginu a vrátí ukazatel na něj
  m_engine = DataEngineManager::self()->loadEngine("idos");
  
  setUpInterface();
  
}

// Vytvoří uživatelské prostředí
void SearchWidget::setUpInterface()
{
    m_layout = new QGraphicsLinearLayout(Qt::Vertical,this);
    
    m_from_label = new Label(this);
    m_from_label->setText("Odkud:");
    m_layout->addItem(m_from_label);
    
    m_from = new LineEdit(this);
    m_layout->addItem(m_from);
    
    m_to_label = new Label(this);
    m_to_label->setText("Kam:");
    m_layout->addItem(m_to_label);

    m_to = new LineEdit(this);
    m_layout->addItem(m_to);
    
    m_search_button = new PushButton(this);
    m_search_button->setText("Hledat!");
    connect(m_search_button, SIGNAL(clicked()),this,SLOT(onSearch()));
    m_layout->addItem(m_search_button);
    
    m_text_browser = new TextBrowser(this);
    m_text_browser->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
    m_text_browser->setPreferredSize(260,200);
    m_layout->addItem(m_text_browser);
    
    m_buttons_layout = new QGraphicsLinearLayout(Qt::Horizontal,m_layout);
    
    m_previous_button = new PushButton(this);
    m_previous_button->setText(QString::fromUtf8("Předchozí spojení"));
    connect(m_previous_button, SIGNAL(clicked()),this,SLOT(onPrevious()));
    m_buttons_layout->addItem(m_previous_button);
    
    m_next_button = new PushButton(this);
    m_next_button->setText(QString::fromUtf8("Další spojení"));
    connect(m_next_button, SIGNAL(clicked()),this,SLOT(onNext()));
    m_buttons_layout->addItem(m_next_button);
    
    m_layout->addItem(m_buttons_layout);
    
    this->setLayout(m_layout);
    this->setMinimumSize(260, 420);

}


// Volá se při kliknutí na tlačítko „Hledat“
void SearchWidget::onSearch()
{
   // Vytvoří a uloží současnou URL. Ta se zároveň použije i jako název zdroje
   m_currentUrl = "http://ttwap.chaps.cz/conn.aspx?Odkud="+m_from->text()+"&Kam="+m_to->text()+"&Datum=&Cas=&JR=&OP=&Lang=C&Format=2&cmd=search";
   // Připojí se ke zdroji. První parametr je název zdroje, druhý objekt, který bude přijímat události zdroje, a třetí interval pro aktualizace
   m_engine->connectSource(m_currentUrl, this, 0);
}

// Volá se při kliknutí na „Další spojení“
void SearchWidget::onNext()
{
  // Jako název zdroje použije URL stránky s následujícím
  // spojením. Tuto adresu získáme ze zdroje spolu s původními daty
  m_engine->connectSource(m_nextUrl, this, 0);
}

// Volá se při kliknutí na "Předchozí spojení"
void SearchWidget::onPrevious()
{
  // Jako název zdroje se použije URL stránky s předchozím
  // spojením. Adresu získáme ze zdroje spolu s původními daty
  m_engine->connectSource(m_previousUrl, this, 0);
}

// Tato metoda je volána DataEnginem, když jsou ve zdroji dostupná nová data
void SearchWidget::dataUpdated(const QString& source, const Plasma::DataEngine::Data &data)
{
    // Umlčí kompilátor; obsahuje název zdroje, ke kterému patří získaná data
    Q_UNUSED(source);

    // Vymaže informace o předchozím spojením
    m_text_browser->setText("");

    // Načte data
    m_previousUrl = data["previousUrl"].toString();
    m_nextUrl = data["nextUrl"].toString();
    QStringList stations = data["stations"].toStringList();
    foreach (const QString &station, stations) {
	m_text_browser->setText(m_text_browser->text().append("\n").append(station));
   }

}

#include "searchwidget.moc"

V konstruktoru se k našemu DataEnginu připojuji trošku složitějším způsobem. Kdyby byl tento widget odvozen od třídy Plasma::Applet či Plasma::PopupApplet, měl bych k dispozici metodu dataEngine, která přijímá jako parametr název enginu, ke kterému se připojujeme. Kód by pak vypadal takto:

m_engine = dataEngine("idos");

Nicméně pokud se podíváte do zdrojových kódů KDE, zjistíte, že metoda dataEngine nás připojí k požadovanému DataEnginu úplně stejným způsobem jako to, do děláme tady.

CMakeLists.txt

# Project Needs a name ofcourse
project(plasma-idos_search)
 
# Find the required Libaries
find_package(KDE4 REQUIRED)

include(KDE4Defaults)

add_definitions (${QT_DEFINITIONS} ${KDE4_DEFINITIONS})
include_directories(
   ${CMAKE_SOURCE_DIR}
   ${CMAKE_BINARY_DIR}
   ${KDE4_INCLUDES} )

# We add our source code here
set(idos_search_SRCS idossearch.cpp searchwidget.cpp)
 
# Now make sure all files get to the right place
kde4_add_plugin(plasma_applet_idos_search ${idos_search_SRCS})
target_link_libraries(plasma_applet_idos_search 
                      ${KDE4_PLASMA_LIBS} 
		      ${KDE4_KDEUI_LIBS} )
 
install(TARGETS plasma_applet_idos_search
        DESTINATION ${PLUGIN_INSTALL_DIR})
 
install(FILES plasma-applet-idos_search.desktop
        DESTINATION ${SERVICES_INSTALL_DIR})

install(FILES idos_search.svgz
	DESTINATION ${CMAKE_INSTALL_PREFIX}/share/icons/hicolor/scalable/apps)

Zde jsme pouze vypustili vkládání modulu QtNetwork a linkování proti jeho knihovnám, protože to se vše přesunulo do DataEnginu.

Závěr

Na konec ještě přikládám tarball s kompletními zdrojovými kódy. Příště si ukážeme, jak k Plasmoidu přidat dialog pro konfiguraci. K tomuto appletu už se nejspíš vracet nebudeme, ale já bych ho rád ještě o pár funkcí obohatil a rozhodil ho mezi širší veřejnost, takže můžete jeho další vývoj sledovat na kde-look.org.

       

Komentáře