Development/Tutorials/Using KActions (ru)

    From KDE TechBase
    The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.


    Использование 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

    #include <KApplication>
    #include <KAboutData>
    #include <KCmdLineArgs>
    
    #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

    #ifndef MAINWINDOW_H
    #define MAINWINDOW_H
    
    #include <KXmlGuiWindow>
    #include <KTextEdit>
    
    class MainWindow : public KXmlGuiWindow
    {
      public:
        MainWindow(QWidget *parent=0);
    	
      private:
        KTextEdit* textArea;
        void setupActions();
    };
    
    #endif
    

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

    mainwindow.cpp

    #include "mainwindow.h"
    
    #include <KApplication>
    #include <KAction>
    #include <KLocale>
    #include <KActionCollection>
    #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:

    #include <KAction>
    ...
    KAction* clearAction = new KAction(this);
    

    Этот код создаёт действие clearAction.

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

    Текст

    Теперь, когда объект KAction создан, можно приступить к его настройке. Сначала, мы задаём текст, отображаемый в меню и под значком KAction на панели инструментов.

    clearAction->setText(i18n("Clear"));
    

    Если планируется перевод интерфейса, то следует использовать функцию i18n для обработки текста (более подробную информацию можно получить в уроке по i18n


    Значок

    В случае отображения действия на панели неплохо использовать значок, характеризующий это действие. Следующий код с помощью функции setIcon() устанавливает стандартный значок KDE document-new

    clearAction->setIcon(KIcon("document-new"));
    
    Комбинация клавиш

    Связать комбинацию клавиш с нашим действием совершенно просто:

    clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
    

    Данный фрагмент кода связывает с нашим действием комбинацию клавиш Ctrl+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, в KAction лишь добавлены специфические для KDE особенности.

    KStandardAction

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

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

    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>&amp;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