mauikit-filebrowsing/docs/quickstart.md

0001 Quick start tutorial {#quickstart}
0002 ===================
0003
0004 ## Setup
0005
0006 For this guide we will create an image tagging editor, for this purpose will be using most of the MauiKit File Browsing controls and some of the classes.
0007
0008 Our project file structure consists for now of only three file: `main.cpp`, `main.qml` and `CMakeLists.txt`
0009
0010 The starting point is to setup the CMakeLists file by linking to `MauiKitFileBrowsing4` library and its dependencies.
0011
0012 First, to find the needed files for the package one could use the line `find_package(MauiKitFileBrowsing4)`, but given we will also be using MauiKit4 core controls, instead we will use the following components syntax `find_package(MauiKit4 REQUIRED COMPONENT FileBrowsing)`, so both packages can be found and linked- the CMake file would look something like this:
0013
0014     cmake_minimum_required(VERSION 3.14)
0015
0016     project(MuTag VERSION 0.1 LANGUAGES CXX)
0017
0018     set(CMAKE_AUTOMOC ON)
0019     set(CMAKE_CXX_STANDARD_REQUIRED ON)
0020
0021     find_package(ECM NO_MODULE)
0022     set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${ECM_MODULE_PATH})
0023
0024     find_package(Qt6 REQUIRED COMPONENTS Quick Qml)
0025     find_package(KF6 COMPONENTS I18n CoreAddons)
0026     find_package(MauiKit4 REQUIRED COMPONENTS FileBrowsing)
0027
0028     qt_add_executable(${PROJECT_NAME}App
0029         main.cpp)
0030
0031     qt_add_qml_module(${PROJECT_NAME}App
0032         URI ${PROJECT_NAME}
0033         VERSION 1.0
0034         QML_FILES main.qml)
0035
0036     target_link_libraries(${PROJECT_NAME}App
0037         PRIVATE
0038         Qt6::Quick
0039         Qt6::Qml
0040         MauiKit4
0041         MauiKit4::FileBrowsing
0042         KF6::I18n
0043         KF6::CoreAddons)
0044
0045     install(TARGETS ${PROJECT_NAME}App
0046         BUNDLE DESTINATION .
0047         LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
0048
0049
0050 The next step is to setup the main entry point with the information about the application. Take a look at the `main.cpp` source file:
0051
0052     #include <QQmlApplicationEngine>
0053     #include <QQmlContext>
0054
0055     #include <QGuiApplication>
0056     #include <QIcon>
0057
0058     #include <KLocalizedString>
0059     #include <KAboutData>
0060
0061     #include <MauiKit3/Core/mauiapp.h>
0062
0063     int main(int argc, char *argv[])
0064     {
0065         QGuiApplication app(argc, argv);
0066
0067         app.setOrganizationName(QStringLiteral("Maui"));
0068         app.setWindowIcon(QIcon(":/assets/mauidemo.svg"));
0069
0070         KLocalizedString::setApplicationDomain("MuTag");
0071         KAboutData about(QStringLiteral("MuTag"),
0072                         i18n("MuTag"),
0073                         "3.0.0",
0074                         i18n("Music Files Tagging."),
0075                         KAboutLicense::LGPL_V3); //here you can set information about the application, which will be fetched by the about dialog.
0076
0077         about.addAuthor(i18n("Camilo Higuita"), i18n("Developer"), QStringLiteral("milo.h@aol.com"));
0078         about.setHomepage("https://mauikit.org");
0079         about.setProductName("maui/mutag");
0080         about.setBugAddress("https://invent.kde.org/camiloh/mutag/-/issues");
0081         about.setOrganizationDomain("org.mutag.app");
0082         about.setProgramLogo(app.windowIcon());
0083         about.addComponent("MauiKit File Browsing");
0084
0085         KAboutData::setApplicationData(about);
0086
0087         MauiApp::instance()->setIconName("qrc:/assets/mauidemo.svg"); // this not only sets the path to the icon file asset, but also takes care of initializing the MauiApp singleton instance.
0088
0089         QQmlApplicationEngine engine;
0090         const QUrl url(u"qrc:/MuTag/main.qml"_qs);
0091         QObject::connect(&engine, &QQmlApplicationEngine::objectCreated,
0092             &app, [url](QObject *obj, const QUrl &objUrl) {
0093                 if (!obj && url == objUrl)
0094                     QCoreApplication::exit(-1);
0095             }, Qt::QueuedConnection);
0096
0097         engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
0098
0099         engine.load(url);
0100
0101         return app.exec();
0102     }
0103
0104 In the code snippet above the information about the application is done using the KDE framework KCoreAddons module `KAboutData`. And another important part is to initialize the MauiKit Application instance, so the styling and other parts work correctly, this is done by calling the `MauiApp::instance()` singleton instance with `MauiApp::instance()->setIconName()`.
0105
0106 The next steps will take care of loading our main QML file `main.qml`:
0107
0108     import org.mauikit.controls as Maui
0109
0110     Maui.ApplicationWindow
0111     {
0112         id: root
0113
0114         Maui.Page
0115         {
0116             anchors.fill: parent
0117             Maui.Controls.showCSD: true
0118         }
0119     }
0120
0121 ## The App Requirements
0122 Next step will be to stablish what is the application roles and what building blocks it needs top achieve its main tasks.
0123
0124 The requirements for this demo app are:
0125 - Add, edit and remove tags to any image file selected
0126 - List all the tags
0127 - List all the images associated to a selected tag
0128
0129 To achieve these, the main page of our application will look something like the following image. Where the user can select an existing tag to list all the image files associated to it, or to click on a button to launch a `FileDialog` to select a new image to edit or add new tags to it. So far, the application will have to pages, one for tag browsing an another for the image tags editing.
0130
0131