(New page: {{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma/GettingStarted}} {{TutorialBrowser| series=Plasma Tutorial| name=Creating your first Plasmoid| pre=[http://mindview...)
 
 
(18 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma/GettingStarted}}
+
 
  
 
{{TutorialBrowser|
 
{{TutorialBrowser|
Line 13: Line 13:
 
reading=[[Development/Tutorials/CMake|CMake]]
 
reading=[[Development/Tutorials/CMake|CMake]]
 
}}
 
}}
==Abstract==
+
==Предисловие==
This tutorial needs KDE 4.1 (trunk) to build.
+
Данное руководство требует для удачной сборки kde 4.2.
We are going to create a simple plasmoid in this tutorial. To keep things simple, we will only create a static plasmoid which will contain the following items:  
+
В данном руководстве мы создадим простое мини-приложение. Чтобы сохранить простоту мы создадим статическое мини-приложение с использованием следующих компонентов:  
  
* An SVG Image
+
* SVG рисунок
* Icon
+
* Иконка
* Some nice text
+
* Какой-либо простой текст
  
 
[[image:creatingyourfirstplasmoid1.png|frame|center]]
 
[[image:creatingyourfirstplasmoid1.png|frame|center]]
  
== The Code ==
+
== Код мини-приложения ==
=== The .desktop file ===
+
=== Файл .desktop ===
Every Plasmoid needs a .desktop file to tell plasma how it should be started and what name it carries.  
+
Каждое мини-приложение должно иметь в своём составе .desktop файл для указания плазме как и под каким именем его запускать.
  
 
'''plasma-applet-tutorial1.desktop'''
 
'''plasma-applet-tutorial1.desktop'''
<code ini>
+
<syntaxhighlight lang="ini">
 
[Desktop Entry]
 
[Desktop Entry]
 
Name=Tutorial 1
 
Name=Tutorial 1
Line 38: Line 38:
 
X-KDE-PluginInfo-Author=Bas Grolleman
 
X-KDE-PluginInfo-Author=Bas Grolleman
  
X-KDE-PluginInfo-Name=tutorial1
+
X-KDE-PluginInfo-Name=plasma_applet_tutorial1
 
X-KDE-PluginInfo-Version=0.1
 
X-KDE-PluginInfo-Version=0.1
 
X-KDE-PluginInfo-Website=http://plasma.kde.org/
 
X-KDE-PluginInfo-Website=http://plasma.kde.org/
Line 45: Line 45:
 
X-KDE-PluginInfo-License=GPL
 
X-KDE-PluginInfo-License=GPL
 
X-KDE-PluginInfo-EnabledByDefault=true
 
X-KDE-PluginInfo-EnabledByDefault=true
</code>
+
</syntaxhighlight>
  
The most important bits are the '''X-KDE-Library''' and '''X-KDE-PluginInfo-Name''', they are the "glue" between your class and plasma, without it, nothing will start. For '''X-KDE-PluginInfo-Category''', refer to the [[Projects/Plasma/PIG | PIG]].
+
Наиболее важными являются пункты '''X-KDE-Library''' и ''' X-KDE-PluginInfo-Name''', они являются "клеем" между вашим классом и плазмой, без них ничего не заработает. Для '''X-KDE-PluginInfo-Category''', см. [[Projects/Plasma/PIG | PIG]].
  
=== The header file ===
+
=== Файл заголовка ===
This is the example header file. Comments have been added in the code for clarity.
+
Это пример файла заголовка. Комментарии в код добавлены для ясности.
  
 
'''plasma-tutorial1.h'''
 
'''plasma-tutorial1.h'''
<code cppqt>
+
<syntaxhighlight lang="cpp-qt">
// Here we avoid loading the header multiple times
+
// Здесь мы избегаем загрузки заголовков несколько раз
 
#ifndef Tutorial1_HEADER
 
#ifndef Tutorial1_HEADER
 
#define Tutorial1_HEADER
 
#define Tutorial1_HEADER
// We need the Plasma Applet headers
+
// Нам необходимо загрузить заголовок Applet плазмы
 
#include <KIcon>
 
#include <KIcon>
 
   
 
   
Line 65: Line 65:
 
class QSizeF;
 
class QSizeF;
 
   
 
   
// Define our plasma Applet
+
// Определяем наш Applet плазмы
 
class PlasmaTutorial1 : public Plasma::Applet
 
class PlasmaTutorial1 : public Plasma::Applet
 
{
 
{
 
     Q_OBJECT
 
     Q_OBJECT
 
     public:
 
     public:
         // Basic Create/Destroy
+
         // Базовые конструктор и деструктор
 
         PlasmaTutorial1(QObject *parent, const QVariantList &args);
 
         PlasmaTutorial1(QObject *parent, const QVariantList &args);
 
         ~PlasmaTutorial1();
 
         ~PlasmaTutorial1();
 
   
 
   
         // The paintInterface procedure paints the applet to screen
+
         // paintInterface - процедура рисующая Applet на экране
 
         void paintInterface(QPainter *painter,
 
         void paintInterface(QPainter *painter,
 
                 const QStyleOptionGraphicsItem *option,
 
                 const QStyleOptionGraphicsItem *option,
Line 85: Line 85:
 
};
 
};
 
   
 
   
// This is the command that links your applet to the .desktop file
+
// Данная команда связывает ваш Applet с .desktop файлом
 
K_EXPORT_PLASMA_APPLET(tutorial1, PlasmaTutorial1)
 
K_EXPORT_PLASMA_APPLET(tutorial1, PlasmaTutorial1)
 
#endif
 
#endif
</code>
+
</syntaxhighlight>
  
==== QRectF boundingRect() ====
+
==== Метод QRectF boundingRect() ====
The <tt>boundingRect()</tt> function tells plasma the actual size of the plasmoid. This is important because we need to know how much space is taken on the screen.  
+
Функция <tt>boundingRect()</tt> сообщает плазме актуальные размеры мини-приложения. Это важно, так как мы должны знать сколько места занимаем на экране.
 
{{tip|
 
{{tip|
If you have issues with your plasmoid leaving pixels behind when dragging, this is usually a result of an incorrect boundingRect()
+
Если у вас есть проблемы с неправильной отрисовкой вашего мини-приложения, то обычно это результат неправильной работы функции boundingRect().
 
}}
 
}}
  
==== void paintInterface(QRectF contentsRect) ====
+
==== Метод void paintInterface(QRectF contentsRect) ====
This can be considered the main function since it paints the plasmoid on to the screen. Here, you define how you want your plasmoid to look.
+
Эта функция считается главной, так как рисует мини-приложение на экране. Здесь вы можете определить, как ваше приложение будет выглядеть.
You should only paint in the boundaries defined by contentsRect and avoid using geometry(). When a plasmoid does not have a standard background, e.g. when it's disabled with a setBackgroundHints() call or it's in the panel, geometry() and boundingRect() behave the same; however, when the standard background is enabled (the usual case), the appplet will have a margin where it should not be painted
+
Вы должны рисовать в пределах, определённых через contentsRect и избегать выхода за них с помощью функции geometry(). Когда мини-приложение не имеет собственного стандартного фона, например он был отключён в функции setBackgroundHints() или он является панелью, geometry() и boundingRect() ведут себя так же, однако, когда стандартный фон включены (обычный случай), апплет будет иметь места, где лучше не рисовать.
  
==== K_EXPORT_PLASMA_APPLET ( <name>, <class> ) ====
+
==== Макрос K_EXPORT_PLASMA_APPLET ( <name>, <class> ) ====
This is a small but very important part that links your classname to the applet name in the .desktop file. If your applet doesn't seem to get loaded, there may be a difference between this declaration and your .desktop file
+
Это маленькая, но очень важная часть связывающая имя вашего класса с именем апплета, определённом в .desktop файле.
 +
 
 +
Если ваш апплет не загружается. то одной из причин может быть именно несоответствие в этом месте.
  
 
{{tip|
 
{{tip|
The K_EXPORT_PLASMA_APPLET adds "plasma_applet_", please pay attention to this when setting up your .desktop file to avoid a name difference
+
Макрос K_EXPORT_PLASMA_APPLET добавляет "plasma_applet_", пожалуйста, учитывайте это, когда настраиваете ваш .desktop файл, чтобы избежать различий в именах.
 
}}
 
}}
  
=== The actual work file ===
+
=== Главный рабочий файл ===
Here is the body of the function, again with a lot of comments in between.  
+
Здесь описано содержимое функций с комментариями.
  
 
'''plasma-tutorial1.cpp'''
 
'''plasma-tutorial1.cpp'''
<code cppqt>
+
<syntaxhighlight lang="cpp-qt">
 
#include "plasma-tutorial1.h"
 
#include "plasma-tutorial1.h"
 
#include <QPainter>
 
#include <QPainter>
Line 126: Line 128:
 
{
 
{
 
     m_svg.setImagePath("widgets/background");
 
     m_svg.setImagePath("widgets/background");
     // this will get us the standard applet background, for free!
+
     // получаем устанавливаем стандартный фон апплета, бесплатно!
 
     setBackgroundHints(DefaultBackground);
 
     setBackgroundHints(DefaultBackground);
 
     resize(200, 200);
 
     resize(200, 200);
Line 135: Line 137:
 
{
 
{
 
     if (hasFailedToLaunch()) {
 
     if (hasFailedToLaunch()) {
         // Do some cleanup here
+
         // Действия по очистке
 
     } else {
 
     } else {
         // Save settings
+
         // Сохраняйте настройки
 
     }
 
     }
 
}
 
}
Line 144: Line 146:
 
{
 
{
 
   
 
   
     // A small demonstration of the setFailedToLaunch function
+
     // Небольшая демонстрация вызова функции setFailedToLaunch
 
     if (m_icon.isNull()) {
 
     if (m_icon.isNull()) {
         setFailedToLaunch(true, "No world to say hello");
+
         setFailedToLaunch(true, "Нет мира, которому можно сказать привет :(");
 
     }
 
     }
 
}  
 
}  
Line 157: Line 159:
 
     p->setRenderHint(QPainter::Antialiasing);
 
     p->setRenderHint(QPainter::Antialiasing);
 
   
 
   
     // Now we draw the applet, starting with our svg
+
     // Сейчас мы отрисуем наш апплет, начнём с нашего svg
 
     m_svg.resize((int)contentsRect.width(), (int)contentsRect.height());
 
     m_svg.resize((int)contentsRect.width(), (int)contentsRect.height());
 
     m_svg.paint(p, (int)contentsRect.left(), (int)contentsRect.top());
 
     m_svg.paint(p, (int)contentsRect.left(), (int)contentsRect.top());
 
   
 
   
     // We place the icon and text
+
     // Поместим иконку и текст на апплет.
 
     p->drawPixmap(7, 0, m_icon.pixmap((int)contentsRect.width(),(int)contentsRect.width()-14));
 
     p->drawPixmap(7, 0, m_icon.pixmap((int)contentsRect.width(),(int)contentsRect.width()-14));
 
     p->save();
 
     p->save();
Line 167: Line 169:
 
     p->drawText(contentsRect,
 
     p->drawText(contentsRect,
 
                 Qt::AlignBottom | Qt::AlignHCenter,
 
                 Qt::AlignBottom | Qt::AlignHCenter,
                 "Hello Plasmoid!");
+
                 "Привет, Plasmoid!");
 
     p->restore();
 
     p->restore();
 
}
 
}
 
   
 
   
 
#include "plasma-tutorial1.moc"
 
#include "plasma-tutorial1.moc"
</code>
+
</syntaxhighlight>
 +
 
 +
==== Класс Plasma/Svg ====
 +
Как вы могли увидеть из кода, мы использовали {{class|Plasma::Svg}} объект, достаточно важный, чтобы отметить его здесь.
  
==== Plasma/Svg ====
+
Сперва мы выставляем относительный путь к файлу '''widgets/background''' для {{class|Plasma::Svg}} который используется в {{class|Plasma::Theme}} для нахождения SVG данных. Пока {{class|Plasma::Svg}} не поддерживает загрузку произвольных файлов с полными путями, используйте относительные пути из темы как можно чаще. так как это позволяет отдельным плазмоидам выглядеть одинаково, используя определённый в данный момент стиль Plasma. Список доступных картинок можно найти на [[Projects/Plasma/Theme|Plasma Theme page]].
As you can see in the example code we are using the {{class|Plasma::Svg}} object, there are some important things to note here.
 
  
First we're using a relative path '''widgets/background''' which causes {{class|Plasma::Svg}} to use {{class|Plasma::Theme}} to locate the SVG data. While {{class|Plasma::Svg}} does support loading arbitrary files when passed an absolute path, use relative paths from the theme as often as possible as it makes Plasma skinable and the individual plasmoids look like a combined whole instead of a group of separate unrelated applications. You can see a list of available image components on the [[Projects/Plasma/Theme|Plasma Theme page]].
+
В любом режиме, {{class|Plasma::Svg}} может использоваться для разбора состовляющего SVG файлов, извлекая из них элементы по идентификаторам, которые содержатся в документе SVG. Хороший пример: если вы откроете файл clock.svg то он будет открыт с темой по умолчанию, вы должны будете увидеть фон, 3 стрелки и задний фон (прозрачность). Из-за возможности поместить все элементы в один файл SVG, файл покажет часы. Это намного удобнее, чем редактировать 5 различных файлов когда они должны находится друг над другом, а также это улучшает производительность при разборе SVG файла и чтения его с диска.  
  
In either mode, {{class|Plasma::Svg}} can be used to draw a subset of the SVG file by passing it an element id that appears in the SVG document. As a good example, if you open the clock.svg file that ships with the default theme, you will see that it has a background, 3 handles (hour, minute and seconds) and a foreground (the glass). Due to the ability to put all the elements in one file the SVG file shows a clock. This is much nicer for artists compared to editing 5 separate files that they have to imagine on top of each other, and much nicer for performance as only one SVG renderer and one file read from disk is necessary.
+
==== Метод setBackgroundHints(DefaultBackground) ====
 +
Поскольку рисование фона является общей функцией есть быстрый и простой способ отрисовать его. При добавлении <tt>setBackgroundHints(DefaultBackground)</tt> в ваш код, стандартный фон Plasma будет рисоваться позади вашего мини-приложения. Это не только экономит Ваше время и количество кода, но и создает более последовательное представление для пользователя.
  
==== setBackgroundHints(DefaultBackground) ====
+
==== Метод init() ====
Since drawing a background is a common function there is fast and easier way of doing it. By adding <tt>setBackgroundHints(DefaultBackground)</tt> to the code, the default Plasma background gets drawn behind your plasmoid. This not only saves you time and code, but creates a more consistent presentation for the user.
+
В конструкторе вы говорите плазме только о фоне приложения и конфигурационном файле, если такие имеются. Вы также можете выставлять размеры мини-приложения в конструкторе. После этого плазма позаботится об изменении размеров и вы можете не беспокоиться по этому поводу. В методе <tt>init()</tt> вы можете инициализировать всё что пожелаете, например считывание информации из конфигурационного файла.
  
==== The init() method ====
+
==== Метод hasFailedToLaunch() ====
In the constructor you only tell plasma about the background and configuration file if any. You also set the start size in the constructor. After that, plasma will take care of any resizing and you never have to worry about size. In the <tt>init()</tt> method you initialize everything that needs to be initialize such as reading config data for example.
 
  
==== hasFailedToLaunch() ====
+
Если в некоторых случаях мини-приложение не может быть запущено (например не загружены некоторые библиотеки, отсутствуют драйвера для некоторого оборудования и т.д.) этот метод вернёт значение true. Использование этого метода даст вашему приложению способность выполнить некоторую очистку перед завершением.
If for some reason, the applet fails to get up on its feet (the library couldn't be loaded, necessary hardware support wasn't found, etc..) this method returns true. Using this function gives your application a chance to cleanup before quiting.  
 
  
==== setFailedToLaunch(bool, QString) ====
+
==== Метод setFailedToLaunch(bool, QString) ====
When your application is unable to start, this function allows you to inform Plasma and give an optional reason why. Plasma will then draw a standardized error interface to inform the user of the situation and your applet will not be called upon to do any drawing on its own from that point forward. If your plasmoid becomes more complex and depends on multiple factors this is the nicest way to cleanup.
+
Если ваше приложение не в состоянии запуститься, то вызвав данный метод вы сможете уведомить плазму как и почему это произошло. После этого плазма нарисует стандартный интерфейс с сообщением об ошибке для пользователя и ваше мини-приложение не будет выполнять то, для чего он был предназначен. Если ваше мини-приложение сложное и зависит от многих внешних факторов, то это лучший способ проведения очистки.
  
==== dataUpdated ====
+
==== Функция dataUpdated ====
If you would connect to any of plasma's data-engines you would have to implement a function called dataUpdated in your plasmoid. The latter is called if the data-engine sends you data, i.e. your plasmoid should recalculate its contents.
+
Если вы хотите обрабатывать какие-либо данные от plasma's data-engines, вам следует реализовать функцию dataUpdated в вашем мини-приложении. Последняя вызывается, если data-engine посылает вам данные, т.е. ваше мини-приложение должно заново рассчитать свое содержимое.
  
==== Determine the applet size and geometry: geometry() and contentsRect() ====
+
==== Определение формы и размера апплета: функции geometry() и contentsRect() ====
If you need to know, in your applet code, what the applet size and geometry is, call contentsRect() and contentsRect().size(). Avoid calling geometry() and size() because they don't take into account the margin's size set by the applets default background.
+
Если вы хотите узнать в коде апплета, какого размера апплет и какую он имеет форму,  
Also avoid using absolute numbers to position items in the applet like QPoint(0, 0) to indicate the top-left point of your applet, instead use contentsRect().topLeft().
+
вызовите contentsRect() и contentsRect().size(). Избегайте вызовов функций geometry() и size(), потому что они не берут в расчет размер поля фона по умолчанию устанавливаемый апплетам. Также избегайте использование абсолютных значений для позиционирования содержимого апплета, например таких как QPoint(0, 0) для показа верхней левой точки вашего апплета, вместо этого используйте contentsRect().topLeft().
  
=== Building it all, the CMakeLists.txt ===
+
=== Построение, файл CMakeLists.txt ===
Finally, to put everything together you need to build everything. To tell cmake what needs to go where there is the CMakeLists.txt file.  
+
Наконец, для связывания всего вместе, вам нужно все это собрать. Для указания cmake что нужно делать, укажем ему на CMakeLists.txt файл.
  
For more details on CMake please read [[Development/Tutorials/CMake]]
+
За деталями работы CMake, пожалуйста, обращайтесь к документации [[Development/Tutorials/CMake]]
  
<code bash>
+
<syntaxhighlight lang="bash">
# Project Needs a name ofcourse
+
# Проекту конечно же нужно имя
 
project(plasma-tutorial1)
 
project(plasma-tutorial1)
  
# Find the required Libaries
+
# Поиск требуемых библиотек
 
find_package(KDE4 REQUIRED)
 
find_package(KDE4 REQUIRED)
 
include(KDE4Defaults)
 
include(KDE4Defaults)
find_package(Plasma REQUIRED)
 
  
 
add_definitions (${QT_DEFINITIONS} ${KDE4_DEFINITIONS})
 
add_definitions (${QT_DEFINITIONS} ${KDE4_DEFINITIONS})
Line 221: Line 223:
 
   )
 
   )
  
# We add our source code here
+
# Тут мы добавляем наш исходный код
 
set(tutorial1_SRCS plasma-tutorial1.cpp)
 
set(tutorial1_SRCS plasma-tutorial1.cpp)
  
# Now make sure all files get to the right place
+
# Убедитесь, что все пути к файлам верны
 
kde4_add_plugin(plasma_applet_tutorial1 ${tutorial1_SRCS})
 
kde4_add_plugin(plasma_applet_tutorial1 ${tutorial1_SRCS})
 
target_link_libraries(plasma_applet_tutorial1  
 
target_link_libraries(plasma_applet_tutorial1  
                       ${PLASMA_LIBS} ${KDE4_KDEUI_LIBS})
+
                       ${KDE4_PLASMA_LIBS} ${KDE4_KDEUI_LIBS})
  
 
install(TARGETS plasma_applet_tutorial1
 
install(TARGETS plasma_applet_tutorial1
Line 234: Line 236:
 
install(FILES plasma-applet-tutorial1.desktop
 
install(FILES plasma-applet-tutorial1.desktop
 
         DESTINATION ${SERVICES_INSTALL_DIR})
 
         DESTINATION ${SERVICES_INSTALL_DIR})
</code>
+
</syntaxhighlight>
  
== Testing the Applet ==
+
== Тестирование апплета ==
If your current Development Environment differs from the Test Installation, you have to run cmake with -DCMAKE_INSTALL_PREFIX=/usr/lib/kde4/ (replace with your $KDEDIR). Then run make. If succesfull the applet can be installed by running sudo make install
+
Если ваша текущая среда разработки отличается от тестовой установки, вы должны запускать cmake с параметром -DCMAKE_INSTALL_PREFIX=/usr/lib/kde4/ (замените вашей переменной $KDEDIR). Затем запустите make. Если результат успешен, апплет может быть установлен запуском команды sudo make install
or
+
или
 
* cp ./lib/plasma_applet_tutorial1.so $KDEDIR/lib  
 
* cp ./lib/plasma_applet_tutorial1.so $KDEDIR/lib  
 
* cp ./plasma-applet-tutorial1.desktop $KDEDIR/share/kde4/services/
 
* cp ./plasma-applet-tutorial1.desktop $KDEDIR/share/kde4/services/
  
and run kbuildsycoca4 (so that KDE apps will know about the new desktop files).
+
и запуском kbuildsycoca4 (так приложения KDE узнают о новых файлах *.desctop)
In order to test your Applet you can use the '''plasmoidviewer''' program:
+
Для тестового запуска вашего апплета вы можете использовать программу '''plasmoidviewer''' набрав:
<code bash>
+
<syntaxhighlight lang="bash">
 
plasmoidviewer applet_name
 
plasmoidviewer applet_name
</code>
+
</syntaxhighlight>
  
Where '''applet_name''' is the value specified into .desktop for the '''X-KDE-PluginInfo-Name''' key.
+
Где '''applet_name''' значение, указанное в .desktop для ключа '''X-KDE-PluginInfo-Name'''.
  
Otherwise you can restart plasma, so the Applet will be displayed in the Applet Browser:  
+
Или вы можете перезапустить плазму, так что апплет будет отображен в окне выбора апплетов:
<code bash>
+
<syntaxhighlight lang="bash">
 
kbuildsycoca4
 
kbuildsycoca4
 
kquitapp plasma
 
kquitapp plasma
 
plasma  
 
plasma  
</code>
+
</syntaxhighlight>
  
If that doesn't work you will have to restart your KDE session by logging out and back in.
+
Если так не работает, вам следует перезапустить вашу KDE сессию путем выхода из системы и входа снова.

Latest revision as of 23:27, 11 September 2014


Creating your first Plasmoid
Tutorial Series   Plasma Tutorial
Previous   C++, Qt, KDE4 development environment
What's Next  
Further Reading   CMake

Предисловие

Данное руководство требует для удачной сборки kde 4.2. В данном руководстве мы создадим простое мини-приложение. Чтобы сохранить простоту мы создадим статическое мини-приложение с использованием следующих компонентов:

  • SVG рисунок
  • Иконка
  • Какой-либо простой текст
Creatingyourfirstplasmoid1.png

Код мини-приложения

Файл .desktop

Каждое мини-приложение должно иметь в своём составе .desktop файл для указания плазме как и под каким именем его запускать.

plasma-applet-tutorial1.desktop

[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=[email protected]
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

Наиболее важными являются пункты X-KDE-Library и X-KDE-PluginInfo-Name, они являются "клеем" между вашим классом и плазмой, без них ничего не заработает. Для X-KDE-PluginInfo-Category, см. PIG.

Файл заголовка

Это пример файла заголовка. Комментарии в код добавлены для ясности.

plasma-tutorial1.h

// Здесь мы избегаем загрузки заголовков несколько раз
#ifndef Tutorial1_HEADER
#define Tutorial1_HEADER
// Нам необходимо загрузить заголовок Applet плазмы
#include <KIcon>
 
#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

Метод QRectF boundingRect()

Функция boundingRect() сообщает плазме актуальные размеры мини-приложения. Это важно, так как мы должны знать сколько места занимаем на экране.

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

#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"

Класс Plasma/Svg

Как вы могли увидеть из кода, мы использовали Plasma::Svg объект, достаточно важный, чтобы отметить его здесь.

Сперва мы выставляем относительный путь к файлу widgets/background для Plasma::Svg который используется в Plasma::Theme для нахождения SVG данных. Пока Plasma::Svg не поддерживает загрузку произвольных файлов с полными путями, используйте относительные пути из темы как можно чаще. так как это позволяет отдельным плазмоидам выглядеть одинаково, используя определённый в данный момент стиль Plasma. Список доступных картинок можно найти на Plasma Theme page.

В любом режиме, Plasma::Svg может использоваться для разбора состовляющего SVG файлов, извлекая из них элементы по идентификаторам, которые содержатся в документе SVG. Хороший пример: если вы откроете файл clock.svg то он будет открыт с темой по умолчанию, вы должны будете увидеть фон, 3 стрелки и задний фон (прозрачность). Из-за возможности поместить все элементы в один файл SVG, файл покажет часы. Это намного удобнее, чем редактировать 5 различных файлов когда они должны находится друг над другом, а также это улучшает производительность при разборе SVG файла и чтения его с диска.

Метод setBackgroundHints(DefaultBackground)

Поскольку рисование фона является общей функцией есть быстрый и простой способ отрисовать его. При добавлении setBackgroundHints(DefaultBackground) в ваш код, стандартный фон Plasma будет рисоваться позади вашего мини-приложения. Это не только экономит Ваше время и количество кода, но и создает более последовательное представление для пользователя.

Метод init()

В конструкторе вы говорите плазме только о фоне приложения и конфигурационном файле, если такие имеются. Вы также можете выставлять размеры мини-приложения в конструкторе. После этого плазма позаботится об изменении размеров и вы можете не беспокоиться по этому поводу. В методе init() вы можете инициализировать всё что пожелаете, например считывание информации из конфигурационного файла.

Метод 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

# Проекту конечно же нужно имя
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})

Тестирование апплета

Если ваша текущая среда разработки отличается от тестовой установки, вы должны запускать 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 узнают о новых файлах *.desctop) Для тестового запуска вашего апплета вы можете использовать программу plasmoidviewer набрав:

plasmoidviewer applet_name

Где applet_name значение, указанное в .desktop для ключа X-KDE-PluginInfo-Name.

Или вы можете перезапустить плазму, так что апплет будет отображен в окне выбора апплетов:

kbuildsycoca4
kquitapp plasma
plasma

Если так не работает, вам следует перезапустить вашу KDE сессию путем выхода из системы и входа снова.


This page was last edited on 11 September 2014, at 23:27. Content is available under Creative Commons License SA 4.0 unless otherwise noted.