Development/Tutorials/Using KXmlGuiWindow/pt-br

Como usar a KXmlGuiWindow

Tutorial Series	Tutorial para Iniciantes
Previous	Tutorial 1 - Hello World
What's Next	Tutorial 3 - QActions and XMLGUI
Further Reading	KXmlGuiWindow

Resumo

Este tutorial incrementa o First Program Tutorial e apresentará a classe KXmlGuiWindow.

No tutorial anterior o programa fez aparecer uma caixa de diálogo, então vamos dar passos no sentido de criar um aplicativo funcional.

KXmlGuiWindow

A KXmlGuiWindow fornece uma visualização completa da janela principal com menus, barras de ferramentas, uma barra de status e uma área principal no centro para um widget grande. Por exemplo, o menu de ajuda é predefinido. A maioria dos aplicativos KDE deriva dessa classe, pois fornece uma maneira fácil de definir layouts de menus e barras de ferramentas por meio de arquivos XML (essa tecnologia é chamada XMLGUI e faz parte da estrutura KF5::XmlGui). Embora não utilizemos XMLGUI neste tutorial, vamos usá-lo no próximo.

Para ter uma KXmlGuiWindow útil, precisamos criar uma subclasse. Então, criamos dois arquivos, um mainwindow.cpp e um mainwindow.h que conterão nosso código.

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;
};
 
#endif

Primeiro derivamos uma subclasse KXmlGuiWindow com class MainWindow : public KXmlGuiWindow e depois declaramos o construtor com MainWindow(QWidget * parent = nullptr); .

E, finalmente, declaramos um ponteiro para o objeto que vai compor a maior parte do nosso programa. O KTextEdit é um widget genérico de editor de texto rico com alguns detalhes, como ocultar automaticamente o cursor.

mainwindow.cpp

#include "mainwindow.h"

#include <KTextEdit>

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

Primeiramente, é claro, temos que incluir o arquivo de cabeçalho que contém a declaração de classe.

Inicializamos nosso editor de texto com um objeto e usamos a função interna do KXmlGuiWindow setCentralWidget(), que informa ao KXmlGuiWindow o que deve aparecer na seção central da janela.

Finalmente, o KXmlGuiWindow::setupGUI() é chamado, o que faz um monte de coisas nos bastidores e cria as barras de menu padrão(Configurações, Ajuda).

Back to main.cpp

In order to actually run this window, we need to add a few lines in main.cpp:

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("tutorial2");
    
    KAboutData aboutData(
                         // The program name used internally. (componentName)
                         QStringLiteral("tutorial2"),
                         // A displayable program name string. (displayName)
                         i18n("Tutorial 2"),
                         // The program version string. (version)
                         QStringLiteral("1.0"),
                         // Short description of what the app does. (shortDescription)
                         i18n("A simple text area"),
                         // 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();
}

Again, we include our new header file in order to create our MainWindow object which we then display.

CMake

The best way to build the program is to use CMake. We add mainwindow.cpp to the sources list, include the XmlGui and TextWidgets (for KTextEdit) frameworks, and replace all tutorial1 text to tutorial2.

CMakeLists.txt

cmake_minimum_required(VERSION 3.0)

project (tutorial2)

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 
)

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

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

add_executable(tutorial2 ${tutorial2_SRCS})

target_link_libraries(tutorial2
    Qt5::Widgets
    KF5::CoreAddons
    KF5::I18n
    KF5::XmlGui
    KF5::TextWidgets
)

install(TARGETS tutorial2  ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Compile and run

The best way to compile, link and run it is to set up a correct build environment. But for a simple tutorial like this, it's enough to just create a build directory and build from there. This command takes cafe of all of that in one line:

mkdir build && cd build && cmake .. && make && ./tutorial2

Moving On

Now you can move on to Using Actions.