Development/Tutorials/Using KActions: Difference between revisions

From KDE TechBase
(→‎tutorial3ui.rc: According to the DTD, <kpartgui> is deprecated as root element, use <gui> now)
(The page was moved again)
 
(62 intermediate revisions by 31 users not shown)
Line 1: Line 1:
{{TutorialBrowser|
This page was moved [https://develop.kde.org/docs/getting-started/kxmlgui/using_actions/ here]
 
series=Beginner Tutorial|
 
name=How To Use KActions and XmlGui|
 
pre=[[Development/Tutorials/Programming_Tutorial_KDE_4/Using_KXmlGuiWindow|Tutorial 2 - KXmlGuiWindow]], Basic XML knowledge|
 
next=[[Development/Tutorials/Programming_Tutorial_KDE_4/Using_KConfig|Tutorial 4 - KConfig]]|
 
reading=None
}}
 
==Abstract==
We're going to introduce the concept of actions. Actions are a unified way of supplying the user with ways to interact with your program.
 
Say, for example, we want to let the user clear the text box by clicking a button in the toolbar, from an option in the File menu or through a keyboard shortcut; we can provide all of those through one {{class|KAction}}.
 
[[image:introtokdetutorial3.png|frame|center]]
 
==KAction==
A {{class|KAction}} is an object which contains all the information about the icon and shortcuts you want associated to a certain action. You then connect the action to a [http://doc.trolltech.com/latest/signalsandslots.html slot] which carries out the work of your action.
 
===Creating Your Own===
 
To create an action, you need to <tt>#include <KAction></tt> in your <tt>.cpp</tt> file.
=====Creating the object=====
We're going to create an action which will clear the text area (see Tutorial 2). The KAction is built up in a number of steps. The first is creating the KAction
<code cppqt>KAction* clearAction = new KAction(actionCollection(), "clear");</code>
This creates a KAction called <tt>clearAction</tt>. The first constructor argument is telling the action that it is part of the <tt>{{class|KActionCollection}} actionCollection()</tt> and the second is simply setting a name for internal use (it doesn't necessarily have to be textually similar to the function of the action).
=====Text=====
Now we have our KAction object, we can start setting its properties. First, we'll set the text that will be displayed in the menu and under its icon in the toolbar.
<code cppqt>clearAction->setText(i18n("Clear"));</code>
As you can see, the text must be passed through the i18n() function if you want your UI to be translatable.
 
=====Icon=====
If you're going to display the action in a toolbar, you're going to want to have an icon depicting the action. To set an icon we simply use the <tt>setIcon()</tt> function thus:
<code cppqt>clearAction->setIcon(KIcon("filenew"));</code>
Here we're setting the icon to the standard KDE <tt>filenew</tt> icon.
=====Shortcut=====
We can also set a shortcut that will perform our action. It's as simple as a
<code cppqt>clearAction->setShortcut(Qt::CTRL+Qt::Key_W);</code>
to set Ctrl+W to be associated to this action.
=====Connecting the action=====
Now our action is fully set up, we need to connect it to something useful. We're going to connect our action to the <tt>clear()</tt> action belonging to a KTextArea.
<code cppqt>
connect( clearAction, SIGNAL( triggered(bool) ),
        textArea, SLOT( clear() ) );
</code>
This is the same as it would be done in Qt with a {{qt|QAction}}.
 
===KStandardAction===
 
For actions which would likely appear in almost every KDE application such as 'quit', 'save', and 'load' there are pre-created convenience KActions, accessed through {{class|KStandardAction}}.
 
They are very simple to use. Once you've done <tt>#include <KStandardAction></tt>, you simply need to supply it with what you want the function to do and which KActionCollection to add it to. For example,
<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
Will Create a KAction with the correct icon, text and shortcut and will even add it to the File menu.
 
==The Code==
===mainwindow.h===
<code cppqt n>
#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
</code>
 
===mainwindow.cpp===
<code cppqt n>
#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()
{
  QAction* clearAction =
          actionCollection()->addAction( "clear" );
  clearAction->setText(i18n("Clear"));
  clearAction->setIcon(KIcon("filenew"));
  clearAction->setShortcut(Qt::CTRL+Qt::Key_W);
  connect(clearAction, SIGNAL(triggered(bool)),
          textArea, SLOT(clear()));
 
  KStandardAction::quit(kapp, SLOT(quit()),
                        actionCollection());
 
  setupGUI();
}
</code>
 
===main.cpp===
<code cppqt n>
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>
 
#include "mainwindow.h"
 
int main (int argc, char *argv[])
{
  KAboutData aboutData( "tutorial3", "Tutorial 3",
      "1.0", "A simple text area using KAction etc.",
      KAboutData::License_GPL, "(c) 2006" );
  KCmdLineArgs::init( argc, argv, &aboutData );
  KApplication app;
  MainWindow* window = new MainWindow();
  window->show();
  return app.exec();
}
</code>
 
==Putting the actions in the menus and toolbars==
Now, at the moment, we've only created our new "Clear" action. It won't yet show up in the menus or in the toolbars. To tell the program where to put our actions (and to allow the end-user to move them around) we use a KDE technology called XmlGui.
===XmlGui===
{{improve|Mention that it will be replaced by liveui}}
 
When you call <tt>setupGUI()</tt> in your {{class|KXmlGuiWindow}} class, it calls the XmlGui system which reads an XML file description of your interface (which we will create in a minute) and creates the buttons and menus appropriately.
 
Now obviously XmlGui needs to know which file is your description file, i.e. it needs to know its name and location. The rule for the naming is the file should be called <tt>appnameui.rc</tt> (where <tt>appname</tt> is the name you set in {{class|KAboutData}}), so in our example, the file will be called <tt>tutorial3ui.rc</tt>. Where the file will be located is handled by CMake.
 
===Writing your ''appname''ui.rc File===
 
Since the description of our UI is being defined with XML, the layout of the description must follow strict rules. We won't go through all the rules in this tutorial but for more information, see the _detailed_XmlGui_page_ (once we have a full explanation of XmlGui (or possibly liveui if that's done soon :)) on the wiki, I'll link it up).
 
{{improve|Walk through what the code below means}}
 
===tutorial3ui.rc===
<code xml n>
<?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>&amp;File</text>
      <Action name="clear" />
    </Menu>
  </MenuBar>
</gui>
</code>
 
==CMake==
Now that we're using XmlGui, we need to put the <tt>tutorial3ui.rc</tt> somewhere where KDE can find it. '''This means we need to install our project somewhere.'''
===CMakeLists.txt===
<code ini n>
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 )
</code>
 
===Make, Install And Run===
If you don't have write access to where your KDE4 installation directory, you can install it to a folder in your home directory.
 
To tell CMake where to install the program, set the <tt>DCMAKE_INSTALL_PREFIX</tt> switch. So to install the program to the KDE directory, do
cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
make install
tutorial3
Though, if you just want to install it somewhere local for testing (it's probably a bit silly to go to the effort of installing these tutorials to your KDE directory) you can do something like
cmake . -DCMAKE_INSTALL_PREFIX=/home/user/kdetmp
which will create a KDE-like directory structure under ~/kdetmp
 
==Moving On==
Now that we can make the GUI look like and do whatever we want, we can move on to storing application settings with [[Development/Tutorials/Programming_Tutorial_KDE_4/Using_KConfig|KConfig XT]].
 
[[Category:C++]]

Latest revision as of 14:15, 18 July 2023

This page was moved here

Retrieved from "https://techbase.kde.org/index.php?title=Development/Tutorials/Using_KActions&oldid=106984"