Programarea setarilor utilizator in KDE 3

Partea a-III-a: Citirea si scrierea setarilor

Dupa cum probabil stiti, cele mai multe aplicatii KDE permit setari specifice utilizatorului. Aceste setari sint stocate in fisiere de configurare care arata cam asa: ~/.kde/share/config/<fisier-rc-aplicatie>.

Librariile KDE deja ne pun la dispozitie functiile necesare pentru a citi si scrie setarile in fisierul de configurare al aplicatiei. Pentru a vedea cum lucreaza, vom crea citeva proprietati in obiectul de configurare, numite m_font, m_text si m_textColor. Retineti ca folosesc denumiri tipice utilizate prin conventie pentru variabilele membru, care pot fi rezumate in urmatoarele reguli:

1. puneti m_ in fata variabilelor membru, astfel incit sa le puteti deosebi de variabilele locale.
2. incepeti numele cu litere mici, urmat de cuvinte care incep cu litera mare, de exemplu int m_bigTextSize
3. cind aveti o functie membru care intoarce continutul unei variabile membru, numiti-o la fel dar fara m_, de exemplu int bigTextSize();
4. functiilor membru care seteaza o valoare le puneti "set" in fata, de exemplu void setBigTextSize(int size);

Vom adauga citeva proprietati publice in obiectul de configurare (puteti sa le faceti private si sa le puneti la dispozitie functii cu care se pot accesa, dar pentru a simplifica voi folosi variabile membru publice). Vom mai avea nevoie de doua functii pentru citirea si scrierea configuratiei setarilor. Declaratia clasei Configuration devine:

#ifndef CONFIGURATION_H
#define CONFIGURATION_H

#include <qstring.h>
#include <qfont.h>
#include <qcolor.h>

/// Acesta este singurul obiect de configurare.
/// Functiile membru read() si write() pot fi folosite
/// pentru a incarca si salva
/// proprietatile in fisierul de configurare al aplicatiei.
class Configuration {
  public:
    /// Citeste datele din fisierul de configurare.
    /// Daca o propietate nu exista in fisierul de configurare
    /// ii va seta o valuare implicita.
    void read();
    /// Salveaza datale in fisierul de configurare.
    void write() const;

    QString m_text;      ///< Textul afisat in widget-ul principal.
    QFont   m_font;      ///< Fontul folosit pentru text.
    QColor  m_textColor; ///< Culoarea widget-ului principal.

  private:
    Configuration();
    Configuration(const Configuration&);

    friend Configuration& Config();
};

/// Intoarce o referinta la obiectul de configurare al aplicatiei.
Configuration& Config<();

#endif  // CONFIGURATION_H

Sint citeva lucruri noi in acest fisier. La inceput sint incluse trei fisiere antet, fiecare pentru cite o clasa QT pe care o folosim. Daca nu sinteti familiarizat cu aceste clase, aruncati o privire asupra documentatiei claselor QT.

In continuare avem variabilele membru mentionate mai sus si doua functii read() si write().

Nota:

Declarati constante toate functiile membru care nu schimba starea interna a clasei!

Probabil ati observat ca am folosit comentarii un pic mai ciudate si nu cum se folosesc normal in C++ cu doua bare inclinate dreapta, ci cu trei si mai mult. In cazul variabilelor membru nu numai ca am folosit trei linii inclinate dar si <. Aceasta este o metoda speciala de a documenta sursa astfel incit generatoarele de documentatii precum Doxygen sa poata genera documentatia despre program. Daca vreti sa vedeti cum arata o astfel de documentatie descarcati settingstutorial-01html.tar.gz si aruncati o privire asupra ei.

Acum vom implementa functiile membru read() si write().

#include "configuration.h"

#include <kapplication.h>       // pentru 'kapp'
#include <kconfig.h>            // pentru KConfig

Configuration::Configuration() {
    read(); // Citeste setarile sau seteaza-le cu cele implicite
};

