View source for Development/Tutorials/Plasma4/GettingStarted (uk)

{{Proposed_deletion|reason=Page was created before the current translation system.}}

{{TutorialBrowser|

series=Plasma Tutorial|

name=Creating your first Plasmoid|

pre=[http://mindview.net/Books/TICPP/ThinkingInCPP2e.html C++], [http://www.trolltech.com/products/qt/ Qt], [[Getting_Started/Build/KDE4|KDE4 development environment]]|

next=| 

reading=[[Development/Tutorials/CMake|CMake]]
}}
==Передмова==
Дана інструкція потребує збірки kde 4.2.
В даній статті ми створимо простий міні-додаток. Щоб зберегти простоту, ми створимо статичний міні-додаток із використанням наступних компонентів: 

* SVG малюнок
* Іконка
* Довільний простий текст

[[image:creatingyourfirstplasmoid1.png|frame|center]]

== Код міні-додатку ==
=== Файл .desktop ===
Кожен міні-додаток повинен містити файл .desktop, щоб вказати плазмі як і під яким іменем його запускати.

'''plasma-applet-tutorial1.desktop'''
<syntaxhighlight lang="ini">
[Desktop Entry]
Name=Tutorial 1
Comment=Plasma Tutorial 1
Type=Service

X-KDE-ServiceTypes=Plasma/Applet
X-KDE-Library=plasma_applet_tutorial1
X-KDE-PluginInfo-Author=Bas Grolleman
X-KDE-PluginInfo-Email=bgrolleman@emendo-it.nl
X-KDE-PluginInfo-Name=plasma_applet_tutorial1
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Examples
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
</syntaxhighlight>

Найважливішими є пункти '''X-KDE-Library''' та ''' X-KDE-PluginInfo-Name''', вони забезпечуються зв'язок між вашим класом та плазмою, без них нічого працювати не буде. Для '''X-KDE-PluginInfo-Category''', див. [[Projects/Plasma/PIG | PIG]].

=== Файл заголовка ===
Це приклад файлу заголовка. Коментарі в коді додані для пояснення.

'''plasma-tutorial1.h'''
<syntaxhighlight lang="cpp-qt">
// Виключаємо повторне завантаження заголовків
#ifndef Tutorial1_HEADER
#define Tutorial1_HEADER

#include <KIcon>
// Необхідно включити заголовок Applet плазми 
#include <Plasma/Applet>
#include <Plasma/Svg>
 
class QSizeF;
 
// Визначаємо наш Applet плазми
class PlasmaTutorial1 : public Plasma::Applet
{
    Q_OBJECT
    public:
        // Конструктор та деструктор
        PlasmaTutorial1(QObject *parent, const QVariantList &args);
        ~PlasmaTutorial1();
 
        // paintInterface - процедура для промальовки Applet
        void paintInterface(QPainter *painter,
                const QStyleOptionGraphicsItem *option,
                const QRect& contentsRect);
	void init();

    private:
        Plasma::Svg m_svg;
        KIcon m_icon;
};
 
// Ця команда зв'язує ваш Applet з .desktop файлом
K_EXPORT_PLASMA_APPLET(tutorial1, PlasmaTutorial1)
#endif
</syntaxhighlight>

==== Метод QRectF boundingRect() ====
Функція <tt>boundingRect()</tt> повідомляє плазмі актуальні розміри міні-додатку. Це важливо, оскільки ми повинні знати, скільки місця займаємо на екрані.
{{tip|
Якщо виникають проблеми з неправильною промальовкою, то зазвичай це результат неправильної роботи функції boundingRect().
}}

==== Метод void paintInterface(QRectF contentsRect) ====
Ця функціявважається головною, оскільки відповідає за промальовування плазмоїда на екрані. Тут ви можете визначити, як буде виглядати ваш додаток. Ви повинні проводити малювання в межах, визначених через contentsRect та уникати виходу за них за допомогою функції geometry(). Коли міні-додаток не має свого власного стандартного фону, наприклад він був відключений у функції setBackgroundHints() чи є панеллю, то geometry() та boundingRect() поводять себе так само, але, коли використовується стандартний фон(звичний випадок), аплет буде мати місця, де краще не малювати.

==== Макрос K_EXPORT_PLASMA_APPLET ( <name>, <class> ) ====
Це маленька, але дуже важлива частина, що зв'язує ім'я вашого класу з іменем аплету, що визначене в файлі .desktop.

Якщо ваш аплет не завантажується, то одною з причин може бути якраз невідповідність у цьому місці.

{{tip|
Макрос K_EXPORT_PLASMA_APPLET додає "plasma_applet_", будь ласка, враховуйте це, коли налаштовуєте ваш .desktop файл, щоб уникнути розбіжностей в іменах.
}}

=== Головний робочий файл ===
Тут описано вміст функцій із коментарями.

'''plasma-tutorial1.cpp'''
<syntaxhighlight lang="cpp-qt">
#include "plasma-tutorial1.h"
#include <QPainter>
#include <QFontMetrics>
#include <QSizeF>
 
#include <plasma/svg.h>
#include <plasma/theme.h>
 
PlasmaTutorial1::PlasmaTutorial1(QObject *parent, const QVariantList &args)
    : Plasma::Applet(parent, args),
    m_svg(this),
    m_icon("document")
{
    m_svg.setImagePath("widgets/background");
    // встановлюємо стандартний фон
    setBackgroundHints(DefaultBackground);
    resize(200, 200);
}
 

PlasmaTutorial1::~PlasmaTutorial1()
{
    if (hasFailedToLaunch()) {
        // Очистка
    } else {
        // Зберігаємо налаштування
    }
}

void PlasmaTutorial1::init()
{
 
    // Невелика демонстрація виклику функції setFailedToLaunch
    if (m_icon.isNull()) {
        setFailedToLaunch(true, "Немає світу, котрому можна сказати привіт!");
    }
} 
 
 
void PlasmaTutorial1::paintInterface(QPainter *p,
        const QStyleOptionGraphicsItem *option, const QRect &contentsRect)
{
    p->setRenderHint(QPainter::SmoothPixmapTransform);
    p->setRenderHint(QPainter::Antialiasing);
 
    // Зараз ми намалюємо наш аплет, почнемо з нашого svg
    m_svg.resize((int)contentsRect.width(), (int)contentsRect.height());
    m_svg.paint(p, (int)contentsRect.left(), (int)contentsRect.top());
 
    // Помістимо іконку та текст на аплет.
    p->drawPixmap(7, 0, m_icon.pixmap((int)contentsRect.width(),(int)contentsRect.width()-14));
    p->save();
    p->setPen(Qt::white);
    p->drawText(contentsRect,
                Qt::AlignBottom | Qt::AlignHCenter,
                "Привіт, Plasmoid!");
    p->restore();
}
 
#include "plasma-tutorial1.moc"
</syntaxhighlight>

==== Клас Plasma/Svg ====
Як ви могли побачити із коду, ми використовували {{class|Plasma::Svg}} об'єкт, достатньо важливий, щоб відмітити його тут.

Спершу ми виставляємо відносний шлях до файлу '''widgets/background''' для {{class|Plasma::Svg}}, котрий використовується в {{class|Plasma::Theme}} для знаходження SVG-даних. Поки {{class|Plasma::Svg}} не підтримує завантаження довільних файлів з абсолютними шляхами, використовуйте відносні шляхи із теми якомога частіше, оскільки це дозволяє окремим плазмоїдам виглядати одинаково, використовуючи визначений в даний момент стиль Plasma. Список доступних картинок можна знайти на [[Projects/Plasma/Theme|Plasma Theme page]].

Н будь-якому режимі, {{class|Plasma::Svg}} може використовуватися для розбору вмісту SVG файлів, дістаючи із них елементи по ідентифікаторах, котрі містяться в SVG документі. Хороший приклад: якщо ви відкриєте файл clock.svg, то він буде відкритий з темою за замовчуванням, ви маєте побачити фон, 3 стрілки та задній фон(прозорість). Через можливість помістити всі елементи в один файл SVG, файл покаже годинник. Це набагато зручніше, ніж редагувати 5 різних файлів, коли вони повинні знаходитися один над одним, а також це покращує продуктивність при розборі SVG файла і зчитуванні його з диску.

==== Метод setBackgroundHints(DefaultBackground) ====
Оскільки малювання фону є загальною функцією, існує швидкий і простий спосіб промалювати його. При додаванні <tt>setBackgroundHints(DefaultBackground)</tt> до вашого коду, стандартний фон Plasma буде малюватися позаду вашого міні-додатку. Це не тільки економить ваш час і кількість коду, але й створює більш послідовне представлення для користувача.

==== Метод init() ====
В конструкторі ви повідомляєте плазмі тільки про фон додатку та конфігураційний файл, якщо такі є. Ви також можете виставляти розміри міні-додатку в конструкторі. Після цього плазма бере відповідальність за зміну розмірів на себе і ви можете не думати на рахунок цього. У методі <tt>init()</tt> ви можете ініціалізувати все, що захочете, наприклад зчитування інформації з конфігураційного файлу.

==== Метод hasFailedToLaunch() ====

Якщо в деяких випадках міні-додаток не може бути запущений (наприклад не завантажені деякі бібліотеки, відсутні драйвери для деякого обладнання  і т.п.), то цей метод поверне значення true. Використання цього методу дасть вашому додатку можливість виконати деяку очистку перед завершенням.

==== Метод setFailedToLaunch(bool, QString) ====
Якщо ваш додаток не в стані запуститися, то, викликавши даний метод, ви зможете повідомити плазму як і чому це сталося. Після цього плазма намалює стандартний інтерфейс із повідомленням про помилку для користувача і ваш міні-додаток не буде виконувати те, для чого він був призначений. Якщо ваш міні-додаток складний та залежить від багатьох зовнішніх факторів, то це найкращий спосіб проведення очистки.

==== Функція dataUpdated ====
Якщо ви хочете обробляти будь-які дані від plasma's data-engines, вам необхідно реалізувати функцію dataUpdated у вашому міні-додатку. Остання викликається, якщо data-engine надсилає вам дані, тобто ваш міні-додаток повинен перерахувати свій вміст.

==== Визначення форми та розміру аплета: функції geometry() та contentsRect() ====
Якщо ви хочете дізнатися в коді аплету, який розмір та форму має аплет, викличте contentsRect() та contentsRect().size(). Уникайте викликів функцій geometry() та size(), тому що вони не враховують розмір поля фону, що встановлюється аплетам за замовчуванням. Також уникайте використання абсолютних значень для позиціонування аплета, наприклад таких як QPoint(0, 0) для показу верхньої лівої точки вашого аплету. Замість цього використовуйте contentsRect().topLeft().

=== Побудова, файл CMakeLists.txt ===
Нарешті, для зв'язування всього разом, вам необхідно це все збудувати. Для вказання cmake, що потрібно робити, вкажемо йому файл CMakeLists.txt.

За деталями роботи CMake, будь ласка, звертайтесь до документації [[Development/Tutorials/CMake]]

<syntaxhighlight lang="bash">
# Проекту звісно ж потрібне ім'я
project(plasma-tutorial1)

# Пошук необхідних бібліотек
find_package(KDE4 REQUIRED)
include(KDE4Defaults)

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

# Тут ми додаємо наш код
set(tutorial1_SRCS plasma-tutorial1.cpp)

# Переконайтеся, що всі шляхи до файлів правильні
kde4_add_plugin(plasma_applet_tutorial1 ${tutorial1_SRCS})
target_link_libraries(plasma_applet_tutorial1 
                      ${KDE4_PLASMA_LIBS} ${KDE4_KDEUI_LIBS})

install(TARGETS plasma_applet_tutorial1
        DESTINATION ${PLUGIN_INSTALL_DIR})

install(FILES plasma-applet-tutorial1.desktop
        DESTINATION ${SERVICES_INSTALL_DIR})
</syntaxhighlight>

== Тестування аплета ==
Якщо ваше середовище розробки відрізняється від тестової установки, ви повинні запускати cmake з параметром -DCMAKE_INSTALL_PREFIX=/usr/lib/kde4/ (замініть вашою змінною $KDEDIR). Потім запустіть make. Якщо результат вдалий, то аплет може бути встановлений за допомогою команди sudo make install чи
* cp ./lib/plasma_applet_tutorial1.so $KDEDIR/lib 
* cp ./plasma-applet-tutorial1.desktop $KDEDIR/share/kde4/services/

та запуском kbuildsycoca4 (так додатки KDE дізнаються про нові файли *.desktop)
Для тестового запуску вашoго аплета ви можете використовувати програму '''plasmoidviewer''' виконавши:
<syntaxhighlight lang="bash">
plasmoidviewer applet_name
</syntaxhighlight>

Де '''applet_name''' значення, вказане в .desktop для ключа '''X-KDE-PluginInfo-Name'''.

Або ви можете перезапустити плазму, так що аплет буде відображений у вікні вибору аплетів:
<syntaxhighlight lang="bash">
kbuildsycoca4
kquitapp plasma
plasma 
</syntaxhighlight>

Якщо так не працює, вам необхідно перезапустити вашу KDE сесію здійснивши вихід із системи та увійшовши знову.