Development/Tutorials/First program/pt-br: Difference between revisions

From KDE TechBase
No edit summary
(Updating to match new version of source page)
 
(26 intermediate revisions by one other user not shown)
Line 23: Line 23:
{{Tip (pt BR)|Para obter mais informações sobre qualquer classe que você encontre, você pode usar o mecanismo de busca 'kde'. Por exemplo, para procurar por informações sobre KMessageBox, apenas digite "kde:kmessagebox" no Konqueror, Rekonq ou KRunner, e você será levado para a documentação.}}
{{Tip (pt BR)|Para obter mais informações sobre qualquer classe que você encontre, você pode usar o mecanismo de busca 'kde'. Por exemplo, para procurar por informações sobre KMessageBox, apenas digite "kde:kmessagebox" no Konqueror, Rekonq ou KRunner, e você será levado para a documentação.}}


<div class="mw-translate-fuzzy">
{{Tip (pt_BR)|
{{Tip|
Você pode querer usar [[Special:myLanguage/KDevelop|KDevelop]] ou [[Special:myLanguage/qtcreator|QtCreator]] como IDE para seus projetos.
Você pode querer usar [[qtcreator|QtCreator]] como IDE para seus projetos.
}}
}}
</div>


==O código==
==O Código==


<div class="mw-translate-fuzzy">
Todo o código que precisamos estará em um arquivo, <tt>main.cpp</tt>. Crie esse arquivo com o código abaixo:
Todo o código que precisamos estará em um arquivo, <tt>main.cpp</tt>. Crie esse arquivo com o código abaixo:
<syntaxhighlight lang="cpp-qt">
#include <cstdlib>
</div>


<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
Line 91: Line 85:
</syntaxhighlight>
</syntaxhighlight>


