Difference between revisions of "Development/Tutorials/Using KActions (ru)"

Jump to: navigation, search
m (Update)
(Half update (--> XMLGUI section).)
Line 5: Line 5:
 
series=Beginner Tutorial|
 
series=Beginner Tutorial|
  
name=Использование KActions и XmlGui|
+
name=Использование KActions и XMLGUI|
  
 
pre=[[Development/Tutorials/Using_KXmlGuiWindow_(ru)|Урок 2 - KXmlGuiWindow]], Basic XML knowledge|
 
pre=[[Development/Tutorials/Using_KXmlGuiWindow_(ru)|Урок 2 - KXmlGuiWindow]], Basic XML knowledge|
  
next=TODO (milliams)|  
+
next=[[Development/Tutorials/Saving_and_loading|Tutorial 4 - Saving and loading]]|
  
 
reading=None
 
reading=None
Line 17: Line 17:
 
В данном уроке представлена базовая информация по работе с элементами actions (действиями). Действия -- центральная концепция при реализации интерактивности программы.
 
В данном уроке представлена базовая информация по работе с элементами actions (действиями). Действия -- центральная концепция при реализации интерактивности программы.
  
Например, нужно чтобы по нажатию кнопки на панели инструментов, комбинации клавиш или по выбору некоторого пункта меню очищалось текстовое поле. Всё это можно сделать с помощью одного действия {{class|KAction}}.
+
Например, если нужно, чтобы пользователь приложения [[Development/Tutorials/Using_KXmlGuiWindow| с урока 2 ]] мог очищать текстовое поле нажатием кнопки на панели инстрментов, комбинацией клавиш или выбрав некоторый пункт меню, то всё это можно реализовать с помощью одного класса {{class|KAction}}.
 
+
  
 
[[image:introtokdetutorial3.png|frame|center]]
 
[[image:introtokdetutorial3.png|frame|center]]
Line 25: Line 24:
 