void Configuration::read() {
    KConfig *conf=kapp->config();
    // citeste optiunile generale
    conf->setGroup("General");
    m_text = conf->readEntry("text", "Hello World");
    // citeste optiunile de stil
    conf->setGroup("Style");
    QFont defaultFont = QFont("Helvetica");
    m_font = conf->readFontEntry("font", &defaultFont);
    QColor defaultColor(0,0,50);
    m_textColor = conf->readColorEntry("textColor", &defaultColor);
};

void Configuration::write() const {
    KConfig *conf=kapp->config();
    // scrie optiunile generale
    conf->setGroup("General");
    conf->writeEntry("text", m_text);
    // si pe cele de stil
    conf->setGroup("Style");
    conf->writeEntry("font", m_font);
    conf->writeEntry("textColor", m_textColor);
};

Configuration& Config() {
    static Configuration conf;
    return conf;
};

Din nou sint fisiere noi incluse, numite kapplication.h si kconfig.h. Primul ne pune la dispozitie un pointer global, la obiectul aplicatiei, kapp. Cel de-al doilea contine declaratia obiectului KConfig.

Am adaugat o singura linie in constructor care apeleaza functia membru read(). Astfel la creare vom avea valorile setarilor in obiectul de configurare.

Acum vom lamuri functia membru write().

KConfig *conf=kapp->config();

In aceasta linie primim un pointer la o clasa care ne permite sa lucram cu fisierul de configurare. Asta este tot ceea ce trebuie sa faceti - toata munca de localizare/deschidere/inchidere este facuta de librariile KDE. Acum putem sa scriem proprietatile in fisier. Fiecare inregistrare are o cheie si o valoare. Cheia este un text normal si valoarea poate fi aproape orice tip de data QT. Cheile pot fi texte normale, dar in programe complexe pot aparea mai multe chei cu aceeasi denumire asa ca puteti folosi grupuri. Ca sa puteti scrie intr-un anumit grup trebuie setat astfel:

conf->setGroup("General");

Acum grupul General este setat si toate cheile care vor fi scrise vor apartine acestui grup.

Nota:

Toate cheile intr-un grup trebuie sa fie unice!

Comanda cu care se scriu cheile intr-un grup este:

conf->writeEntry("font", m_font);

Functia writeEntry() converteste automat valoarea intr-un sir de caractere si o stocheaza in fisierul de configurare. Restul functiilor write() se comporta la fel si nu cred ca sint greu de inteles. Setam un alt grup si scriem setarile de stil in el. Puteti alege orice nume doriti pentru chei, dar ar trebui sa le numiti similar cu variabilele membru.

Acum sa aruncam o privire si la functia read(). La inceput primim un pointer la obiectul de configurare al aplicatiei, dupa care setam grupul din care vrem sa citim (la fel cum am facut si in functia write()). Citirea unui sir de caractere este foarte simpla, dupa cum puteti vedea mai jos:

m_text = conf->readEntry("text", "Hello World");

Primul parametru al functiei readEntry() este cheia si al doilea este parametru este valoarea implicita, in cazul nostru textul "Hello World". Ori de cite ori cheia nu este in fisierul de configurare sau chiar daca fisierul nu exista (inca), va fi returnata valoarea implicita .

Alte proprietati au nevoie de citeva conversii. Deoarece valorile sint scrise ca texte (fara un identificator de tip), trebuie sa specificam tipul care va fi returnat alegind functia de citire corecta. Pentru aproape toate tipurile de date C++ sau QT exista o functie speciala de citire a unei chei. Aruncati o privire asupra claselor KDE/QT. Pentru scopul nostru avem nevoie doar de readFontEntry() pentru font si de readColorEntry() pentru culoare. Ambele functii de citire primesc un pointer la obiectul care contine valoarea implicita. De aceea am creat obiectele temporare QFont si QColor si am dat adresele lor ca parametru la functia de citire.

In orice caz, dupa executia functiei de citire, obiectul de configurare va contine ori valorile setate de utilizator mai inainte ori valorile implicite. Deoarece apelam functia de citire direct din constructor, sintem foarte siguri ca obiectul de configurare va avea de la inceput date valide.

Puteti sa descarcati proiectul curent: settingstutorial-02.tar.gz