Development/Tutorials/Using KActions (pt BR): Difference between revisions
(→Resumo) |
No edit summary |
||
(5 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
{{TutorialBrowser (pt_BR)| | {{TutorialBrowser (pt_BR)| | ||
Line 27: | Line 27: | ||
===main.cpp=== | ===main.cpp=== | ||
< | <syntaxhighlight lang="cpp-qt"> | ||
#include <KApplication> | #include <KApplication> | ||
#include <KAboutData> | #include <KAboutData> | ||
Line 48: | Line 48: | ||
return app.exec(); | return app.exec(); | ||
} | } | ||
</ | </syntaxhighlight> | ||
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. | 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. | ||
===mainwindow.h=== | ===mainwindow.h=== | ||
< | <syntaxhighlight lang="cpp-qt"> | ||
#ifndef MAINWINDOW_H | #ifndef MAINWINDOW_H | ||
#define MAINWINDOW_H | #define MAINWINDOW_H | ||
Line 70: | Line 70: | ||
#endif | #endif | ||
</ | </syntaxhighlight> | ||
Only a function <tt>void setupActions()</tt> has been added which will do all the work setting up the KActions. | Only a function <tt>void setupActions()</tt> has been added which will do all the work setting up the KActions. | ||
===mainwindow.cpp=== | ===mainwindow.cpp=== | ||
< | <syntaxhighlight lang="cpp-qt"> | ||
#include "mainwindow.h" | #include "mainwindow.h" | ||
Line 107: | Line 107: | ||
setupGUI(); | setupGUI(); | ||
} | } | ||
</ | </syntaxhighlight> | ||
==Explicação== | ==Explicação== | ||
Line 114: | Line 114: | ||
===Criando o objeto KAction=== | ===Criando o objeto KAction=== | ||
The KAction is built up in a number of steps. The first is including the <tt>KAction</tt> library and then creating the KAction: | The KAction is built up in a number of steps. The first is including the <tt>KAction</tt> library and then creating the KAction: | ||
< | <syntaxhighlight lang="cpp-qt"> | ||
#include <KAction> | #include <KAction> | ||
... | ... | ||
KAction* clearAction = new KAction(this); | KAction* clearAction = new KAction(this); | ||
</ | </syntaxhighlight> | ||
This creates a new KAction called <tt>clearAction</tt>. | This creates a new KAction called <tt>clearAction</tt>. | ||
Line 124: | Line 124: | ||
====Texto==== | ====Texto==== | ||
Now we have our KAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the <tt>KAction</tt>'s icon in the toolbar. | Now we have our KAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the <tt>KAction</tt>'s icon in the toolbar. | ||
< | <syntaxhighlight lang="cpp-qt">clearAction->setText(i18n("Clear"));</syntaxhighlight> | ||
Note that the text is passed through the i18n() function; this is necessary for the UI to be translatable (more information on this can be found in the [[Development/Tutorials/Localization/i18n|i18n tutorial]]). | Note that the text is passed through the i18n() function; this is necessary for the UI to be translatable (more information on this can be found in the [[Development/Tutorials/Localization/i18n|i18n tutorial]]). | ||
====Ícone==== | ====Ícone==== | ||
If the action is going to be displayed in a toolbar, it's nice to have an icon depicting the action. The following code sets the icon to the standard KDE <tt>document-new</tt> icon through the use of the <tt>setIcon()</tt> function: | If the action is going to be displayed in a toolbar, it's nice to have an icon depicting the action. The following code sets the icon to the standard KDE <tt>document-new</tt> icon through the use of the <tt>setIcon()</tt> function: | ||
< | <syntaxhighlight lang="cpp-qt">clearAction->setIcon(KIcon("document-new"));</syntaxhighlight> | ||
====Atalhos de Teclado==== | ====Atalhos de Teclado==== | ||
Setting a keyboard shortcut to perform our action is equally simple: | Setting a keyboard shortcut to perform our action is equally simple: | ||
< | <syntaxhighlight lang="cpp-qt">clearAction->setShortcut(Qt::CTRL + Qt::Key_W);</syntaxhighlight> | ||
This associates Ctrl+W with the KAction. | This associates Ctrl+W with the KAction. | ||
===Adding to the Collection=== | ===Adding to the Collection=== | ||
In order for the action to be accessed by the XMLGUI framework (explained in depth later) it must be added to the application's ''action collection''. The action collection is accessed via the <tt>actionCollection()</tt> function like this: | In order for the action to be accessed by the XMLGUI framework (explained in depth later) it must be added to the application's ''action collection''. The action collection is accessed via the <tt>actionCollection()</tt> function like this: | ||
< | <syntaxhighlight lang="cpp-qt"> | ||
actionCollection()->addAction("clear", clearAction); | actionCollection()->addAction("clear", clearAction); | ||
</ | </syntaxhighlight> | ||
Here, the <tt>clearAction</tt> KAction is added to the collection and given a name of ''clear''. This name (''clear'') is used by the XMLGUI framework to refer to the action, ergo, it should not be localized, since it is used internally only. | Here, the <tt>clearAction</tt> KAction is added to the collection and given a name of ''clear''. This name (''clear'') is used by the XMLGUI framework to refer to the action, ergo, it should not be localized, since it is used internally only. | ||
====Conectando a ação==== | ====Conectando a ação==== | ||
Now that the action is fully set up, it needs to be connected to something useful. In this case (because we want to clear the text area), we connect our action to the <tt>clear()</tt> action belonging to a KTextEdit (which, unsurprisingly, clears the KTextEdit) | Now that the action is fully set up, it needs to be connected to something useful. In this case (because we want to clear the text area), we connect our action to the <tt>clear()</tt> action belonging to a KTextEdit (which, unsurprisingly, clears the KTextEdit) | ||
< | <syntaxhighlight lang="cpp-qt"> | ||
connect( clearAction, SIGNAL( triggered(bool) ), | connect( clearAction, SIGNAL( triggered(bool) ), | ||
textArea, SLOT( clear() ) ); | textArea, SLOT( clear() ) ); | ||
</ | </syntaxhighlight> | ||
This is the same as it would be done in Qt with a {{qt|QAction}}. | This is the same as it would be done in Qt with a {{qt|QAction}}. | ||
Line 156: | Line 156: | ||
They are very simple to use. Once the library has been included (<tt>#include <KStandardAction></tt>), simply supply it with what you want the function to do and which KActionCollection to add it to. For example: | They are very simple to use. Once the library has been included (<tt>#include <KStandardAction></tt>), simply supply it with what you want the function to do and which KActionCollection to add it to. For example: | ||
< | <syntaxhighlight lang="cpp-qt">KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</syntaxhighlight> | ||
This creates a KAction with the correct icon, text and shortcut and even adds it to the File menu. | This creates a KAction with the correct icon, text and shortcut and even adds it to the File menu. | ||
Line 175: | Line 175: | ||
===tutorial3ui.rc=== | ===tutorial3ui.rc=== | ||
< | <syntaxhighlight lang="xml"> | ||
<?xml version="1.0" encoding="UTF-8"?> | <?xml version="1.0" encoding="UTF-8"?> | ||
<gui name="tutorial3" | |||
<gui name="tutorial3" version="1" | 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> | <MenuBar> | ||
<Menu name="file" > | <Menu name="file" > | ||
Line 188: | Line 189: | ||
</Menu> | </Menu> | ||
</MenuBar> | </MenuBar> | ||
<ToolBar name="mainToolBar" > | |||
<text>Main Toolbar</text> | |||
<Action name="clear" /> | |||
</ToolBar> | |||
</gui> | </gui> | ||
</ | </syntaxhighlight> | ||
The <tt><Toolbar></tt> tag allows you to describe the toolbar, which is the bar across the top of the window normally with icons. Here it is given the unique name ''mainToolBar'' and its user visible name set to ''Main Toolbar'' using the <tt><text></tt> tag. The clear action is added to the toolbar using the <tt><Action></tt> tag, the name parameter in this tag being the string that was passed to the KActionCollection with <tt>addAction()</tt> in <tt>mainwindow.cpp</tt>. | The <tt><Toolbar></tt> tag allows you to describe the toolbar, which is the bar across the top of the window normally with icons. Here it is given the unique name ''mainToolBar'' and its user visible name set to ''Main Toolbar'' using the <tt><text></tt> tag. The clear action is added to the toolbar using the <tt><Action></tt> tag, the name parameter in this tag being the string that was passed to the KActionCollection with <tt>addAction()</tt> in <tt>mainwindow.cpp</tt>. | ||
Line 202: | Line 209: | ||
Finally, the <tt>tutorial3ui.rc</tt> needs to go somewhere where KDE can find it (can't just leave it in the source directory!). '''This means the project needs to be installed somewhere.''' | Finally, the <tt>tutorial3ui.rc</tt> needs to go somewhere where KDE can find it (can't just leave it in the source directory!). '''This means the project needs to be installed somewhere.''' | ||
===CMakeLists.txt=== | ===CMakeLists.txt=== | ||
< | <syntaxhighlight lang="ini"> | ||
project(tutorial3) | project(tutorial3) | ||
Line 220: | Line 227: | ||
install(FILES tutorial3ui.rc | install(FILES tutorial3ui.rc | ||
DESTINATION ${DATA_INSTALL_DIR}/tutorial3) | DESTINATION ${DATA_INSTALL_DIR}/tutorial3) | ||
</ | </syntaxhighlight> | ||
This file is almost identical to the one for tutorial2, but with two extra lines at the end that describe where the files are to be installed. Firstly, the <tt>tutorial3</tt> target is installed to the <tt>BIN_INSTALL_DIR</tt> then the <tt>tutorial3ui.rc</tt> file that describes the layout of the user interface is installed to the application's data directory. | This file is almost identical to the one for tutorial2, but with two extra lines at the end that describe where the files are to be installed. Firstly, the <tt>tutorial3</tt> target is installed to the <tt>BIN_INSTALL_DIR</tt> then the <tt>tutorial3ui.rc</tt> file that describes the layout of the user interface is installed to the application's data directory. |
Latest revision as of 18:21, 15 July 2012
Série de Tutoriais | Tutorial para iniciantes |
Pré-requisitos | Tutorial 2 - KXmlGuiWindow, Conhecimento básico sobre XML |
Qual é o próximo | Tutorial 4 - Saving and loading |
Leitura adicional | Nenhum |
Resumo
Este tutorial introduz o conceito de ações. Ações são uma maneira unificada de fornecer ao usuário formas de interagir com o seu programa.
For example, if we wanted to let the user of Tutorial 2 clear the text box by clicking a button in the toolbar, from an option in the File menu or through a keyboard shortcut, it could all be done with one KAction.
KAction
A KAction is an object which contains all the information about the icon and shortcuts that is associated with a certain action. The action is then connected to a slot which carries out the work of your action.
O Código
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();
}
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
#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
Only a function void setupActions() has been added which will do all the work setting up the 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();
}
Explicação
This builds upon the KXmlGuiWindow code from Tutorial 2. Most of the changes are to mainwindow.cpp, an important structural change being that the constructor for MainWindow now calls setupActions() instead of setupGUI(). setupActions() is where the new KAction code goes before finally calling setupGUI() itself.
Criando o objeto KAction
The KAction is built up in a number of steps. The first is including the KAction library and then creating the KAction:
#include <KAction>
...
KAction* clearAction = new KAction(this);
This creates a new KAction called clearAction.
Definindo as propriedades do KAction
Texto
Now we have our KAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the KAction's icon in the toolbar.
clearAction->setText(i18n("Clear"));
Note that the text is passed through the i18n() function; this is necessary for the UI to be translatable (more information on this can be found in the i18n tutorial).
Ícone
If the action is going to be displayed in a toolbar, it's nice to have an icon depicting the action. The following code sets the icon to the standard KDE document-new icon through the use of the setIcon() function:
clearAction->setIcon(KIcon("document-new"));
Atalhos de Teclado
Setting a keyboard shortcut to perform our action is equally simple:
clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
This associates Ctrl+W with the KAction.
Adding to the Collection
In order for the action to be accessed by the XMLGUI framework (explained in depth later) it must be added to the application's action collection. The action collection is accessed via the actionCollection() function like this:
actionCollection()->addAction("clear", clearAction);
Here, the clearAction KAction is added to the collection and given a name of clear. This name (clear) is used by the XMLGUI framework to refer to the action, ergo, it should not be localized, since it is used internally only.
Conectando a ação
Now that the action is fully set up, it needs to be connected to something useful. In this case (because we want to clear the text area), we connect our action to the clear() action belonging to a KTextEdit (which, unsurprisingly, clears the KTextEdit)
connect( clearAction, SIGNAL( triggered(bool) ),
textArea, SLOT( clear() ) );
This is the same as it would be done in Qt with a 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 KStandardAction.
They are very simple to use. Once the library has been included (#include <KStandardAction>), simply supply it with what you want the function to do and which KActionCollection to add it to. For example:
KStandardAction::quit(kapp, SLOT(quit()), actionCollection());
This creates a KAction with the correct icon, text and shortcut and even adds it to the File menu.
At the moment, the new "Clear" action has been created but it hasn't been associated with any menus or toolbars. This is done with a KDE technology called XMLGUI, which does nice things like movable toolbars for you.
XMLGUI
The setupGUI() function in KXmlGuiWindow depends on the XMLGUI system to construct the GUI, which XMLGUI does by parsing an XML file description of the interface.
The rule for naming this XML file is appnameui.rc, where appname is the name you set in KAboutData (in this case, tutorial3). So in our example, the file is called tutorial3ui.rc, and is located in the build directory. Where the file will ultimately be placed is handled by CMake.
Arquivo appnameui.rc
Since the description of the UI is defined with XML, the layout must follow strict rules. This tutorial will not go into great depth on this topic, but for more information, see the detailed XMLGUI page (here is an older tutorial: [1]).
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" >
<Action name="clear" />
</Menu>
</MenuBar>
<ToolBar name="mainToolBar" >
<text>Main Toolbar</text>
<Action name="clear" />
</ToolBar>
</gui>
The <Toolbar> tag allows you to describe the toolbar, which is the bar across the top of the window normally with icons. Here it is given the unique name mainToolBar and its user visible name set to Main Toolbar using the <text> tag. The clear action is added to the toolbar using the <Action> tag, the name parameter in this tag being the string that was passed to the KActionCollection with addAction() in mainwindow.cpp.
Besides having the action in the toolbar, it can also be added to the menubar. Here the action is being added to the File menu of the MenuBar the same way it was added to the toolbar.
Change the 'version' attribute of the <gui> tag if you changed .rc file since the last install to force a system cache update.
Some notes on the interaction between code and the .rc file: Menus appear automatically and should have a <text/> child tag unless they refer to standard menus. Actions need to be created manually and inserted into the actionCollection() using the name in the .rc file. Actions can be hidden or disabled, whereas menus can't.
CMake
Finally, the tutorial3ui.rc needs to go somewhere where KDE can find it (can't just leave it in the source directory!). This means the project needs to be installed somewhere.
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)
This file is almost identical to the one for tutorial2, but with two extra lines at the end that describe where the files are to be installed. Firstly, the tutorial3 target is installed to the BIN_INSTALL_DIR then the tutorial3ui.rc file that describes the layout of the user interface is installed to the application's data directory.
Compilar, Instalar e Executar
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 DCMAKE_INSTALL_PREFIX switch. You probably 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), so the following might be appropriate:
mkdir build && cd build cmake .. -DCMAKE_INSTALL_PREFIX=$HOME make install $HOME/bin/tutorial3
which will create a KDE-like directory structure in your user's home directory directory and will install the executable to $HOME/bin/tutorial3.
Continuando
Now you can move on to saving and loading.