Commit 94792162 authored by Thiago Sueto's avatar Thiago Sueto 🐰 Committed by Carl Schwan
Browse files

Step by step hello world

parent 459fd832
......@@ -19,21 +19,34 @@ To get more information about any class you come across, you can use [KDE's API
## The Code
All the code we need will be in one file, `main.cpp`. Create that file with the code below:
### Hello World
{{< readfile file="/content/docs/getting-started/hello_world/main.cpp" highlight="cpp" >}}
All the code we need will be in one file, `main.cpp`. We'll start simple and increment our file as we go further. Create it with the code below:
First we need to create a [QApplication](https://doc.qt.io/qt-5/qapplication.html) object. This needs to be done exactly once in each program since it is needed for things such as [Internationalization](../i18n/). It also should be created before any other KDE Framework or Qt object. A call to [KLocalizedString::setApplicationDomain](docs:ki18n;KLocalizedString::setApplicationDomain) is required to properly set the translation catalog and must be done before the next step happens.
The first KDE Framework specific object we create in this program is [KAboutData](docs:kcoreaddons;KAboutData). This is the class used to store information about the program such as a short description, authors or license information. Pretty much every KDE application should use this class. We then call [KAboutData::setApplicationData](docs:kcoreaddons;KAboutData::setApplicationData) to initialize the properties of the [QApplication ](https://doc.qt.io/qt-5/qapplication.html) object.
{{< readfile file="/content/docs/getting-started/hello_world/main1.cpp" highlight="cpp" >}}
Then we come to [QCommandLineParser ](https://doc.qt.io/qt-5/qcommandlineparser.html). This is the class one would use to specify command line switches to, for example, open the program with a specific file. However, in this tutorial, we simply initialise it with the [KAboutData](docs:kcoreaddons;KAboutData) object we created so we can use the --version or --author switches.
First we need to create a [QApplication](https://doc.qt.io/qt-5/qapplication.html) object. It needs to be created exactly once and before any other KDE Framework or Qt object, as it's the starting point for creating your application and thus required for other components, like [Internationalization](../i18n/).
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 [KGuiItem](docs:kwidgetsaddons;KGuiItem) object. The first argument in the [KGuiItem](docs:kwidgetsaddons;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 `QString()`. 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.
We're going to create a popup box but we're going to customise one of the buttons by creating a [KGuiItem](docs:kwidgetsaddons;KGuiItem) object. The first argument of the [KGuiItem](docs:kwidgetsaddons;KGuiItem) constructor is the text that will appear on the item (in our case, a button object to be used soon). Then we have the option to set an icon for the button, but for now we don't want one so we can just give it a `QString()`, which is just a null [QString](https://doc.qt.io/qt-5/qstring.html). We then set the tooltip (what appears when you hover over an item), and finally the "What's This?" text (accessed through right-clicking or Shift-F1).
Now we have our item, we can create our popup. We call the [KMessageBox::questionYesNo](docs:kwidgetsaddons;KMessageBox::questionYesNo) 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 KGuiItem yesButton we created.
Now that we have our item, we can create our popup. We call the [KMessageBox::questionYesNo](docs:kwidgetsaddons;KMessageBox::questionYesNo) function which, by default, creates a message box with a "Yes" and a "No" button. The first argument is the parent widget of the [KMessageBox](docs:kwidgetsaddons;KMessageBox), but since we are just using a ternary operator to ask whether our message box returns yes, we do not need to specify the parent, so we can use 0, nullptr or NULL instead. The second argument is the text that will appear inside the message box and above the buttons. The third is the caption shown in the window's titlebar, and then we set the [KGuiItem](docs:kwidgetsaddons;KGuiItem) for (what would normally be) the "Yes" button to the KGuiItem yesButton we created.
Note that all user-visible text is passed through the `i18n()` function; this is necessary for the UI to be translatable. More information on internalization can be found in the [i18n](https://techbase.kde.org/Localization) tutorial.
### About and Internationalization
{{< readfile file="/content/docs/getting-started/hello_world/main2.cpp" highlight="cpp" >}}
For your application to be localized, it must first be internationalized, that is, you must prepare your code for it to be localized later. For that, we start with a call to [KLocalizedString::setApplicationDomain](docs:ki18n;KLocalizedString::setApplicationDomain) is required to properly set the translation catalog and must be done before everything else (except QApplication). After that, we can just start enveloping the relevant user-visible strings with `i18n()`. The non-user visible strings that should be kept as-is (that is, read only) should use a [QStringLiteral](https://doc.qt.io/qt-5/qstring.html#QStringLiteral). We'll use those next with [KAboutData](docs:kcoreaddons;KAboutData).
More information on internalization can be found in the [i18n](https://techbase.kde.org/Localization) tutorial.
[KAboutData](docs:kcoreaddons;KAboutData) is a core KDE Frameworks component that stores information about an application, which can then be reused by many other KDE Frameworks components. We instantiate a new [KAboutData](docs:kcoreaddons;KAboutData) object with its fairly complete default constructor and add author information. After all the required information has been set, we call [KAboutData::setApplicationData](docs:kcoreaddons;KAboutData::setApplicationData) to initialize the properties of the [QApplication ](https://doc.qt.io/qt-5/qapplication.html) object.
### Command line
{{< readfile file="/content/docs/getting-started/hello_world/main3.cpp" highlight="cpp" >}}
Then we come to [QCommandLineParser ](https://doc.qt.io/qt-5/qcommandlineparser.html). This is the class one would use to specify command line flags to, for example, open the program with a specific file. However, in this tutorial, we simply initialise it with the [KAboutData](docs:kcoreaddons;KAboutData) object we created before so we can use the `--version` or `--author` flags that are provided by default by Qt.
We're all done as far as the code is concerned. Now to build it and try it out.
......
#include <QApplication>
#include <KMessageBox>
int main (int argc, char *argv[])
{
QApplication app(argc, argv);
KGuiItem yesButton("Hello", QString(),
"This is a tooltip",
"This is a WhatsThis help text.");
return KMessageBox::questionYesNo(0, "Hello World", "Hello", yesButton)
== KMessageBox::Yes? EXIT_SUCCESS: EXIT_FAILURE;
}
#include <QApplication>
#include <KMessageBox>
#include <KAboutData>
#include <KLocalizedString>
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) 2021"),
// 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("submit@bugs.kde.org")
QStringLiteral("submit@bugs.kde.org"));
aboutData.addAuthor(i18n("Name"), i18n("Author Role"), QStringLiteral("your@email.com"),
QStringLiteral("http://your.website.com"), QStringLiteral("OCS Username"));
KAboutData::setApplicationData(aboutData);
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;
}
#include <QApplication>
#include <KMessageBox>
#include <KAboutData>
#include <KLocalizedString>
#include <QCommandLineParser>
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) 2021"),
// 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("submit@bugs.kde.org")
QStringLiteral("submit@bugs.kde.org"));
aboutData.addAuthor(i18n("Name"), i18n("Author Role"), QStringLiteral("your@email.com"),
QStringLiteral("http://your.website.com"), QStringLiteral("OCS 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;
}
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment