Development/Tutorials/Using KActions (ru)

    From KDE TechBase


    Development/Tutorials/Using_KActions


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