Mechanizm wtyczek
Z Kadu
Wstęp
Mechanizm wtyczek umożliwia rozszerzanie funkcjonalności komunikatora Kadu za pomocą pakietów nazywanych wtyczkami składających się z dodatkowego, zewnętrznego kodu i plików z danymi. Wtyczki mogą być dynamicznie ładowane i wyładowywane z Kadu w trakcie pracy komunikatora lub też może być wkompilowane statycznie.
Pliki wtyczki
Każda wtyczka Kadu ma swój podkatalog w katalogu "modules" w źródłach komunikatora. Tam też powinny być umieszczane dodatkowe wtyczki, które chcemy skompilować wraz z Kadu. Nazwa podkatalogu wtyczki jest dość istotną rzeczą, ponieważ informuje komunikator pod jaką nazwą wtyczka będzie obecna w okienku menadżera wtyczek. W dalszej części dokumentu podkatalog wtyczki będzie reprezentowany przez wyrażenie $MODULE.
Nazwa wtyczki
Nazwa wtyczki powinna się składać z małych angielskich liter alfabetu. Oprócz tego na chwilę obecną przyjętych jest kilka specjalnych przyrostków (suffixów): "_sound" dla wtyczek dźwiękowych, "_scripting" dla wtyczek obsługujących języki skryptowe, "_notify" dla wtyczek powiadomień oraz "_docking" dla wtyczek dokujących. Wtyczki kwalifikujące się do wyżej wymienionych kategorii powinny mieć wymagany przyrostek. Przykłady nazw wtyczek: autoresponder, alsa_sound, exec_notify.
Katalog wtyczki
W katalogu $MODULE umieszczamy źródła wtyczek (pliki .cpp i .h), plik "README" i "ChangeLog" i tym podobne oraz plik "CMakeLists.txt" oraz <nazwa_wtyczki.desc> zawierający informacje wymagane do załadowania wtyczki i wyświetlane w oknie "zarządcy wtyczek". Przyjmujemy dodatkowo standardowe podkatalogi: "translations" - z plikami tłumaczeń, jeśli wtyczka takie posiada, configuration - jeśli wtyczka dodaje swoje pola do konfiguracji, "doc" - jeśli wtyczka posiada dokumentację, data - z dodatkowymi plikami danych (obrazki itp), które mają zostać zainstalowane wraz z wtyczką oraz bin z dodatkowymi programami. W ramach potrzeb dopuszczalne są również inne, nie wymienione.
Dodawanie pól do okna konfiguracji
Aby dodać pola do okna konfiguracji kadu, należy utworzyć w katalogu $MODULE podkatalog configuration. W tym podkatalogu tworzy się plik<nazwa_wtyczki>.ui wg następującego wzoru: <configuration-ui> <section name="<nazwa_sekcji_w_konfiguracji>" icon="<opcjonale_ścieżka_do_ikony>" > <tab name="tytuł_karty"> <group-box name="nazwa"> <rodzaj_kontroli caption="Tytuł" config-section="Sekcja w pliku konfiguracyjnym" config-item="pole w pliku konfiguracyjnym" id="id" tooltip="" />> </group-box> </tab> </section> </configuration-ui>
Dokładniejsze informacje o składni, rodzajach pól i parametrach można znależć w dokumentacji kodu.
Najlepszym źródłem przykładów korzystania z okna konfiguracji jest kod wtyczek dostarczanych standardowo z kadu. W razie problemów i pytań zachęcamy do zadawania pytań na naszym forum w dziale Programowanie Kadu
Translacje napisów
W stałych znakowych w kodzie wtyczki (w komunikatach, opisach menu i innych) używamy języka angielskiego. Używamy funkcji tr() i pochodnych z biblioteki Qt - http://doc.trolltech.com/4.7/linguist-manual.html. W katalogu wtyczki robimy podkatalog translations i wrzucamy tam pliki .ts w postaci: <nazwa_wtyczki>_<dwuliterowy_kod_kraju>.ts np. autoresponder_pl.ts
Budowanie wtyczki - plik CMakeLists.txt
Plik CMakeLists.txt zawiera wszystkie informacje o wtyczce potrzebne do jego zbudowania. Kadu korzysta z nowoczesnego systemu budowania jakim jest CMake 2.6
set (SOURCES
autoaway.cpp
autoaway-status-changer.cpp
)
set (MOC_SOURCES
autoaway.h
autoaway-status-changer.h
)
set (TRANSLATION_SOURCES
translations/autoaway_de.ts
translations/autoaway_fr.ts
translations/autoaway_it.ts
translations/autoaway_pl.ts
)
set (CONFIGURATION_FILES
configuration/autoaway.ui
)
kadu_module (autoaway
MODULE_SOURCES ${SOURCES}
MODULE_MOC_SOURCES ${MOC_SOURCES}
MODULE_TRANSLATION_SOURCES ${TRANSLATION_SOURCES}
MODULE_CONFIGURATION_FILES ${CONFIGURATION_FILES}
MODULE_DEPENDENCIES idle
)
Współpraca wtyczki z Kadu
Wtycza=ka w którymś z plików źródłowych, z których powstaje biblioteka so, powinien zawierać następujące funkcje, zadeklarowane dokładnie tak jak to napisane poniżej:
extern "C" int <nazwa_wtyczki>_init(bool firstLoad)
{
// inicjalizacja wtyczki
// ...
return 0;
}
extern "C" void <nazwa_wtyczki>_close()
{
// zamknięcie wtyczki, porządki
// ...
}
Po załadowaniu wtyczki do pamięci Kadu uruchamia funkcję inicjalizującą "<nazwa_wtyczki>_init", która powinna przygotować wtyczkę do dalszej pracy i zwrócić kod błędu (jeszcze nie są ustalone, narazie używamy liczby 1) lub liczbę 0 jeśli inicjalizacja przebiegła pomyślnie. Parametr firstLoad określa czy wtyczka została załadowana pierwszy raz. Przed wyładowywaniem wtyczki przez Kadu uruchamiana jest funkcja "<nazwa_wtyczki>_close", która powinna przygotować wtyczkę do usunięcia z pamięci, pozwalniać zaalokowaną pamięć i tym podobne. W funkcjach tych istnieje możliwość korzystania z translacji ponieważ translator dla wtyczki tworzony jest przed wywołaniem funkcji "init" i usuwany po powrocie z funkcji "close".
Aby skorzystać we wtyczce z funkcjonalności oferowanych przez Kadu dołączamy nagłówki programu i używamy odpowiednich klas, obiektów, funkcji. Informację o różnego typu wydarzeniach (np. otrzymanie nowej wiadomości) możemy otrzymać podłączając się pod odpowiednie sygnały - http://doc.trolltech.com/4.7/signalsandslots.html.
Co zrobić z napisaną wtyczką?
Jeśli uważasz, że napisana przez Ciebie wtyczka oferuje ciekawą funkcjonalność skompresuj katalog z wtyczką do postaci tar.gz lub tar.bz2 (usuń pliki cxxflags, ldflags i pliki tymczasowe), upublicznij gdzieś w internecie i napisz jakąś informację o tym na forum Kadu w dziale "Moduły - Informacje".
Jeśli wtyczka będzie miał pozytywną opinię użytkowników, będzie należycie wspierany przez autora (poprawianie błędów, odpowiadanie na pytania, wyjaśnianie problemów) to zostanie umieszczony na liście oficjalnych wtyczek Kadu - http://www.kadu.net/w/Wtyczki .
Bardzo popularne lub z innych przyczyn istotne wtyczki mają szanse wylądować bezpośrednio w źródłach aplikacji.
Pytania i problemy
W razie jakichkolwiek pytań i problemów zapraszamy na nasze forum.