Development/Tutorials/Using Actions/pt-br: Difference between revisions

From KDE TechBase
(Created page with "==Explicação==")
(Updating to match new version of source page)
 
(60 intermediate revisions by one other user not shown)
Line 138: Line 138:
==Explicação==
==Explicação==


This builds upon the KXmlGuiWindow code from [[Development/Tutorials/Using_KXmlGuiWindow/KF5|Tutorial 2]]. Most of the changes are to <tt>mainwindow.cpp</tt>, an important structural change being that the constructor for MainWindow now calls <tt>setupActions()</tt> instead of <tt>setupGUI()</tt>. <tt>setupActions()</tt> is where the new QAction code goes before finally calling <tt>setupGUI()</tt> itself.
Isso se baseia no código do KXmlGuiWindow do [[Development/Tutorials/Using_KXmlGuiWindow/KF5|Tutorial 2]]. A maioria das alterações é no <tt>mainwindow.cpp</tt>, uma mudança estrutural importante é que o construtor do MainWindow agora chama <tt>setupActions()</tt> em vez de <tt>setupGUI()</tt >. <tt>setupActions()</tt> é o local onde o novo código QAction vai antes de finalmente chamar <tt>setupGUI()</tt>.


===Creating the QAction object===
===Criando o objeto QAction===


The QAction is built up in a number of steps. The first is including the <tt>QAction</tt> header and then creating the QAction:
O QAction é construído em várias etapas. A primeira é a inclusão no cabeçalho do <tt>QAction</tt> e a criação do QAction:
<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
#include <QAction>
#include <QAction>
Line 148: Line 148:
QAction* clearAction = new QAction(this);
QAction* clearAction = new QAction(this);
</syntaxhighlight>
</syntaxhighlight>
This creates a new QAction called <tt>clearAction</tt>.
Isso cria um novo QAction chamado <tt>clearAction</tt>.


===Setting QAction Properties===
===Definindo propriedades QAction===


====Text====
====Texto====


Now that we have our QAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and with the <tt>QAction</tt>'s icon in the toolbar, depending on the widget style (whether beside or below the icon) or setting (whether to display the action text or not).  
Agora que temos nosso objeto QAction, podemos começar a definir suas propriedades. O código a seguir define o texto que será exibido no menu e com o ícone do <tt>QAction</tt> na barra de ferramentas, dependendo do estilo do widget (seja ao lado ou abaixo do ícone) ou da configuração (se deseja exibir o texto da ação ou não).  
<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
clearAction->setText(i18n("&Clear"));
clearAction->setText(i18n("&Clear"));
</syntaxhighlight>
</syntaxhighlight>
Note that the text is passed through the <tt>i18n()</tt> 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]]).
Observe que o texto é passado através da função <tt>i18n()</tt>; isso é necessário para que a interface do usuário seja traduzível (mais informações sobre isso podem ser encontradas no [[Development/Tutorials/Localization/i18n|tutorial i18n]]).


The text of the action should contain a <tt>&</tt> because that makes it easier to translate in non-latin1 languages. In Japanese, the translation might be <tt>ソース(&S)</tt> and without the <tt>&</tt> in the english text the translators cannot know if they have to add a <tt>&</tt> or not.
O texto do action deve conter um <tt>&</tt> porque isso facilita a tradução em idiomas non-latin1. Em japonês, a tradução pode ser  <tt>ソース(&S)</tt> e sem o <tt>&</tt> no texto em inglês os tradutores não podem saber se precisam adicionar um <tt>&</tt> ou não.


====Icon====
====Ícone====


If the action is going to be displayed in a toolbar, it is nice to have an icon depicting the action. The icon may also be displayed beside the action in the menus, depending on the widget style. The following code sets the icon to the standard the <tt>document-new</tt> icon through the use of the <tt>setIcon()</tt> function:
Se o action for exibido em uma barra de ferramentas, é legal ter um ícone representando a ação. O ícone também pode ser exibido ao lado do action nos menus, dependendo do estilo do widget. O código a seguir define o ícone padrão como <tt>document-new</tt> através do uso da função <tt>setIcon()</tt>:
<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
clearAction->setIcon(QIcon::fromTheme("document-new"));
clearAction->setIcon(QIcon::fromTheme("document-new"));
</syntaxhighlight>
</syntaxhighlight>
====Keyboard Shortcut====
====Atalho do teclado====


