Home Forums Wiki Doc Install Extras Screenshots Source Code Projects Blog Users Groups Register
Glx-Dock / Cairo-Dock Wiki Создание апплета
The latest stable release is the *3.4.0* : How to install it here.
Note: We just switched from BZR to Git on Github! (only to host the code and your future pull requests)
History View code

Glx-Dock / Cairo-Dock

Home

History

Language

en English

fr Français

ru Russian

Support Us

Flattr this

Cairo-Dockon

Создание апплета

Начиная с версии Cairo-Dock 2.1.0 вы можете писать апплеты не только на языке C.
Обратитесь к разделу Управление панелью, с помощью DBus


Доступно полное руководство для разработчиков

Вы можете найти его здесь: http://doc.glx-dock.org/


В Cairo-dock присутствует фреймворк предназначенный для быстрого написания стандартных апплетов.
Давайте посмотрим, как он работает.

Прежде всего, мы можем сгенерировать функциональный апплет с помощью скрипта generate-new-applet.sh, расположенного в каталоге исходников "plug-ins"
Запустите его, будет немного вопросов, после завершения перейдите в каталог готового апплета и введите sudo make install. Готово! Перезапустите панель и вы увидите
ваш новый апплет в панели настроек. Вы даже можете его активировать, он должен появиться на главной панели.

Теперь нам осталось ввести хоть какой-нибудь код.

Прежде чем идти дальше, попробуйте структурировать ваш будущий апплет (давайте назовём его "truc"):

Структура апплета

Дерево исходных кодов
Дерево исходных кодов имеет стандартный вид и вы можете скопировать его из любого другого апплета:

truc ---> configure.ac, Makefile.am
+--> src -> applet-init.c/h, applet-config.c/h, applet-notifications.c/h, *.c/h
+--> data -> truc.conf.in, preview, readme.in, *
+--> po -> Makefile.in.in, LINGUAS, POTFILES.in, *.po


Имена файлов могут отличаться, но соблюдение подобной иерархии,позволит легко ориентировать по любым, даже неизвестным вам апплетам.

Каталог с исходными кодами
В./src, мы имеем:
- applet-init.c: содержит функции для инициализации, остановки и перезапуска апплета.
- applet-config.c: содержит функции для загрузки конфига, его сброса и сброса данных.
- applet-notifications.c: содержит функции, которые вызываются когда апплет получает уведомление от панели о каком-то произошедшем событии (щелчок, перенос и т.д.)
- *.c: всё остальное, что может понадобиться (подключение к серверу, функции отрисовки, вычисления и т.д.) Хорошим тоном является разнесение функции по разным файлам.

Каталог данных
В --./data-- мы имеем:
- preview: изображение (png или jpg), дающее первоначальное представление об апплете, 200x200 пикселей. Оно будет показываться в панели настроек Cairo-Dock.
- readme.in: файл с кратким описанием апплета (он тоже будет показываться в панели настроек).
- truc.conf.in: конфиг апплета, который содержит все параметры, которые позволено изменять пользователю. Позже рассмотрим, как его использовать.
- icon.png: значок вашего апплета, как он будет показывать в панели настроек. Часто используется и для отображения на самой панели.

Каталог переводов
В ./po мы имеем:
- Makefile.in.in: не будемзаострять внимание на этом файле.
- LINGUAS: список доступных языков.
- POTFILES.in: список файлов в которых находятся строки для перевода.
- *.po: файл содержит перевод каждого сообщения.

Структура дерева установки
Структура дерева установки очень проста:
- содержимое каталога "data" будет скопировано в /usr/share/cairo-dock/plug-ins/truc
- сам плагин в /usr/lib/cairo-dock/libcd-truc.so
- файлы переводов пойдут в /usr/share/locale/$lang/LC_MESSAGES/cd-truc.mo, где $lang = ru, en, ...

Файлы компиляции
Не забудьте определить зависимости от других библиотек, если имеются, в файле configure.ac, согласно версии вашего апплета. Кроме того, укажите файлы, необходимые для установки в Makefile.am.

Ну что ж, перейдём к серъёзным вещам!

Использование фреймворка апплета

