Development/Tutorials/Using KActions (ru)

Development/Tutorials/Using_KActions

Languages: عربي | Asturianu | Català | Česky | Kaszëbsczi | Dansk | Deutsch | English | Esperanto | Español | Eesti | فارسی | Suomi | Français | Galego | Italiano | 日本語 | 한국어 | Norwegian | Polski | Português Brasileiro | Română | Русский | Svenska | Slovenčina | Slovenščina | српски | Türkçe | Tiếng Việt | Українська | 简体中文 | 繁體中文

Использование KActions и XmlGui

Tutorial Series	Beginner Tutorial
Previous	Урок 2 - KXmlGuiWindow, Basic XML knowledge
What's Next	TODO (milliams)
Further Reading	None

Введение

В данном уроке представлена базовая информация по работе с элементами actions (действиями). Использование действий является наиболее общим способом создания интерактивности программы.

Например, требуется очищать текстовое поле нажатием кнопки на панели инструментов, клавиши быстрого выбора или при использовании какого-либо пункта меню File. Это можно обеспечить при помощи одного KAction (действия).

KAction

Объект класса KAction хранит информацию о значке и клавише быстрого вызова, связанных с определённым действием. Действие может быть соединено со слотом, обрабатывающем его.

Создание действий

Для создания действия в .cpp необходимо наличие #include <KAction>

Создание объекта KAction

Мы создадим действие, очищающее текстовое поле (см. Урок 2). KAction создаётся в несколько шагов. Первый - создание объекта KAction: KAction* clearAction = new KAction(this); Этот код создаёт действие clearAction.

Текст

Теперь, когда объект KAction создан, можно приступить к его настройке. Сначала, мы задаём текст, отображаемый в меню и под значком на панели инструментов. clearAction->setText(i18n("Clear")); Если планируется перевод интерфейса, то следует использовать функцию i18n для обработки текста.

Значок

При добавлении действий на панель инструментов можно задать значок, характеризующий выполняемое действие. Для этого следует просто вызвать функцию setIcon(), например: clearAction->setIcon(KIcon("filenew")); В данном примере с действием связывается стандартный значок KDE filenew.

Клавиша быстрого вызова

Также с действием можно связать клавишу быстрого вызова. Например, следующий фрагмент кода связывает с нашим действием комбинацию клавиш Ctrl+W: clearAction->setShortcut(Qt::CTRL+Qt::Key_W);

Добавдение в набор (Collection)

Чтобы сделать наше действие доступным системе XmlGui, следует добавить его в набор действий (action collection) приложения c помощью actionCollection() следующим образом: actionCollection()->addAction("clear", clearAction); В данном примере мы добавляем clearAction в коллекцию, задав имя clear. Это имя используется системой XmlGui.

Соединение действий

Теперь, когда действие полностью настроено, можно соединить его с действием clear(), принадлежащим KTextArea. connect( clearAction, SIGNAL( triggered(bool) ),

        textArea, SLOT( clear() ) );

Это абсолютно идентично использованию QAction.

KStandardAction

Для часто используемых в KDE приложениях действий, таких, как quit', 'save', и 'load', существуют готовые KActions, доступные через класс KStandardAction.

Их очень легко использовать. После включения заголовочного файла <KStandardAction> в ваш код, следует просто соединить их с функциями-обработчиками и добавить в соответствующую коллекцию (KActionCollection). Например, следующий код

KStandardAction::quit(kapp, SLOT(quit()), actionCollection()); создаст действие с соответствующим значком, текстом, клавишей быстрого вызова и даже добавит в меню File.

The Code

mainwindow.h

1. ifndef MAINWINDOW_H
2. define MAINWINDOW_H

1. include <KXmlGuiWindow>
2. include <KTextEdit>

class MainWindow : public KXmlGuiWindow { public:

   MainWindow(QWidget *parent=0);

private:

   KTextEdit* textArea;
   void setupActions();

};

1. endif

mainwindow.cpp

1. include "mainwindow.h"

1. include <KApplication>
2. include <KAction>
3. include <KLocale>
4. include <KActionCollection>
5. include <KStandardAction>

MainWindow::MainWindow(QWidget *parent) : KXmlGuiWindow(parent) {

 textArea = new KTextEdit;
 setCentralWidget(textArea);

 setupActions();

}

void MainWindow::setupActions() {

 KAction* clearAction = new KAction(this);
 clearAction->setText(i18n("Clear"));
 clearAction->setIcon(KIcon("filenew"));
 clearAction->setShortcut(Qt::CTRL+Qt::Key_W);
 actionCollection()->addAction("clear", clearAction);
 connect(clearAction, SIGNAL(triggered(bool)),
         textArea, SLOT(clear()));

 KStandardAction::quit(kapp, SLOT(quit()),
                       actionCollection());

 setupGUI();

}

main.cpp

1. include <KApplication>
2. include <KAboutData>
3. include <KCmdLineArgs>

1. include "mainwindow.h"

int main (int argc, char *argv[]) {

 KAboutData aboutData( "tutorial3", "tutorial3",
     ki18n("Tutorial 3"), "1.0",
     ki18n("A simple text area using KAction etc."),
     KAboutData::License_GPL,
     ki18n("Copyright (c) 2007 Developer") );
 KCmdLineArgs::init( argc, argv, &aboutData );
 KApplication app;

 MainWindow* window = new MainWindow();
 window->show();
 return app.exec();

}

Добавление действия в меню и на панель управления

На данном этапе действие "Clear" только создано: оно не будет отображено в меню или на панели управления. Чтобы задать, куда следует добавить действия (и позволить пользователю программы перемещать их), мы использем KDE-технологию XmlGui.

XmlGui

Note

В последующих версиях KDE4, XmlGui может быть заменена на систему liveui. Но сейчас XmlGui является единственным верным способом настройки UI.

При вызове функции setupGUI() в нашем классе (производном) KXmlGuiWindow, осуществляется обращение к системе XmlGui, которая читатет XML файл с описанием интерфейса (мы рассмотрим его позже) и создаёт кнопки и меню.

Очевидно, что XmlGui требуется знать, какой файл является файлом описания, т.е. его имя и расположение. По установленному правилу имя файла должно быть appnameui.rc (где appname является именем, заданным в KAboutData), таким образом, в нашем примере файл должен быть назван tutorial3ui.rc. Его расположение определяется CMake.

Создание файла appnameui.rc

В связи с тем, что UI описывается на языке XML, порядок описания должен придерживаться строгих правил. В данном уроке мы не станем подробно рассказывать обо всех правилах, но для получения большей информации рекомендуется посмотреть страницу _с_подробным_описанием_XML (когда у нас будет статья с полным описанием XmlGui (или, возможно, liveui, если эта система будет реализована :)) здесь будет соответсвующая ссылка).

tutorial3ui.rc

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE kpartgui SYSTEM "kpartgui.dtd"> <gui name="tutorial3" version="1">

 <ToolBar name="mainToolBar" >
   <text>Main Toolbar</text>
   <Action name="clear" />
 </ToolBar>
 <MenuBar>
   <Menu name="file" >
     <text>&File</text>
     <Action name="clear" />
   </Menu>
 </MenuBar>

</gui>

Тэг <Toolbar> служит для описания панели инструментов (toolbar). Панель инструментов - это панель со значками, находящаяся в верхней части окна. В данном примере она получила уникальное имя mainToolBar и с помощью <text> видимое пользователю имя Main Toolbar, также мы добавляем на панель наше действие, используя тэг <Action>. Значение, заданное в параметре name, должно быть идентичным строке, переданной функции addAction() в нашем С++ коде.

Теперь можно добавить действие в меню. Для этого мы используем тэг <MenuBar>, в остальном всё абсолютно идентично выше описаному.

При изменении .rc файла следует изменять атрибут 'version', чтобы обновить кэш.

CMake

Из-за того, что был использован XmlGui, необходимо копировать tutorial3ui.rc туда, где KDE сможет его найти. Это означает, что необходимо куда-нибудь установить наш проект.

CMakeLists.txt

project(tutorial3)

find_package(KDE4 REQUIRED) include_directories( ${KDE4_INCLUDES} )

set(tutorial3_SRCS

 main.cpp
 mainwindow.cpp

)

kde4_add_executable(tutorial3 ${tutorial3_SRCS})

target_link_libraries(tutorial3 ${KDE4_KDEUI_LIBS})

install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR}) install( FILES tutorial3ui.rc

        DESTINATION  ${DATA_INSTALL_DIR}/tutorial3 )

Данный файл почти идентичен файлу со второго урока, но имеет две дополнительные строки. Они как раз и описывают, куда должны быть установлены файлы. Сначала в BIN_INSTALL_DIR будет установлен tutorial3 (бинарный файл, target), затем в каталог приложения (data directory) - файл tutorial3ui.rc, описывающий пользовательский интерфейс.

Сборка, установка и запуск

Если у вас нет доступа к каталогу KDE4, то приложение можно установить в папку домашнего каталога.

Чтобы указать CMake, куда следует установить программу, нужно использовать переменную DCMAKE_INSTALL_PREFIX. Таким образом, чтобы установить программу в каталог KDE, выполните:

cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
make install
tutorial3

Однако, если вы хотите установить программу куда-либо, чтобы его проверить (было бы глупо устанавливать приложения с этих уроков в каталог KDE), следует напечатать:

cmake . -DCMAKE_INSTALL_PREFIX=/home/kde-devel/kdetmp

это создаст KDE-подобную структуру каталогов в ~/kdetmp и установит исполняемый файл в /home/kde-devel/kdetmp/bin/tutorial3.

Продолжим изучение

TODO