Setting a keyboard shortcut to perform our action is equally simple:
Definir um atalho do teclado para executar nossa ação é igualmente simples:
<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
actionCollection()->setDefaultShortcut(clearAction, Qt::CTRL + Qt::Key_W);
actionCollection()->setDefaultShortcut(clearAction, Qt::CTRL + Qt::Key_W);
</syntaxhighlight>
</syntaxhighlight>
This associates Ctrl+W with the QAction.
Isso associa Ctrl + W ao QAction.


===Adding to the Collection===
===Adicionando ao 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:  
Para que a ação seja acessada pelo XMLGUI framework( explicada em detalhes posteriormente), ela deve ser adicionada ao ''action collection'' do aplicativo. A coleção de ações é acessada através da função <tt>actionCollection()</tt>, da seguinte forma:  
<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
actionCollection()->addAction("clear", clearAction);
actionCollection()->addAction("clear", clearAction);
</syntaxhighlight>
</syntaxhighlight>
Here, the <tt>clearAction</tt> QAction 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.
Aqui, o QAction <tt>clearAction</tt> é adicionado à coleção e recebe um nome de ''clear''. Esse nome (''clear'') é usado pela XMLGUI framework para se referir ao action, portanto, não deve ser localizada, pois é usada apenas internamente.


====Connecting the action====
====Conectando ao action====


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)
Agora que o action está totalmente configurado, ele precisa estar conectado a algo útil. Nesse caso( porque queremos limpar a área de texto), conectamos nossa action à ação <tt>clear()</tt> pertencente a um KTextEdit (que, sem surpresa, limpa o KTextEdit)
<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
connect( clearAction, SIGNAL( triggered(bool) ),  
connect( clearAction, SIGNAL( triggered(bool) ),  
Line 193: Line 193:
===KStandardAction===
===KStandardAction===


For actions which would likely appear in almost every KDE application such as 'quit', 'save', and 'load' there are pre-created convenience QActions, accessed through {{class|KStandardAction}}.
Para ações que provavelmente apareceriam em quase todos os aplicativos do KDE, como 'sair', 'salvar' e 'carregar', existem QActions convenientes pré-criados, acessados através do {{class|KStandardAction}}.


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 QActionCollection to add it to. For example:
Eles são muito simples de usar. Depois que a biblioteca for incluída (<tt>#include <KStandardAction></tt>), basta fornecer o que você deseja que a função faça e a qual QActionCollection será incluído. Por exemplo:
<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
KStandardAction::quit(qApp, SLOT(quit()), actionCollection());
KStandardAction::quit(qApp, SLOT(quit()), actionCollection());
</syntaxhighlight>
</syntaxhighlight>
Here we call the QApplicaton's [http://doc.qt.io/qt-5/qapplication.html#quit quit] method whenever the KStandardAction quit is triggered. We are able to access that QApplication method via the [http://doc.qt.io/qt-5/qapplication.html#qApp qApp] macro.
Aqui chamamos o método [http://doc.qt.io/qt-5/qapplication.html#quit quit] do QApplicaton sempre que o KStandardAction é acionado. Podemos acessar esse método QApplication por meio da macro [http://doc.qt.io/qt-5/qapplication.html#qApp qApp].


In the end, this creates a QAction with the correct icon, text and shortcut and even adds it to the File menu.
Por fim, isso cria um QAction com o ícone, texto e atalho corretos e até o adiciona ao menu Arquivo.


==Adding the action to menus and toolbars==
==Adicionando o action a menus e barras de ferramentas==


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.
Até o momento, o novo action "Clear" foi criado, mas não foi associado a nenhum menu ou barra de ferramentas. Isso é feito com uma tecnologia do KDE chamada XMLGUI, que faz coisas legais como barras de ferramentas móveis para você.


==Defining your own help menu==
==Definindo seu próprio menu de ajuda==


The Help menu has been standardized to ease the lives of both developers and users, which is why all KDE software Help menus look the same. If you want to create your own help menu, search for the explanation around showAboutApplication() in from the {{class|KHelpMenu}} class in XMLGUI.
O menu Ajuda foi padronizado para facilitar a vida de desenvolvedores e usuários, e é por isso que todos os menus de Ajuda do software KDE têm a mesma aparência. Se você deseja criar seu próprio menu de ajuda, procure pela explicação sobre o showAboutApplication() na classe {{class|KHelpMenu}} da XMLGUI.


==XMLGUI==
==XMLGUI==


The <tt>setupGUI()</tt> function in {{class|KXmlGuiWindow}} depends on the XMLGUI system to construct the GUI, which XMLGUI does by parsing an XML file description of the interface.
A função <tt>setupGUI()</tt> em {{class|KXmlGuiWindow}} depende do sistema XMLGUI para construir a GUI, no qual o XMLGUI faz analizando uma descrição de arquivo XML da interface.


The rule for naming this XML file is <tt>appnameui.rc</tt>, where <tt>appname</tt> is the name you set in {{class|KAboutData}} (in this case, ''tutorial3''). So in our example, the file is called <tt>tutorial3ui.rc</tt>, and is located in the build directory. Where the file will ultimately be placed is handled by CMake.
A regra para nomear esse arquivo XML é <tt>appnameui.rc</tt>, onde <tt>appname</tt> é o nome que você definiu em {{class | KAboutData}} (neste caso, ''tutorial3''). Portanto, em nosso exemplo, o arquivo é chamado <tt>tutorial3ui.rc</tt> e está localizado no diretório de build. O local onde o arquivo será finalmente colocado é tratado pelo CMake.


==appnameui.rc file==
==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 [[Development/Architecture/KDE4/XMLGUI_Technology|detailed XMLGUI page]].
Como a descrição da interface do usuário é definida com XML, o layout deve seguir regras estritas. Este tutorial não entrará em detalhes sobre este tópico, mas para obter mais informações, consulte a [[Development/Architecture/KDE4/XMLGUI_Technology|página detalhada do XMLGUI]].


===tutorial3ui.rc===
===tutorial3ui.rc===
Line 248: Line 248:
</gui>
</gui>
</syntaxhighlight>
</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>.
A tag <tt><Toolbar></tt> permite que você descreva a barra de ferramentas, que é a barra na parte superior da janela, normalmente com ícones. Aqui é dado o nome exclusivo ''mainToolBar'' e seu nome visível ao usuário definido como ''Main Toolbar'' usando a tag <tt><text></tt>. A action clear é adicionada à barra de ferramentas usando a tag <tt><Action></tt>, o parâmetro name nessa tag é a string que foi passada para o KActionCollection com <tt>addAction()</tt> em <tt>mainwindow.cpp</tt>.


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 <tt>MenuBar</tt> the same way it was added to the toolbar.
Além de ter o action na barra de ferramentas, também pode ser adicionado à barra de menus. Aqui a ação está sendo adicionada ao menu ''File'' do <tt>MenuBar</tt> da mesma maneira que foi adicionada à barra de ferramentas.


Change the 'version' attribute of the <tt><nowiki><gui></nowiki></tt> tag if you changed .rc file since the last install to force a system cache update. Be sure it is an integer, if you use a decimal value, it will not work, but will not notify that it didn't. '
Altere o atributo 'version' da tag <tt><nowiki><gui></nowiki> </tt> se você alterou o arquivo .rc desde a última instalação para forçar uma atualização do cache do sistema. Certifique-se de que é um número inteiro, se você usar um valor decimal ele não funcionará, e não notificará . "


{{Warning|The version attribute must always be an integer number.}}
{{Warning (pt BR)|O atributo version deve sempre ser um número inteiro.}}


Some notes on the interaction between code and the .rc file: Menus appear automatically and should have a <tt><nowiki><text/></nowiki></tt> 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.
Algumas notas sobre a interação entre o código e o arquivo .rc: Os menus aparecem automaticamente e devem ter uma tag filha <tt><nowiki><text/></nowiki> </tt>, a menos que se refiram aos menus padrão. Actions precisam ser criados manualmente e inseridos no actionCollection () usando o nome no arquivo .rc. Actions podem ser ocultados ou desabilitados, enquanto os menus não.


==CMake==
==CMake==


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''', unlike in the previous tutorials.
Finalmente, o <tt>tutorial3ui.rc</tt> precisa ir a algum lugar onde o KDE possa encontrá-lo (não pode simplesmente deixá-lo no diretório de origem!). '''Isso significa que o projeto precisa ser instalado em algum lugar''', diferente dos tutoriais anteriores.


===CMakeLists.txt===
===CMakeLists.txt===
Line 272: Line 272:


find_package(ECM 1.0.0 REQUIRED NO_MODULE)
find_package(ECM 1.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${ECM_KDE_MODULE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${CMAKE_CURRENT_SOURCE_DIR}/cmake)


include(KDEInstallDirs)
include(KDEInstallDirs)
Line 311: Line 311:
install(FILES tutorial3ui.rc DESTINATION ${KDE_INSTALL_KXMLGUI5DIR}/tutorial3)
install(FILES tutorial3ui.rc DESTINATION ${KDE_INSTALL_KXMLGUI5DIR}/tutorial3)
</syntaxhighlight>
</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>KDE_INSTALL_TARGETS_DEFAULT_ARGS</tt> then the <tt>tutorial3ui.rc</tt> file that describes the layout of the user interface is installed to the application's data directory under <tt>KDE_INSTALL_KXMLGUI5DIR</tt>.
Esse arquivo é quase idêntico ao do tutorial2, mas com duas linhas extras no final que descrevem onde os arquivos devem ser instalados. Primeiramente, o destino do <tt>tutorial3</tt> é instalado no <tt>KDE_INSTALL_TARGETS_DEFAULT_ARGS</tt> e, em seguida, o arquivo <tt>tutorial3ui.rc</tt> que descreve o layout da interface do usuário é instalado no  diretório de dados do aplicativo em <tt>KDE_INSTALL_KXMLGUI5DIR</tt>.


===Make, Install And Run===
===Compilar, Instalar e Executar===


This is probably the trickiest part. Where you install the files, especially <tt>tutorial3ui.rc</tt> is important. Normally, you'd want to install it where KDE software is installed by your distribution, which is usually under {{path|/usr}}. That, however, would require root/admin access and If you don't have that, you can install it to a folder in your home directory.
Esta é provavelmente a parte mais complicada. Onde você instala os arquivos, especialmente o <tt>tutorial3ui.rc</tt> é importante. Normalmente, você deseja instalá-lo onde o  KDE software é instalado pela sua distribuição, que geralmente está em {{path|/usr}}. Isso, no entanto, exigiria acesso root/admin e, se você não tiver, poderá instalá-lo em uma pasta no seu diretório home.


To tell CMake where to install the program, set the <tt>DCMAKE_INSTALL_PREFIX</tt> 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:
Para informar ao CMake onde instalar o programa, defina a opção <tt>DCMAKE_INSTALL_PREFIX</tt>. Você provavelmente só quer instalá-lo em algum local local para teste (provavelmente é um pouco tolo tentar instalar esses tutoriais no diretório do KDE); portanto, o seguinte pode ser apropriado:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
mkdir build && cd build
mkdir build && cd build
Line 323: Line 323:
make install
make install
</syntaxhighlight>
</syntaxhighlight>
which will create a KDE-like directory structure in your user's home directory. Specifically, it will create the directories {{path|$HOME/bin/}} and {{path|$HOME/share/}} and will install the executable to {{path|$HOME/bin/tutorial3}} and the <tt>tutorial3ui.rc</tt> file to {{path|$HOME/share/kxmlgui/tutorial3/tutorial3ui.rc}}.
que criará uma estrutura de diretório semelhante ao KDE no diretório home do usuário. Especificamente, ele criará os diretórios {{path|$HOME/bin/}} e {{path|$HOME/share/}} e instalará o executável em {{path|$HOME/bin/tutorial3}} e o arquivo <tt>tutorial3ui.rc</tt> em  {{path|$HOME/share/kxmlgui/tutorial3/tutorial3ui.rc}}.


However, to be able to run the program properly, you will need to let the system know where the XMLGUI file is. Since we installed it in a nonstandard location, we'll have to explicitly to do so every time. The following command would suffice:
No entanto, para executar o programa corretamente, você deverá informar o sistema onde está o arquivo XMLGUI. Como o instalamos em um local fora do padrão, precisaremos sempre apontar explicitamente. O seguinte comando seria suficiente:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
XDG_DATA_DIRS=$HOME/share:$XDG_DATA_DIRS $HOME/bin/tutorial3
XDG_DATA_DIRS=$HOME/share:$XDG_DATA_DIRS $HOME/bin/tutorial3
</syntaxhighlight>
</syntaxhighlight>
This temporarily adds (prepends) the newly created "share" location to <tt>XDG_DATA_DIRS</tt>, the standard path for application data files.
Isso adiciona(anexa) temporariamente o local do "share" recém-criado a <tt>XDG_DATA_DIRS</tt>, o caminho padrão para os arquivos de dados do aplicativo.


==Moving On==
==Adiante==


Now you can move on to [[Development/Tutorials/Saving_and_loading|saving and loading]].
Agora você pode seguir para [[Development/Tutorials/Saving_and_loading|salvando e carregando]].


Or you can learn [[Development/Tutorial/Icons|how to add icons to your application]].
Ou você pode aprender  [[Development/Tutorial/Icons|como adicionar ícones ao seu aplicativo]].


Or you can learn [[Development/Tutorials/Desktop_File|how to place your application in the K-Menu using .desktop files]].
Ou você pode aprender [[Development/Tutorials/Desktop_File|como colocar seu aplicativo no K-Menu usando arquivos .desktop]].


[[Category:C++]]
[[Category:C++]]

Latest revision as of 16:44, 24 August 2020

Como usar Actions e XMLGUI
Tutorial Series   Tutorial para Iniciantes
Previous   Tutorial 2 - KXmlGuiWindow, Conhecimento básico do XML
What's Next   Tutorial 4 - Saving and loading
Further Reading   None

Resumo

Este tutorial apresenta o conceito de actions. Actions são uma maneira unificada de fornecer ao usuário maneiras de interagir com seu programa.

Por exemplo, se quisermos permitir que o usuário do Tutorial 2 limpe a caixa de texto clicando em um botão na barra de ferramentas, em uma opção no menu Arquivo ou através de um atalho do teclado, ele poderá fazer tudo isso com um QAction.

QAction

Um QAction é um objeto que contém todas as informações sobre o ícone e os atalhos associados a um determinado action. O action é então conectado a um slot que executa o trabalho da sua action.

O Código

main.cpp

#include <cstdlib>
 
#include <QApplication>
#include <QCommandLineParser>

#include <KAboutData>
#include <KLocalizedString>

#include "mainwindow.h"
 
int main (int argc, char *argv[])
{
    QApplication app(argc, argv);
    KLocalizedString::setApplicationDomain("tutorial3");
    
    KAboutData aboutData(
                         // The program name used internally. (componentName)
                         QStringLiteral("tutorial3"),
                         // A displayable program name string. (displayName)
                         i18n("Tutorial 3"),
                         // The program version string. (version)
                         QStringLiteral("1.0"),
                         // Short description of what the app does. (shortDescription)
                         i18n("A simple text area using QAction etc."),
                         // The license this code is released under
                         KAboutLicense::GPL,
                         // Copyright Statement (copyrightStatement = QString())
                         i18n("(c) 2015"),
                         // Optional text shown in the About box.
                         // Can contain any information desired. (otherText)
                         i18n("Some text..."),
                         // The program homepage string. (homePageAddress = QString())
                         QStringLiteral("http://example.com/"),
                         // The bug report email address
                         // (bugsEmailAddress = QLatin1String("[email protected]")
                         QStringLiteral("[email protected]"));
    aboutData.addAuthor(i18n("Name"), i18n("Task"), QStringLiteral("[email protected]"),
                        QStringLiteral("http://your.website.com"), QStringLiteral("OSC Username"));
    KAboutData::setApplicationData(aboutData);
 
    QCommandLineParser parser;
    aboutData.setupCommandLine(&parser);
    parser.process(app);
    aboutData.processCommandLine(&parser);
    
    MainWindow* window = new MainWindow();
    window->show();
    
    return app.exec();
}

Desta vez, muito pouco mudou no main.cpp, apenas o construtor KAboutData foi atualizado para mostrar que agora estamos no tutorial 3.

mainwindow.h

#ifndef MAINWINDOW_H
#define MAINWINDOW_H
 
#include <KXmlGuiWindow>

class KTextEdit;
 
class MainWindow : public KXmlGuiWindow
{
  public:
    explicit MainWindow(QWidget *parent = nullptr);
 
  private:
    KTextEdit* textArea;
    void setupActions();
};
 
#endif

Somente uma função void setupActions() foi adicionada, que fará todo o trabalho de configuração das QActions.

mainwindow.cpp

#include <QApplication>
#include <QAction>

#include <KTextEdit>
#include <KLocalizedString>
#include <KActionCollection>
#include <KStandardAction>

#include "mainwindow.h"

MainWindow::MainWindow(QWidget *parent) : KXmlGuiWindow(parent)
{
  textArea = new KTextEdit();
  setCentralWidget(textArea);
  
  setupActions();
}

void MainWindow::setupActions()
{
    QAction* clearAction = new QAction(this);
    clearAction->setText(i18n("&Clear"));
    clearAction->setIcon(QIcon::fromTheme("document-new"));
    actionCollection()->setDefaultShortcut(clearAction, Qt::CTRL + Qt::Key_W);
    actionCollection()->addAction("clear", clearAction);
    connect(clearAction, SIGNAL(triggered(bool)), textArea, SLOT(clear()));
    
    KStandardAction::quit(qApp, SLOT(quit()), actionCollection());
    
    setupGUI(Default, "tutorial3ui.rc");
}

Explicação

Isso se baseia no código do KXmlGuiWindow do Tutorial 2. A maioria das alterações é no mainwindow.cpp, uma mudança estrutural importante é que o construtor do MainWindow agora chama setupActions() em vez de setupGUI(). setupActions() é o local onde o novo código QAction vai antes de finalmente chamar setupGUI().

Criando o objeto QAction

O QAction é construído em várias etapas. A primeira é a inclusão no cabeçalho do QAction e a criação do QAction:

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

Isso cria um novo QAction chamado clearAction.

Definindo propriedades QAction

Texto

Agora que temos nosso objeto QAction, podemos começar a definir suas propriedades. O código a seguir define o texto que será exibido no menu e com o ícone do QAction na barra de ferramentas, dependendo do estilo do widget (seja ao lado ou abaixo do ícone) ou da configuração (se deseja exibir o texto da ação ou não).

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

Observe que o texto é passado através da função i18n(); isso é necessário para que a interface do usuário seja traduzível (mais informações sobre isso podem ser encontradas no tutorial i18n).

O texto do action deve conter um & porque isso facilita a tradução em idiomas non-latin1. Em japonês, a tradução pode ser ソース(&S) e sem o & no texto em inglês os tradutores não podem saber se precisam adicionar um & ou não.

Ícone

Se o action for exibido em uma barra de ferramentas, é legal ter um ícone representando a ação. O ícone também pode ser exibido ao lado do action nos menus, dependendo do estilo do widget. O código a seguir define o ícone padrão como document-new através do uso da função setIcon():

clearAction->setIcon(QIcon::fromTheme("document-new"));

Atalho do teclado

Definir um atalho do teclado para executar nossa ação é igualmente simples:

actionCollection()->setDefaultShortcut(clearAction, Qt::CTRL + Qt::Key_W);

Isso associa Ctrl + W ao QAction.

Adicionando ao Collection

Para que a ação seja acessada pelo XMLGUI framework( explicada em detalhes posteriormente), ela deve ser adicionada ao action collection do aplicativo. A coleção de ações é acessada através da função actionCollection(), da seguinte forma:

actionCollection()->addAction("clear", clearAction);

Aqui, o QAction clearAction é adicionado à coleção e recebe um nome de clear. Esse nome (clear) é usado pela XMLGUI framework para se referir ao action, portanto, não deve ser localizada, pois é usada apenas internamente.

Conectando ao action

Agora que o action está totalmente configurado, ele precisa estar conectado a algo útil. Nesse caso( porque queremos limpar a área de texto), conectamos nossa action à ação clear() pertencente a um KTextEdit (que, sem surpresa, limpa o KTextEdit)

connect( clearAction, SIGNAL( triggered(bool) ), 
         textArea, SLOT( clear() ) );

KStandardAction

Para ações que provavelmente apareceriam em quase todos os aplicativos do KDE, como 'sair', 'salvar' e 'carregar', existem QActions convenientes pré-criados, acessados através do KStandardAction.

Eles são muito simples de usar. Depois que a biblioteca for incluída (#include <KStandardAction>), basta fornecer o que você deseja que a função faça e a qual QActionCollection será incluído. Por exemplo:

KStandardAction::quit(qApp, SLOT(quit()), actionCollection());

Aqui chamamos o método quit do QApplicaton sempre que o KStandardAction é acionado. Podemos acessar esse método QApplication por meio da macro qApp.

Por fim, isso cria um QAction com o ícone, texto e atalho corretos e até o adiciona ao menu Arquivo.

Adicionando o action a menus e barras de ferramentas

Até o momento, o novo action "Clear" foi criado, mas não foi associado a nenhum menu ou barra de ferramentas. Isso é feito com uma tecnologia do KDE chamada XMLGUI, que faz coisas legais como barras de ferramentas móveis para você.

Definindo seu próprio menu de ajuda

O menu Ajuda foi padronizado para facilitar a vida de desenvolvedores e usuários, e é por isso que todos os menus de Ajuda do software KDE têm a mesma aparência. Se você deseja criar seu próprio menu de ajuda, procure pela explicação sobre o showAboutApplication() na classe KHelpMenu da XMLGUI.

XMLGUI

A função setupGUI() em KXmlGuiWindow depende do sistema XMLGUI para construir a GUI, no qual o XMLGUI faz analizando uma descrição de arquivo XML da interface.

A regra para nomear esse arquivo XML é appnameui.rc, onde appname é o nome que você definiu em KAboutData KAboutData (neste caso, tutorial3). Portanto, em nosso exemplo, o arquivo é chamado tutorial3ui.rc e está localizado no diretório de build. O local onde o arquivo será finalmente colocado é tratado pelo CMake.

arquivo appnameui.rc

Como a descrição da interface do usuário é definida com XML, o layout deve seguir regras estritas. Este tutorial não entrará em detalhes sobre este tópico, mas para obter mais informações, consulte a página detalhada do XMLGUI.

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>
    <Menu >
      <text>A&amp;nother Menu</text>
      <Action name="clear" />
    </Menu >
  </MenuBar>
 
  <ToolBar name="mainToolBar" >
    <text>Main Toolbar</text>
    <Action name="clear" />
  </ToolBar>
 
</gui>

A tag <Toolbar> permite que você descreva a barra de ferramentas, que é a barra na parte superior da janela, normalmente com ícones. Aqui é dado o nome exclusivo mainToolBar e seu nome visível ao usuário definido como Main Toolbar usando a tag <text>. A action clear é adicionada à barra de ferramentas usando a tag <Action>, o parâmetro name nessa tag é a string que foi passada para o KActionCollection com addAction() em mainwindow.cpp.

Além de ter o action na barra de ferramentas, também pode ser adicionado à barra de menus. Aqui a ação está sendo adicionada ao menu File do MenuBar da mesma maneira que foi adicionada à barra de ferramentas.

Altere o atributo 'version' da tag <gui> se você alterou o arquivo .rc desde a última instalação para forçar uma atualização do cache do sistema. Certifique-se de que é um número inteiro, se você usar um valor decimal ele não funcionará, e não notificará . "

Aviso
O atributo version deve sempre ser um número inteiro.


Algumas notas sobre a interação entre o código e o arquivo .rc: Os menus aparecem automaticamente e devem ter uma tag filha <text/> , a menos que se refiram aos menus padrão. Actions precisam ser criados manualmente e inseridos no actionCollection () usando o nome no arquivo .rc. Actions podem ser ocultados ou desabilitados, enquanto os menus não.

CMake

Finalmente, o tutorial3ui.rc precisa ir a algum lugar onde o KDE possa encontrá-lo (não pode simplesmente deixá-lo no diretório de origem!). Isso significa que o projeto precisa ser instalado em algum lugar, diferente dos tutoriais anteriores.

CMakeLists.txt

cmake_minimum_required(VERSION 3.0)

project (tutorial3)

set(QT_MIN_VERSION "5.3.0")
set(KF5_MIN_VERSION "5.2.0")

find_package(ECM 1.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${CMAKE_CURRENT_SOURCE_DIR}/cmake)

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(FeatureSummary)

find_package(Qt5 ${QT_MIN_VERSION} CONFIG REQUIRED COMPONENTS 
    Core    # QCommandLineParser, QStringLiteral
    Widgets # QApplication, QAction
)

find_package(KF5 ${KF5_MIN_VERSION} REQUIRED COMPONENTS
    CoreAddons      # KAboutData
    I18n            # KLocalizedString
    XmlGui          # KXmlGuiWindow, KActionCollection
    TextWidgets     # KTextEdit
    ConfigWidgets   # KStandardActions
)
    

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)
    
set(tutorial3_SRCS main.cpp mainwindow.cpp)

add_executable(tutorial3 ${tutorial3_SRCS})

target_link_libraries(tutorial3
    Qt5::Widgets
    KF5::CoreAddons
    KF5::I18n
    KF5::XmlGui
    KF5::TextWidgets
    KF5::ConfigWidgets
)

install(TARGETS tutorial3  ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
install(FILES tutorial3ui.rc DESTINATION ${KDE_INSTALL_KXMLGUI5DIR}/tutorial3)

Esse arquivo é quase idêntico ao do tutorial2, mas com duas linhas extras no final que descrevem onde os arquivos devem ser instalados. Primeiramente, o destino do tutorial3 é instalado no KDE_INSTALL_TARGETS_DEFAULT_ARGS e, em seguida, o arquivo tutorial3ui.rc que descreve o layout da interface do usuário é instalado no diretório de dados do aplicativo em KDE_INSTALL_KXMLGUI5DIR.

Compilar, Instalar e Executar

Esta é provavelmente a parte mais complicada. Onde você instala os arquivos, especialmente o tutorial3ui.rc é importante. Normalmente, você deseja instalá-lo onde o KDE software é instalado pela sua distribuição, que geralmente está em /usr. Isso, no entanto, exigiria acesso root/admin e, se você não tiver, poderá instalá-lo em uma pasta no seu diretório home.

Para informar ao CMake onde instalar o programa, defina a opção DCMAKE_INSTALL_PREFIX. Você provavelmente só quer instalá-lo em algum local local para teste (provavelmente é um pouco tolo tentar instalar esses tutoriais no diretório do KDE); portanto, o seguinte pode ser apropriado:

mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
make install

que criará uma estrutura de diretório semelhante ao KDE no diretório home do usuário. Especificamente, ele criará os diretórios $HOME/bin/ e $HOME/share/ e instalará o executável em $HOME/bin/tutorial3 e o arquivo tutorial3ui.rc em $HOME/share/kxmlgui/tutorial3/tutorial3ui.rc.

No entanto, para executar o programa corretamente, você deverá informar o sistema onde está o arquivo XMLGUI. Como o instalamos em um local fora do padrão, precisaremos sempre apontar explicitamente. O seguinte comando seria suficiente:

XDG_DATA_DIRS=$HOME/share:$XDG_DATA_DIRS $HOME/bin/tutorial3

Isso adiciona(anexa) temporariamente o local do "share" recém-criado a XDG_DATA_DIRS, o caminho padrão para os arquivos de dados do aplicativo.

Adiante

Agora você pode seguir para salvando e carregando.

Ou você pode aprender como adicionar ícones ao seu aplicativo.

Ou você pode aprender como colocar seu aplicativo no K-Menu usando arquivos .desktop.