Development/Tutorials/Using Actions/pt-br

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á . "

Warning

The version attribute must always be an integer number.

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, unlike in the previous tutorials.

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} ${ECM_KDE_MODULE_DIR} ${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)

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 KDE_INSTALL_TARGETS_DEFAULT_ARGS then the tutorial3ui.rc file that describes the layout of the user interface is installed to the application's data directory under KDE_INSTALL_KXMLGUI5DIR.

Make, Install And Run

This is probably the trickiest part. Where you install the files, especially tutorial3ui.rc is important. Normally, you'd want to install it where KDE software is installed by your distribution, which is usually under /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.

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

which will create a KDE-like directory structure in your user's home directory. Specifically, it will create the directories $HOME/bin/ and $HOME/share/ and will install the executable to $HOME/bin/tutorial3 and the tutorial3ui.rc file to $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:

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

This temporarily adds (prepends) the newly created "share" location to XDG_DATA_DIRS, the standard path for application data files.

Moving On

Now you can move on to saving and loading.

Or you can learn how to add icons to your application.

Or you can learn how to place your application in the K-Menu using .desktop files.