Объект класса {{class|KAction}} хранит информацию о значке и клавише быстрого вызова, связанных с определённым действием. Действие может быть соединено со [http://doc.trolltech.com/latest/signalsandslots.html слотом], обрабатывающем его.
 
Объект класса {{class|KAction}} хранит информацию о значке и клавише быстрого вызова, связанных с определённым действием. Действие может быть соединено со [http://doc.trolltech.com/latest/signalsandslots.html слотом], обрабатывающем его.
  
 +
== Листинг кода ==
  
===Создание действий===
+
===main.cpp===
 
+
<code cppqt n>
Для создания действия в <tt>.cpp</tt> необходимо наличие <tt>#include <KAction></tt>
+
#include <KApplication>
=====Создание объекта KAction=====
+
#include <KAboutData>
Мы создадим действие, очищающее текстовое поле (см. Урок 2). KAction создаётся в несколько шагов. Первый - создание объекта KAction:
+
#include <KCmdLineArgs>
<code cppqt>KAction* clearAction = new KAction(this);</code>
+
Этот код создаёт действие <tt>clearAction</tt>.
+
 
+
=====Текст=====
+
Теперь, когда объект KAction создан, можно приступить к его настройке. Сначала, мы задаём текст, отображаемый в меню и под значком на панели инструментов.
+
<code cppqt>clearAction->setText(i18n("Clear"));</code>
+
Если планируется перевод интерфейса, то следует использовать функцию i18n для обработки текста.
+
  
 +
#include "mainwindow.h"
  
=====Значок=====
+
int main (int argc, char *argv[])
 
+
{
При добавлении действий на панель инструментов можно задать значок, характеризующий выполняемое действие. Для этого следует просто вызвать функцию <tt>setIcon()</tt>, например:  
+
  KAboutData aboutData( "tutorial3", "tutorial3",
<code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
+
      ki18n("Tutorial 3"), "1.0",
В данном примере с действием связывается стандартный значок KDE <tt>document-new</tt>.
+
      ki18n("A simple text area using KAction etc."),
 
+
      KAboutData::License_GPL,
=====Комбинация клавиш=====
+
      ki18n("Copyright (c) 2007 Developer") );
 
+
  KCmdLineArgs::init( argc, argv, &aboutData );
Также, если ожидается что действие будет выполняться часто, с ним можно связать комбинацию клавиш. Например, следующий фрагмент кода связывает с нашим действием комбинацию клавиш Ctrl+W:
+
  KApplication app;
<code cppqt>clearAction->setShortcut(Qt::CTRL+Qt::Key_W);</code>
+
 
+
  MainWindow* window = new MainWindow();
=====Добавдение в набор (Collection)=====
+
  window->show();
 
+
  return app.exec();
Чтобы сделать наше действие доступным системе XmlGui, следует добавить его в ''набор действий (action collection)'' приложения c помощью <tt>actionCollection()</tt> следующим образом:
+
}
<code cppqt>
+
actionCollection()->addAction("clear", clearAction);
+
 
</code>
 
</code>
В данном примере мы добавляем <tt>clearAction</tt> в коллекцию, задав имя ''clear''. Это имя используется системой XmlGui.
+
This time, very little has changed in <tt>main.cpp</tt>, only the KAboutData constructor has been updated to show that we are now on tutorial 3.
  
 
=====Соединение сигналов и слотов=====
 
 
Теперь, когда параметры внешнего вида действия определены, можно связать его с методом tt>clear()</tt> объекта KTextArea.
 
<code cppqt>
 
connect( clearAction, SIGNAL( triggered(bool) ),
 
        textArea, SLOT( clear() ) );
 
</code>
 
Интерфейс класса аналогичен {{qt|QAction}}, в KAction лишь добавлены специфические для KDE особенности.
 
 
===KStandardAction===
 
 
Для часто используемых в KDE приложениях действий, таких, как quit, save, и load, доступны готовые объекты KAction, доступные через класс {{class|KStandardAction}}.
 
 
Их очень легко использовать. После включения заголовочного файла <tt><KStandardAction></tt> в ваш код, следует просто соединить их с функциями-обработчиками и добавить в соответствующую коллекцию (KActionCollection). Например, следующий код
 
 
<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
 
создаст действие с соответствующим значком, текстом, клавишей быстрого вызова и даже добавит пункт в меню File.
 
 
==The Code==
 
 
===mainwindow.h===
 
===mainwindow.h===
 
<code cppqt n>
 
<code cppqt n>
Line 89: Line 61:
 
class MainWindow : public KXmlGuiWindow
 
class MainWindow : public KXmlGuiWindow
 
{
 
{
public:
+
  public:
 
     MainWindow(QWidget *parent=0);
 
     MainWindow(QWidget *parent=0);
 
 
private:
+
  private:
 
     KTextEdit* textArea;
 
     KTextEdit* textArea;
 
     void setupActions();
 
     void setupActions();
Line 99: Line 71:
 
#endif
 
#endif
 
</code>
 
</code>
 +
Only a function <tt>void setupActions()</tt> has been added which will do all the work setting up the KActions.
  
 
===mainwindow.cpp===
 
===mainwindow.cpp===
Line 111: Line 84:
  
 
MainWindow::MainWindow(QWidget *parent)
 
MainWindow::MainWindow(QWidget *parent)
: KXmlGuiWindow(parent)
+
    : KXmlGuiWindow(parent)
 
{
 
{
 
   textArea = new KTextEdit;
 
   textArea = new KTextEdit;
Line 124: Line 97:
 
   clearAction->setText(i18n("Clear"));
 
   clearAction->setText(i18n("Clear"));
 
   clearAction->setIcon(KIcon("document-new"));
 
   clearAction->setIcon(KIcon("document-new"));
   clearAction->setShortcut(Qt::CTRL+Qt::Key_W);
+
   clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
 
   actionCollection()->addAction("clear", clearAction);
 
   actionCollection()->addAction("clear", clearAction);
 
   connect(clearAction, SIGNAL(triggered(bool)),
 
   connect(clearAction, SIGNAL(triggered(bool)),
Line 136: Line 109:
 
</code>
 
</code>
  
===main.cpp===
 
<code cppqt n>
 
#include <KApplication>
 
#include <KAboutData>
 
#include <KCmdLineArgs>
 
  
#include "mainwindow.h"
+
==Объяснение==
 +
Приложение основано на исходном коде, приведённом в [[Development/Tutorials/Using_KXmlGuiWindow_(ru)|Уроке 2]]. Большинство изменений касаются <tt>mainwindow.cpp</tt>. Конструктор MainWindow теперь вместо <tt>setupGUI()</tt> вызывает <tt>setupActions()</tt>. KAction создаётся и настраивается в функции <tt>setupActions()</tt> до вызова <tt>setupGUI()</tt>.
  
int main (int argc, char *argv[])
+
 
{
+
 
  KAboutData aboutData( "tutorial3", "tutorial3",
+
Для создания действия в <tt>.cpp</tt> необходимо наличие <tt>#include <KAction></tt>
      ki18n("Tutorial 3"), "1.0",
+
=====Создание объекта KAction=====
      ki18n("A simple text area using KAction etc."),
+
Мы создадим действие, которое очищающает текстовое поле [[Development/Tutorials/Using_KXmlGuiWindow_(ru)|(см. Урок 2)]]. KAction создаётся в несколько шагов. Первый - включение заголовочного файла и создание объекта KAction:
      KAboutData::License_GPL,
+
<code cppqt>
      ki18n("Copyright (c) 2007 Developer") );
+
#include <KAction>
  KCmdLineArgs::init( argc, argv, &aboutData );
+
...
  KApplication app;
+
KAction* clearAction = new KAction(this);
+
  MainWindow* window = new MainWindow();
+
  window->show();
+
  return app.exec();
+
}
+
 
</code>
 
</code>
 +
Этот код создаёт действие <tt>clearAction</tt>.
 +
 +
===Настройка свойств KAction===
 +
 +
=====Текст=====
 +
Теперь, когда объект KAction создан, можно приступить к его настройке. Сначала, мы задаём текст, отображаемый в меню и под значком <tt>KAction</tt> на панели инструментов.
 +
<code cppqt>clearAction->setText(i18n("Clear"));</code>
 +
Если планируется перевод интерфейса, то следует использовать функцию i18n для обработки текста (более подробную информацию можно получить в [[Development/Tutorials/Localization/i18n|уроке по i18n]]
 +
 +
 +
=====Значок=====
 +
В случае отображения действия на панели неплохо использовать значок, характеризующий это действие. Следующий код с помощью функции <tt>setIcon()</tt> устанавливает стандартный значок KDE <tt>document-new</tt>
 +
<code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
 +
 +
=====Комбинация клавиш=====
 +
Связать комбинацию клавиш с нашим действием совершенно просто:
 +
<code cppqt>clearAction->setShortcut(Qt::CTRL + Qt::Key_W);</code>
 +
Данный фрагмент кода связывает с нашим действием комбинацию клавиш Ctrl+W:
 +
 +
 +
=====Добавдение в набор (Collection)=====
 +
 +
Чтобы сделать наше действие доступным системе XMLGUI (более подробное объяснение приведено дальше), следует добавить его в ''набор действий (action collection)'' приложения c помощью <tt>actionCollection()</tt> следующим образом:
 +
<code cppqt>
 +
actionCollection()->addAction("clear", clearAction);
 +
</code>
 +
В данном примере мы добавляем <tt>clearAction</tt> в коллекцию, задав имя ''clear''. Это имя используется системой XMLGUI.
 +
 +
 +
=====Соединение действия с обработчиком=====
 +
 +
Теперь, когда параметры внешнего вида действия определены, можно связать его с методом tt>clear()</tt> объекта KTextArea.
 +
<code cppqt>
 +
connect( clearAction, SIGNAL( triggered(bool) ),
 +
        textArea, SLOT( clear() ) );
 +
</code>
 +
Интерфейс класса аналогичен {{qt|QAction}}, в KAction лишь добавлены специфические для KDE особенности.
 +
 +
===KStandardAction===
 +
 +
Для часто используемых в KDE приложениях действий, таких, как quit, save, и load, доступны готовые объекты KAction, доступные через класс {{class|KStandardAction}}.
 +
 +
Их очень легко использовать. После включения заголовочного файла <tt><KStandardAction></tt> в ваш код, следует просто соединить их с функциями-обработчиками и добавить в соответствующую коллекцию (KActionCollection). Например, следующий код
 +
 +
<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
 +
создаст действие с соответствующим значком, текстом, клавишей быстрого вызова и даже добавит пункт в меню File.
  
  
 
==Добавление действия в меню и на панель управления==
 
==Добавление действия в меню и на панель управления==
  
На данном этапе действие "Clear" только создано: оно не будет отображено в меню или на панели управления. Чтобы задать, куда следует добавить действия (и позволить пользователю программы перемещать их), следует использовать KDE-технологию XmlGui.  
+
На данном этапе действие "Clear" только создано: оно не будет отображено в меню или на панели управления. Чтобы задать, куда следует добавить действия (и позволить пользователю программы перемещать их), следует использовать KDE-технологию XMLGUI.  
 +
 
 +
{{note|В последующих версиях KDE4, XMLGUI может быть заменена на систему liveui. Но сейчас XMLGUI является единственным правильным способом настройки UI.}}
  
===XmlGui===
 
  
{{note|В последующих версиях KDE4, XmlGui может быть заменена на систему liveui. Но сейчас XmlGui является единственным верным способом настройки UI.}}
+
===XMLGUI===
  
 
При вызове функции <tt>setupGUI()</tt> в нашем классе (производном) {{class|KXmlGuiWindow}}, осуществляется обращение к системе XmlGui, которая читатет XML файл с описанием интерфейса (мы рассмотрим его позже) и создаёт кнопки и меню.
 
При вызове функции <tt>setupGUI()</tt> в нашем классе (производном) {{class|KXmlGuiWindow}}, осуществляется обращение к системе XmlGui, которая читатет XML файл с описанием интерфейса (мы рассмотрим его позже) и создаёт кнопки и меню.

Revision as of 18:22, 26 December 2007


Contents

Development/Tutorials/Using_KActions


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

Введение

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

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

Introtokdetutorial3.png

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

} This time, very little has changed in main.cpp, only the KAboutData constructor has been updated to show that we are now on tutorial 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

Only a function void setupActions() has been added which will do all the work setting up the 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:

  1. 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.


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

Теперь, когда параметры внешнего вида действия определены, можно связать его с методом tt>clear()</tt> объекта 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.

noframe
 
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"?> <!DOCTYPE kpartgui SYSTEM "kpartgui.dtd"> <gui name="tutorial3" version="1">

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

</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


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal