Development/Tutorials/Using KActions (ru)

    From KDE TechBase
    Revision as of 20:31, 29 June 2011 by Neverendingo (talk | contribs) (Text replace - "<code cppqt>" to "<syntaxhighlight lang="cpp-qt">")


    Development/Tutorials/Using_KActions


    Использование KActions и XMLGUI
    Tutorial Series   Beginner Tutorial
    Previous   Урок 2 - KXmlGuiWindow, Basic XML knowledge
    What's Next   Урок 4 - Сохранение и загрузка
    Further Reading   None

    Введение

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

    Например, если нужно, чтобы пользователь приложения с урока 2 мог очищать текстовое поле нажатием кнопки на панели инстрментов, комбинацией клавиш или выбрав некоторый пункт меню, то всё это можно реализовать с помощью одного класса KAction.

    KAction

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

    Листинг кода

    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();
    

    } Небольшие изменения конструктора KAboutData файла main.cpp. Теперь он будет показывать, что приложение принадлежит уроку 3.

    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

    Добавьте вызов функции void setupActions(), которая будет выполнять настройку KActions.

    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("document-new"));
     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();
    

    }


    Объяснение

    Приложение основано на исходном коде, приведённом в Уроке 2. Большинство изменений касаются mainwindow.cpp. Конструктор MainWindow теперь вместо setupGUI() вызывает setupActions(). KAction создаётся и настраивается в функции setupActions() до вызова setupGUI().


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

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

    Мы создадим действие, которое очищающает текстовое поле (см. Урок 2). KAction создаётся в несколько шагов. Первый - включение заголовочного файла и создание объекта KAction: <syntaxhighlight lang="cpp-qt">

    1. include <KAction>

    ... KAction* clearAction = new KAction(this); Этот код создаёт действие clearAction.

    Настройка свойств KAction

    Текст

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


    Значок

    В случае отображения действия на панели неплохо использовать значок, характеризующий это действие. Следующий код с помощью функции setIcon() устанавливает стандартный значок KDE document-new <syntaxhighlight lang="cpp-qt">clearAction->setIcon(KIcon("document-new"));

    Комбинация клавиш

    Связать комбинацию клавиш с нашим действием совершенно просто: <syntaxhighlight lang="cpp-qt">clearAction->setShortcut(Qt::CTRL + Qt::Key_W); Данный фрагмент кода связывает с нашим действием комбинацию клавиш Ctrl+W:


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

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


    Соединение действия с обработчиком

    Теперь, когда параметры внешнего вида действия определены, можно связать его с методом clear() объекта KTextArea. <syntaxhighlight lang="cpp-qt"> connect( clearAction, SIGNAL( triggered(bool) ),

            textArea, SLOT( clear() ) );
    

    Интерфейс класса аналогичен QAction, в KAction лишь добавлены специфические для KDE особенности.

    KStandardAction

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

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

    <syntaxhighlight lang="cpp-qt">KStandardAction::quit(kapp, SLOT(quit()), actionCollection()); создаст действие с соответствующим значком, текстом, клавишей быстрого вызова и даже добавит пункт в меню File.


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

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

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


    XMLGUI

    При вызове функции 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"?> <gui name="tutorial3"

        version="1"
        xmlns="http://www.kde.org/standards/kxmlgui/1.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0
                            http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >
    
     <MenuBar>
       <Menu name="file" >
         <text>&File</text>
         <Action name="clear" />
       </Menu>
     </MenuBar>
    
     <ToolBar name="mainToolBar" >
       <text>Main Toolbar</text>
       <Action name="clear" />
       <ActionList name="dynamicActionlist" />
     </ToolBar>
    

    </gui>

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

    Теперь можно добавить действие в меню. Для этого мы используем тэг <MenuBar>, в остальном всё абсолютно идентично выше описаному. Заметьте, что таким же способом можно динамически добавлять список действий, используя тэг <ActionList>. Для получения более подробной информации обратитесь к документации по методу plugActionList() класса KXMLGUIClient.

    При изменении .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