Переменные
Апплет имеет структуру CairoDockModuleInstance. Доступ к ней через переменную myApplet.
Апплет имеет Icon, переменная myIcon.
Значок находится внутри CairoContainer, ваш в myContainer.
Этим контейнером также может быть CairoDock (ваш myDock) или CairoDesklet (ваш myDesklet). В первом случае myDock == myContainer и myDesklet == NULL и наоборот, поэтому здесь они просто для удобства пользования.
Апплет имеет несколько параметров, который берутся из конфига, они сугрппированы в структуру AppletConfig. Ваша myConfig.
Апплет имеет некоторые данные, которые подгружаются при запуске, они сгруппированы в структуру AppletData. Ваша myData.
И последне, значок ассоциирован с cairo_t контекстом отрисовки, ваш myDrawContext. Обратите внимание, что если апплет в режиме Десклета, контекст доступен после установки рендера десклета, поэтому нужно это сделать прежде всего.

Единичный и монжественный запуск
В Cairo-Dock апплеты могут быть запущены несколько раз или только один. К примеру, у вас может быть несколько копий Часов, показывающих время в разных странах.
Чтобы сделать апплет многократным, нужно добавить следующую строку в файл src/Makefile.am :
-DCD_APPLET_MULTI_INSTANCE="1"
В случае однократного апплета, переменная myApplet доступна отовсюду, как глобальная переменная. В случае многократного апплета, она доступна только при init и reload, и предоставляется для задания функций, как входных параметров (можно сделать её глобальонй переменной)

Уведомления
В Cairo-Dock апплеты взаимодействуют с панелью с помощью уведомлений. Когда что-нибудь происходит (пользователь щелкает где-нибудь, перетаскивает какие-то данные на панель и т.д.), панель посылает уведомление о событии. Все, кто зарегистрирован на принятие таких уведомлений, получают его
Чтобы зарегистрироваться на получение уведомлений, нужно задать функцию (или callback), которая будет вызываться при возникновении уведомления.
Имеется несколько макросов для наиболее частых уведомлений (правый/левый/средний/двойной щелчок). Будьте осторожны в соблюдении формата описания функции, если не используете макросы, этот формат будет описан в соответствующем менеджере.

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

Когда апплет останавливается (пользователь удаляет его), то вам потребуется высвободить все назначенные ресурсы, чтобы апплет отдал всю используемую память и прекратил любые существующие таймеры или уведомления.
Высвобождение данных задается в функции reset_data, которая вызывается панелью, поэтому стоит помещать сюда весь код, который будет высвобождать параметры myData. Остальное будет зависеть от функции stop.

Перезапуск возникает в 2 случаях:
– в случае изменения размера десклета пользователем или при изменении значений в панели настроек
– в случае изменений значений в настройках самого апплета или прикрепления\открепления апплета.
Макрос CD_APPLET_MY_CONFIG_HAS_CHANGED сообщает какой случай происходит. В другом виде, myConfig уже перезапущен, поэтому нет нужды об этом заботиться.

Макрос
Макросы предназначены для написания ясного кода и уменьшения его размеров. Они оттеняют сложность некоторых функций и предотвращают поломки API, поэтому следует их использовать везде, где это возможно.
Все они определены в cairo-dock-applet-facility.h и задокументированы (для лучшего понимания вы можете сгенерировать html документ с помощью doxygen).

Конфиг
При изменении настроек панели или апплета, панель динамически пересоздаётся под эти изменения. Conf файлы это ключевые файлы, сгруппированные по группам.
Каждый может генерировать виджеты (spinbutton, ввод текста и т.д.)
Каждый ключ имеет комментарий (строка начинающаяся с '#'), этот комментарий будет отображён рядом с виджетом.
Для понимания какой это виджет, используется первая буква комментария. Полный список находится в src/cairo-dock-gui-factory.c или в качестве примера в data/cairo-dock.conf.in.
Система позволяет не заботиться о панели настроек: нет необходимости в её постройке, нет необходимости в получении значений, которые задаёт пользователь!


Glx-Dock / Cairo-Dock Wiki Создание апплета Top

Online users :

Powered by ElementSpeak © 2007 Adrien Pilleboue, 2009-2013 Matthieu Baerts.
Dock based on CSS Dock Menu (Ndesign) with jQuery. Icons by zgegball
Cairo-Dock is a free software under GNU-GPL3 licence. First stable version created by Fabounet.
Many thanks to TuxFamily for the web Hosting and Mav for the domain name.