File indexing completed on 2024-12-22 04:31:09

 /*
  * <one line to give the program's name and a brief idea of what it does.>
  * Copyright (C) 2019  camilo <chiguitar@unal.edu.co>
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation, either version 3 of the License, or
  * (at your option) any later version.
  *
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
 #pragma once
 
 #include <QObject>
  #include <QQmlEngine>
 #include "fmh.h"
 
 #include "mauikit_export.h"
 
 #include <QQmlParserStatus>
 
 /**
  * @brief MauiList class.
  * 
  * A helper class for easily setting up a list model to be feed into MauiModel::list, and to be used by the browsing views in Mauikit controls.
  * 
  * @warning This method of setting up a data model is very limited by the lingo supported by the FMH::MODEL_KEY dictionary.
  * So only consider using this class if your data model structure is based on only string text and can be represented by the FMH::MODEL_KEY dictionary entries. 
  * @see FMH::MODEL_KEY
  * 
  * This inherits from the QQmlParserStatus class, so t can be aware of its creation status in the QML engine. This is useful to lazy-loading parts when needed, as when the component presenting the data model is ready and loaded.
  * 
  * The list generated by sub-classing MauiList is meant to be used as the list for the MauiModel class, exposed to QML as the `BaseModel` type. The MauiModel supports features, such as filtering and sorting.
  * @see MauiModel
  * 
  * @image html Misc/listbrowser_data.png
  * 
  * @section example Example
  * This is a simple example of a MauiList based data model.
  * 
  * First wee need to setup the MauiList data. In the example below the data is manually added. The data must be modeled using the FMH::MODEL_LIST, which is an array list of FMH::MODEL, which is a map of key pairs, where the key must be a FMH::MODEL_KEY enum type, and the value a string text.
  * 
  * @code 
  * #pragma once
  * 
  * #include <QObject>
  * #include <MauiKit4/Core/mauilist.h>
  * 
  * class PlantsList : public MauiList
  * {
  *    Q_OBJECT
  * public:
  *    PlantsList(QObject *parent = nullptr);
  * 
  *    // QQmlParserStatus interface
  *    void componentComplete();
  * 
  *    // MauiList interface
  *    const FMH::MODEL_LIST &items() const;
  * 
  * private:
  *    FMH::MODEL_LIST m_list;
  * 
  *    //Here we have our own custom raw data and turn it into a FMH::MODEL_LIST
  *    FMH::MODEL_LIST getData() const;
  * };
  * @endcode
  * 
  * 
  * In this example the data is only retrieved once the QML engine has completely loaded the component using the MauiList, for this we override the `componentComplete()` virtual method, and there we inform the MauiModel with the signals that the list data is ready.
  * 
  * @code
  * #include "plantslist.h"
  * 
  * PlantsList::PlantsList(QObject *parent) : MauiList(parent)
  * {
  * 
  * }
  * 
  * void PlantsList::componentComplete()
  * {
  *    Q_EMIT preListChanged();
  *    m_list = getData();
  *    Q_EMIT postListChanged();
  *    Q_EMIT countChanged();
  * }
  * 
  * const FMH::MODEL_LIST &PlantsList::items() const
  * {
  *    return m_list;
  * }
  * 
  * FMH::MODEL_LIST PlantsList::getData() const
  * {
  *    FMH::MODEL_LIST data;
  * 
  *    data << FMH::MODEL {{FMH::MODEL_KEY::TITLE, QStringLiteral("Acanthaceae")}, {FMH::MODEL_KEY::CATEGORY, QStringLiteral("Acanthus")}};
  * 
  *    data << FMH::MODEL {{FMH::MODEL_KEY::TITLE, QStringLiteral("Agavaceae")}, {FMH::MODEL_KEY::CATEGORY, QStringLiteral("Agave")}};
  * 
  *    data << FMH::MODEL {{FMH::MODEL_KEY::TITLE, QStringLiteral("Bixaceae")}, {FMH::MODEL_KEY::CATEGORY, QStringLiteral("Annatto")}};
  * 
  *    data << FMH::MODEL {{FMH::MODEL_KEY::TITLE, QStringLiteral("Asteraceae")}, {FMH::MODEL_KEY::CATEGORY, QStringLiteral("Aster")}};
  * 
  *    data << FMH::MODEL {{FMH::MODEL_KEY::TITLE, QStringLiteral("Leguminaceae")}, {FMH::MODEL_KEY::CATEGORY, QStringLiteral("Bean")}};
  * 
  *    return data;
  * }
  * 
  * @endcode
  * 
  * Now we register our own custom PlanstList class to the QML engine as a type.
  * 
  * @code
  * #include <MauiKit3/Core/mauiapp.h>
  * #include "plantslist.h"
  * 
  * int main(int argc, char *argv[])
  * {
  *    ...
  *    
  *    qmlRegisterType<PlantsList>("org.maui.demo", 1, 0, "PlantsList"); //Here we register it.
  * 
  *    engine.load(url);
  * 
  *    return app.exec();
  * }
  * @endcode
  * 
  * And finally, we can consume the data list by hooking it up to the MauiModel exposed type `BaseModel`.
  * 
  * @code
  * import org.mauikit.controls as Maui
  * 
  * import org.maui.demo as Demo
  * 
  * Maui.ApplicationWindow
  * {
  *    id: root
  * 
  *    Maui.Page
  *    {
  *        id: _page
  *        anchors.fill: parent
  *        Maui.Controls.showCSD: true
  *        headBar.forceCenterMiddleContent: true
  * 
  *        Maui.ListBrowser
  *        {
  *            anchors.fill: parent
  *            model: Maui.BaseModel
  *            {
  *                list: Demo.PlantsList
  *                {
  * 
  *                }
  *            }
  * 
  *            delegate: Maui.ListBrowserDelegate
  *            {
  *                width: ListView.view.width
  *                label1.text: model.title
  *                label2.text: model.category
  *            }
  *        }
  *    }
  * }
  * @endcode
  * 
  * <a href="https://invent.kde.org/maui/mauikit/-/blob/qt6-2/examples/mauilist/">You can find a more complete example at this link.</a>
  */
 class MAUIKIT_EXPORT MauiList : public QObject, public QQmlParserStatus
 {
     
     Q_OBJECT
     QML_ANONYMOUS
     Q_INTERFACES(QQmlParserStatus)
 
     Q_DISABLE_COPY(MauiList)
     
     /**
      * The total amount of elements in the list.
      * @note This needs to be setup manually, as in emitting the signal when new items are appended or removed, etc.
      */
     Q_PROPERTY(int count READ getCount NOTIFY countChanged FINAL)
     
 public:
     /**
      * @brief Default constructor. The usage of this class is meant to be via inheritance by sub-classing it.
      */
     explicit MauiList(QObject *parent = nullptr);
     
     /**
      * @brief The modeled data represented by a FMH::MODEL_LIST.
      * @note  The data must be modeled using the FMH::MODEL_LIST, which is an array list of FMH::MODEL elements, which is a map of key pairs, where the key must be a FMH::MODEL_KEY enum type, and the value a string text.
      * 
      * @return The data model.
      */
     virtual const FMH::MODEL_LIST &items() const = 0;
     
     /**
      * @brief See the Qt documentation on the QQmlParserStatus.
      */
     virtual void classBegin() override {}
     
     /**
      * @brief See the Qt documentation on the QQmlParserStatus.
      */
     virtual void componentComplete() override  {}
     
     /**
      * @brief This function is called once the MauiList has been hooked to the MauiModel, using the MauiModel::list property.
      */
     virtual void modelHooked() {}
     
     int getCount() const;
     
     /**
      * @brief Request to get an item in the list, the item is represented as a FMH::MODEL key pair value.
      * @param index the position of the item to retrieve
      * @return The found item/map in the list at the index. If not item is found at the given index, then an empty map is returned.
      */
     FMH::MODEL getItem(const int &index) const;
     
 public Q_SLOTS:    
     /**
      * @brief Request to get an item in the list, the item is represented as a QVariantMap for easy consumption within the QML scope. This function is exposed to be invoked from QML.
      * @param index the position of the item to retrieve
      * @return The found item/map in the list at the index. If not item is found at the given index, then an empty map is returned.
      */
     QVariantMap get(const int &index) const;
     
 protected:    
     /**
      * @brief Whether an item with a given key-par value exists in the list.
      * @param key the FMH::MODEL_KEY to look for
      * @param value the value associated with the key to look for
      * @return an exact match exists or not
      */
     bool exists(const FMH::MODEL_KEY &key, const QString &value) const;
     
     /**
      * @brief The index number of an item in the list of a given key-par value.
      * @param key the FMH::MODEL_KEY to look for
      * @param value the value associated with the key to look for
      * @return the found index or `-1` if not found
      */
     int indexOf(const FMH::MODEL_KEY &key, const QString &value) const;
     
 Q_SIGNALS:    
     /**
      * @brief This signal should be emitted by the implementation before appending a new item to the list data model.
      */
     void preItemAppended();
     
      /**
      * @brief This signal should be emitted by the implementation before appending a multiple new items to the list data model.
      * @param count the total amount of new items that will be added
      */
     void preItemsAppended(uint count);
     
     /**
      * @brief This signal should be emitted by the implementation after one or multiple new items have finished being added into the list data model.
      */
     void postItemAppended();
     
     /**
      * @brief This signal should be emitted by the implementation before a new item has been inserted at a given index to the list data model.
      * @param index the position index where the new item was inserted at
      */
     void preItemAppendedAt(int index);
     
     /**
      * @brief This signal should be emitted by the implementation before an item has been removed at the given index position.
      * @param index the index position of the element that will be removed
      */
     void preItemRemoved(int index);
     
     /**
      * @brief This signal should be emitted by the implementation after an item has been successfully removed from the list data model. 
      */
     void postItemRemoved();
     
     /**
      * @brief This signal should be emitted by the implementation when changes have been done in the list data model.
      * @param index the index position of the item that was modified in the list data model
      * @param roles the keys that were modified, the key values can be FMH::MODEL_KEY
      */
     void updateModel(int index, QVector<int> roles);
     
     /**
      * @brief This signal should be emitted by the implementation before the list data model has been assigned or populated.
      */
     void preListChanged();
     
     /**
      * @brief This signal should be emitted by the implementation after the list data model is set and done.
      */
     void postListChanged();
     
     /**
      * @brief This signal should be emitted by the implementation when an item has been moved from one index position to another.
      * @param index the original index position of the item in the list data model
      * @param to the new index destination of the item
      */
     void itemMoved(int index, int to);
     
     /**
      * @brief This signal should be emitted by the implementation when the number of elements in the list data model varies. For example when an item is removed or added.
      */
     void countChanged();
 };