First we need to create a [http://doc.qt.io/qt-5/qapplication.html QApplication] object. This needs to be done exactly once in each program since it is needed for things such as [[Development/Tutorials/Localization/i18n|i18n]]. It also should be created before any other KDE Framework or Qt object. A call to {{class|KLocalizedString}}::setApplicationDomain() is required to properly set the translation catalog and must be done before the next step happens.
Primeiro, precisamos criar um objeto [http://doc.qt.io/qt-5/qapplication.html QApplication]. Isso precisa ser feito exatamente uma vez em cada programa, pois é necessário para coisas como [[Development/Tutorials/Localization/i18n|i18n]]. Também deve ser criado antes de qualquer outro KDE Framework ou Qt object. Uma chamada para {{class|KLocalizedString}}::setApplicationDomain() é necessária para configurar corretamente o catálogo de traduções e deve ser feita antes que a próxima etapa aconteça.


<div class="mw-translate-fuzzy">
O primeiro objeto específico do KDE Framework que criamos neste programa é o {{class|KAboutData}}. Essa é a classe usada para armazenar informações sobre o programa, como uma breve descrição, autores ou informações de licença. Praticamente todos os aplicativos do KDE devem usar esta classe. Em seguida, chamamos {{class|KAboutData}}::setApplicationData() para inicializar as propriedades do objeto [http://doc.qt.io/qt-5/qapplication.html QApplication].
Então chegamos a {{class|KCmdLineArgs}}. Essa é a classe que se usaria para especificar uma linha de comando para, por exemplo, abrir o programa com um arquivo específico. No entanto, nesse tutorial, nós simplesmente iniciamos com o objeto {{class|KAboutData}} que nós criamos então podemos usar <tt>--version</tt> ou <tt>--author</tt>.
</div>


<div class="mw-translate-fuzzy">
Então chegamos ao  [http://doc.qt.io/qt-5/qcommandlineparser.html QCommandLineParser]. Essa é a classe que você usaria para especificar opções de linha de comando para, por exemplo, abrir o programa com um arquivo específico. No entanto, neste tutorial, simplesmente o inicializamos com o objeto {{class|KAboutData}} que criamos para que possamos usar as opções  <tt>--version</tt> or <tt>--author</tt>.
Assim criamos um objeto {{class|KApplication}}. Isso precisa ser feito uma vez em cada programa, já que é necessário para coisas como [[Development/Tutorials/Localization/i18n|i18n]].
</div>


Now we've done all the necessary setup, we can move on to doing interesting things with our application. We're going to create a popup box but we're going to customise one of the buttons. To do this customisation, we need to use a {{class|KGuiItem}} object. The first argument in the {{class|KGuiItem}} constructor is the text that will appear on the item (in our case, a button). Then we have an option of setting an icon for the button but we don't want one so we just give it <tt>QString()</tt>. We then set the tooltip (what appears when you hover over an item) and finally the "What's This?" (accessed through right-clicking or Shift-F1) text.
Agora que fizemos toda a configuração necessária, podemos passar a fazer coisas interessantes com nosso aplicativo. Vamos criar uma pop-up box, mas vamos personalizar um dos botões. Para fazer essa personalização, precisamos usar um objeto  {{class|KGuiItem}}. O primeiro argumento no construtor {{class|KGuiItem}} é o texto que aparecerá no item (no nosso caso, um botão). Então temos a opção de definir um ícone para o botão, mas não queremos um, apenas fornecemos <tt>QString()</tt>. Em seguida, definimos a tooltip (é o que aparece quando você passa o mouse sobre um item) e, finalmente, o "What's This?"(acessado com o botão direito do mouse ou Shift-F1).


Now we have our item, we can create our popup. We call the <tt>{{class|KMessageBox}}::questionYesNo()</tt> function which, by default, creates a message box with a "Yes" and a "No" button. The second argument is the text that will appear in the message box above the buttons. The third is the caption the window will have and finally, we set the KGuiItem for (what would normally be) the "Yes" button to the <tt>KGuiItem yesButton</tt> we created.
Agora que temos o nosso item, podemos criar nosso pop-up. Chamamos a função <tt>{{class|KMessageBox}}::questionYesNo()</tt> que, por padrão, cria uma message box com os botões "Yes" e "No". O segundo argumento é o texto que aparecerá na message box acima dos botões. A terceira é a legenda que a janela terá e, finalmente, definimos o KGuiItem para (o que normalmente seria) o botão "Yes" para o  <tt>KGuiItem yesButton</tt> que criamos.


Note that all user-visible text is passed through the i18n() function; this is necessary for the UI to be translatable. More information on localization can be found in the [[Special:myLanguage/Development/Tutorials/Localization/i18n|localization tutorial]].
Observe que todo o texto visível ao usuário é passado através da função i18n(); isso é necessário para que a UI seja traduzível. Mais informações sobre localização podem ser encontradas em [[Special:myLanguage/Development/Tutorials/Localization/i18n|localization tutorial]].


We're all done as far as the code is concerned. Now to build it and try it out.
Tudo foi feito no que diz respeito ao código. Agora, compile e experimente.


== Build ==
== Compilação ==


You want to [[Special:myLanguage/Development/Tutorials/CMake|use CMake]] for your build environment. You provide a file {{Path|CMakeLists.txt}}, CMake uses this file to generate all Makefiles out of it.
Você deve [[Special:myLanguage/Development/Tutorials/CMake|usar o CMake]] para o seu ambiente de compilação. Forneça um arquivo {{Path|CMakeLists.txt}}, o CMake usa esse arquivo para gerar todos os Makefiles a partir dele.


=== CMakeLists.txt ===
=== CMakeLists.txt ===


Create a file named {{Path|CMakeLists.txt}} in the same directory as {{Path|main.cpp}} with this content:
Crie um arquivo chamado {{Path|CMakeLists.txt}} no mesmo diretório que o {{Path|main.cpp}} com este conteúdo:


<syntaxhighlight lang="cmake">
<syntaxhighlight lang="cmake">
Line 126: Line 116:


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 162: Line 152:
</syntaxhighlight>
</syntaxhighlight>


The <tt>find_package()</tt> function locates the package that you ask it for (in this case ECM, Qt5, or KF5) and sets some variables describing the location of the package's headers and libraries. ECM, or Extra CMake Modules, is required to import special CMake files and functions for building KDE applications.
A função <tt>find_package()</tt> localiza o pacote solicitado(neste caso, ECM, Qt5 ou KF5) e define algumas variáveis que descrevem a localização dos cabeçalhos do pacote e bibliotecas. O ECM, ou Extra CMake Modules, é necessário para importar arquivos e funções especiais do CMake para criar aplicativos KDE.


Here we try to find the modules for Qt 5 and KDE Frameworks 5 required to build our tutorial. The necessary files are included by CMake so that the compiler can see them at build time. Minimum version numbers are set at the very top of CMakeLists.txt file for easier reference.
Aqui tentamos encontrar os módulos para o Qt 5 e o KDE Frameworks 5 necessários para compilar nosso tutorial. Os arquivos necessários são incluídos pelo CMake para que o compilador possa vê-los no momento da criação. Os números mínimos de versão são definidos na parte superior do arquivo CMakeLists.txt para facilitar a referência


Next we create a variable called <tt>tutorial1_SRCS</tt> using the <tt>set()</tt> function. In this case we simply set it to the name of our only source file.
Em seguida, criamos uma variável chamada <tt>tutorial1_SRCS</tt> usando a função <tt>set()</tt>. Nesse caso, simplesmente a definimos como o nome do nosso único arquivo de origem.


Then we use <tt>add_executable()</tt> to create an executable called <tt>tutorial1</tt> from the source files listed in our <tt>tutorial1_SRCS</tt> variable. Afterwards, we link our executable to the necessary libraries using <tt>target_link_libraries()</tt> function. The line starting with <tt>install</tt> writes a default "install" target into the Makefile.
Então usamos <tt>add_executable()</tt> para criar um executável chamado <tt>tutorial1</tt> a partir dos arquivos fontes listados em nossa variável <tt>tutorial1_SRCS</tt>. Depois, linkar nosso executável às bibliotecas necessárias usando a função <tt>target_link_libraries()</tt>. A linha que começa com <tt>install</tt> grava um destino "install" padrão no Makefile.


=== Make And Run ===
=== Make And Run ===


To compile, link and install your program, you must have several software installed, e.g. cmake, make and gcc-c++, and the Qt 5 and KDE Frameworks development files. To be sure you have everything, best follow [https://community.kde.org/Get_Involved/development#One-time_setup:_your_development_environment this install guide].
Para compilar, linkar e instalar seu programa, você deve ter vários softwares instalados, por exemplo cmake, make e gcc-c++, o Qt 5 e os arquivos de desenvolvimento KDE Frameworks. Para ter certeza de que você tem tudo, é melhor seguir para[https://community.kde.org/Get_Involved/development#One-time_setup:_your_development_environment esse guia de instalação].


While you can run '''CMake''' directly inside the source code directory itself, it is a best practice, and actually enforced in some KDE software, to use a separate build directory and run '''CMake''' from there:
Embora você possa executar o '''CMake''' diretamente dentro do diretório do código-fonte em si, é uma boa prática e altamente recomendável em alguns softwares do KDE usar um diretório de compilação separado e executar '''CMake''' a partir daí:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
Line 184: Line 174:
</syntaxhighlight>
</syntaxhighlight>


And launch it with:
E executar com:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
Line 190: Line 180:
</syntaxhighlight>
</syntaxhighlight>


==Moving On==
==Adiante==


Now you can move on to [[Special:myLanguage/Development/Tutorials/Using_KXmlGuiWindow|using KXmlGuiWindow]].
Agora você pode seguir para [[Special:myLanguage/Development/Tutorials/Using_KXmlGuiWindow|usando o KXmlGuiWindow]].


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

Latest revision as of 16:44, 24 August 2020


Olá Mundo
Tutorial Series   Tutorial para Iniciantes
Previous   C++, Qt, Building KDE
What's Next   Tutorial 2 - KXmlGuiWindow
Further Reading   CMake

Resumo

Seu primeiro programa deve cumprimentar o mundo com um amigável "Hello World", e o que mais? Para isso, usaremos uma classe KMessageBox e personalizaremos um dos botões.


Dica
Para obter mais informações sobre qualquer classe que você encontre, você pode usar o mecanismo de busca 'kde'. Por exemplo, para procurar por informações sobre KMessageBox, apenas digite "kde:kmessagebox" no Konqueror, Rekonq ou KRunner, e você será levado para a documentação.



Dica
Você pode querer usar KDevelop ou QtCreator como IDE para seus projetos.


O Código

Todo o código que precisamos estará em um arquivo, main.cpp. Crie esse arquivo com o código abaixo:

#include <QApplication>
#include <QCommandLineParser>
#include <KAboutData>
#include <KLocalizedString>
#include <KMessageBox>

int main (int argc, char *argv[])
{
    QApplication app(argc, argv);
    KLocalizedString::setApplicationDomain("tutorial1");

    
    KAboutData aboutData(
                         // The program name used internally. (componentName)
                         QStringLiteral("tutorial1"),
                         // A displayable program name string. (displayName)
                         i18n("Tutorial 1"),
                         // The program version string. (version)
                         QStringLiteral("1.0"),
                         // Short description of what the app does. (shortDescription)
                         i18n("Displays a KMessageBox popup"),
                         // 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);
    
    KGuiItem yesButton( i18n( "Hello" ), QString(),
                        i18n( "This is a tooltip" ),
                        i18n( "This is a WhatsThis help text." ) );

return 
        KMessageBox::questionYesNo 
        (0, i18n( "Hello World" ), i18n( "Hello" ), yesButton ) 
        == KMessageBox::Yes? EXIT_SUCCESS: EXIT_FAILURE;
}

Primeiro, precisamos criar um objeto QApplication. Isso precisa ser feito exatamente uma vez em cada programa, pois é necessário para coisas como i18n. Também deve ser criado antes de qualquer outro KDE Framework ou Qt object. Uma chamada para KLocalizedString::setApplicationDomain() é necessária para configurar corretamente o catálogo de traduções e deve ser feita antes que a próxima etapa aconteça.

O primeiro objeto específico do KDE Framework que criamos neste programa é o KAboutData. Essa é a classe usada para armazenar informações sobre o programa, como uma breve descrição, autores ou informações de licença. Praticamente todos os aplicativos do KDE devem usar esta classe. Em seguida, chamamos KAboutData::setApplicationData() para inicializar as propriedades do objeto QApplication.

Então chegamos ao QCommandLineParser. Essa é a classe que você usaria para especificar opções de linha de comando para, por exemplo, abrir o programa com um arquivo específico. No entanto, neste tutorial, simplesmente o inicializamos com o objeto KAboutData que criamos para que possamos usar as opções --version or --author.

Agora que fizemos toda a configuração necessária, podemos passar a fazer coisas interessantes com nosso aplicativo. Vamos criar uma pop-up box, mas vamos personalizar um dos botões. Para fazer essa personalização, precisamos usar um objeto KGuiItem. O primeiro argumento no construtor KGuiItem é o texto que aparecerá no item (no nosso caso, um botão). Então temos a opção de definir um ícone para o botão, mas não queremos um, apenas fornecemos QString(). Em seguida, definimos a tooltip (é o que aparece quando você passa o mouse sobre um item) e, finalmente, o "What's This?"(acessado com o botão direito do mouse ou Shift-F1).

Agora que temos o nosso item, podemos criar nosso pop-up. Chamamos a função KMessageBox::questionYesNo() que, por padrão, cria uma message box com os botões "Yes" e "No". O segundo argumento é o texto que aparecerá na message box acima dos botões. A terceira é a legenda que a janela terá e, finalmente, definimos o KGuiItem para (o que normalmente seria) o botão "Yes" para o KGuiItem yesButton que criamos.

Observe que todo o texto visível ao usuário é passado através da função i18n(); isso é necessário para que a UI seja traduzível. Mais informações sobre localização podem ser encontradas em localization tutorial.

Tudo foi feito no que diz respeito ao código. Agora, compile e experimente.

Compilação

Você deve usar o CMake para o seu ambiente de compilação. Forneça um arquivo CMakeLists.txt, o CMake usa esse arquivo para gerar todos os Makefiles a partir dele.

CMakeLists.txt

Crie um arquivo chamado CMakeLists.txt no mesmo diretório que o main.cpp com este conteúdo:

cmake_minimum_required(VERSION 3.0)

project (tutorial1)

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 Qt modules
find_package(Qt5 ${QT_MIN_VERSION} CONFIG REQUIRED COMPONENTS 
    Core    # QCommandLineParser, QStringLiteral
    Widgets # QApplication 
)

# Find KDE modules
find_package(KF5 ${KF5_MIN_VERSION} REQUIRED COMPONENTS
    CoreAddons      # KAboutData
    I18n            # KLocalizedString
    WidgetsAddons   # KMessageBox
)

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)
    
set(tutorial1_SRCS main.cpp)

add_executable(tutorial1 ${tutorial1_SRCS})

target_link_libraries(tutorial1
    Qt5::Widgets
    KF5::CoreAddons
    KF5::I18n
    KF5::WidgetsAddons
)

install(TARGETS tutorial1  ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

A função find_package() localiza o pacote solicitado(neste caso, ECM, Qt5 ou KF5) e define algumas variáveis que descrevem a localização dos cabeçalhos do pacote e bibliotecas. O ECM, ou Extra CMake Modules, é necessário para importar arquivos e funções especiais do CMake para criar aplicativos KDE.

Aqui tentamos encontrar os módulos para o Qt 5 e o KDE Frameworks 5 necessários para compilar nosso tutorial. Os arquivos necessários são incluídos pelo CMake para que o compilador possa vê-los no momento da criação. Os números mínimos de versão são definidos na parte superior do arquivo CMakeLists.txt para facilitar a referência

Em seguida, criamos uma variável chamada tutorial1_SRCS usando a função set(). Nesse caso, simplesmente a definimos como o nome do nosso único arquivo de origem.

Então usamos add_executable() para criar um executável chamado tutorial1 a partir dos arquivos fontes listados em nossa variável tutorial1_SRCS. Depois, linkar nosso executável às bibliotecas necessárias usando a função target_link_libraries(). A linha que começa com install grava um destino "install" padrão no Makefile.

Make And Run

Para compilar, linkar e instalar seu programa, você deve ter vários softwares instalados, por exemplo cmake, make e gcc-c++, o Qt 5 e os arquivos de desenvolvimento KDE Frameworks. Para ter certeza de que você tem tudo, é melhor seguir paraesse guia de instalação.

Embora você possa executar o CMake diretamente dentro do diretório do código-fonte em si, é uma boa prática e altamente recomendável em alguns softwares do KDE usar um diretório de compilação separado e executar CMake a partir daí:

mkdir build && cd build

You can invoke CMake and make manually:

cmake .. && make

E executar com:

./tutorial1

Adiante

Agora você pode seguir para usando o KXmlGuiWindow.