SessionItem.h

Go to the documentation of this file.

//  ************************************************************************************************
//
//  BornAgain: simulate and fit reflection and scattering
//
//! @file      GUI/Model/BaseItem/SessionItem.h
//! @brief     Defines class SessionItem
//!
//! @homepage  http://www.bornagainproject.org
//! @license   GNU General Public License v3 or higher (see COPYING)
//! @copyright Forschungszentrum Jülich GmbH 2018
//! @authors   Scientific Computing Group at MLZ (see CITATION, AUTHORS)
//
//  ************************************************************************************************
 
#ifndef BORNAGAIN_GUI_MODEL_BASEITEM_SESSIONITEM_H
#define BORNAGAIN_GUI_MODEL_BASEITEM_SESSIONITEM_H
 
#include "Base/Util/Assert.h"
#include "Fit/Param/RealLimits.h"
#include "GUI/Model/BaseItem/ModelMapper.h" // no forward declare, used too often
#include "GUI/Support/XML/Serialize.h"
#include "Wrap/WinDllMacros.h"
#include <QStringList>
#include <memory>
 
Q_DECLARE_METATYPE(RealLimits)
 
class SessionItemData;
class SessionItemTags;
class QXmlStreamWriter;
class QXmlStreamReader;
class GroupInfo;
 
//! Base class for a GUI data item.
//!
//! SessionItem and SessionModel implement the base structures to store data in the GUI layer.
//!
//! SessionItem provides
//!  * Keeping of the project data itself
//!  * Storing of elements for UI representation, e.g. the label text and the tooltip
//!  * Generic serialization to XML
//!  * Hierarchical tree management
//!  * Method to signal value changes
//!  * Generic way to change values via QVariant
//!
//! For realizing the highly generic approach, access to properties, children, values, signals is
//! done by strings. Converting values is done by means provided by QVariant.
//!
//! A data structure is realized at runtime, not at compile time (therefore e.g. properties are not
//! just data members, but children of type SessionItem). The tree structure, properties, UI etc.
//! are usually created by initialization routines.
//!
//! By this, the data holding is completely generic and also completely volatile - it can be changed
//! at any time, properties or children can be added or removed to represent different behavior, or
//! even different objects. This realizes kind of a dynamic polymorphy, which can be examined by
//! strings. E.g. to find out whether a child is a property with a value, or a grouping element with
//! more children, the child's modelType() has to be checked against "Property", "GroupProperty",
//! and so on. The model type therefore is comparable to the "class" of the SessionItem.
//!
//! The hierarchy of a SessionItem and its children is used for
//!  * representation on the UI (trees)
//!  * creating the XML hierarchy
//!  * accessing
//!
//! **Example for creating properties (properties are a replacement for data members):**
//! \code
//! CylinderItem::CylinderItem()
//! {
//!     addProperty("Radius", 8.0);
//!     addProperty("Height", 16.0);
//! }
//! \endcode
//!
//! In this example, the text "Radius" will be used
//!  * on the UI to represent the value (label),
//!  * for storing the value to the project file (XML tag)
//!  * for accessing the property (e.g. read/write the value).
//!  * for identifying the item when signaling a value change
//!
//! The object has nothing like a \code double m_radius; \endcode
//!
//! **Relation to core elements**
//!
//! The GUI component does not use core component elements to store data.
//!
//! As an example, here the representation of simulation options in the core layer:
//! \code
//! class SimulationOptions {
//! public:
//!     // access methods omitted for simplicity
//! private:
//!     bool m_mc_integration;
//!     bool m_include_specular;
//!     bool m_use_avg_materials;
//!     size_t m_mc_points;
//!     ThreadInfo m_thread_info;
//! };
//! \endcode
//!
//! And following the corresponding object in the UI layer.
//! \code
//! class BA_CORE_API_ SimulationOptionsItem : public SessionItem {
//! private:
//!     // Strings for accessing the properties
//!     static constexpr auto P_RUN_POLICY{"..."};
//!     static constexpr auto P_NTHREADS{"..."};
//!     static constexpr auto P_COMPUTATION_METHOD{"..."};
//!     static constexpr auto P_MC_POINTS{"..."};
//!     static constexpr auto P_FRESNEL_MATERIAL_METHOD{"..."};
//!     static constexpr auto P_INCLUDE_SPECULAR_PEAK{"..."};
//!
//! public:
//!     // access methods omitted for simplicity
//! private:
//!     // no members at all!
//! };
//! \endcode
//!
//! As one can see, no structure is visible at all in the class definition itself.
//! The structure is created in the constructor:
//!
//! \code
//! SimulationOptionsItem::SimulationOptionsItem() : SessionItem(M_TYPE)
//! {
//!     ComboProperty policy;
//!     policy << getRunPolicyNames();
//!     policy.setToolTips(getRunPolicyTooltips());
//!     addProperty(P_RUN_POLICY, policy.variant())->setToolTip(tooltip_runpolicy);
//!
//!     ComboProperty nthreads;
//!     nthreads << getCPUUsageOptions();
//!     addProperty(P_NTHREADS, nthreads.variant())->setToolTip(tooltip_nthreads);
//!
//!     ComboProperty computationMethod;
//!     computationMethod << "Analytical"
//!                       << "Monte-Carlo Integration";
//!     addProperty(P_COMPUTATION_METHOD,
//!     computationMethod.variant())->setToolTip(tooltip_computation);
//!
//!     // [Code omitted for simplicity]
//!
//!     mapper()->setOnPropertyChange([this](const QString& name) {
//!         if (name == P_COMPUTATION_METHOD && isTag(P_MC_POINTS)) {
//!             ComboProperty combo = getItemValue(P_COMPUTATION_METHOD).value<ComboProperty>();
//!
//!             if (combo.getValue() == "Analytical") {
//!                 getItem(P_MC_POINTS)->setEnabled(false);
//!
//!             } else {
//!                 getItem(P_MC_POINTS)->setEnabled(true);
//!             }
//!         } else if (name == P_NTHREADS) {
//!             updateComboItem(P_NTHREADS, getCPUUsageOptions());
//!         } else if (name == P_RUN_POLICY) {
//!             updateComboItem(P_RUN_POLICY, getRunPolicyNames());
//!         }
//!     });
//! }
//! \endcode
//!
//! The onPropertyChange part in the above example shows also the string based access to
//! values as well as types:
//! \code
//!     mapper()->setOnPropertyChange([this](const QString& name) {
//!         if (name == P_COMPUTATION_METHOD && isTag(P_MC_POINTS))
//!             // ...
//!             getItem(P_MC_POINTS)->setEnabled(true);
//!         else if (name == P_NTHREADS)
//!             updateComboItem(P_NTHREADS, getCPUUsageOptions());
//!         else if (name == P_RUN_POLICY)
//!             updateComboItem(P_RUN_POLICY, getRunPolicyNames());
//!     });
//! \endcode
//!
//! Since UI and core are using completely unrelated objects, a conversion between the two
//! components is necessary. This is done with the functions in namespace TransformFromCore
//! and TransformToCore.
//!
//! For IParticle this looks like this:
//! \code
//! std::unique_ptr<IParticle> GUI::Transform::ToCore::createIParticle(const SessionItem&
//! item)
//! {
//!     std::unique_ptr<IParticle> P_particle;
//!     if (item.modelType() == "Particle") {
//!         auto& particle_item = static_cast<const ParticleItem&>(item);
//!         P_particle = particle_item.createParticle();
//!     } else if (item.modelType() == "ParticleCoreShell") {
//!         auto& particle_coreshell_item = static_cast<const ParticleCoreShellItem&>(item);
//!         P_particle = particle_coreshell_item.createParticleCoreShell();
//!     } else if (item.modelType() == "ParticleComposition") {
//!         auto& particle_composition_item = static_cast<const ParticleCompositionItem&>(item);
//!         P_particle = particle_composition_item.createParticleComposition();
//!     } else if (item.modelType() == "MesoCrystal") {
//!         auto& mesocrystal_item = static_cast<const MesoCrystalItem&>(item);
//!         P_particle = mesocrystal_item.createMesoCrystal();
//!     }
//!     return P_particle;
//! }
//! \endcode
//!
//! This code part again shows the (highly error-prone) string-based type checking.
 
class BA_CORE_API_ SessionItem {
    friend class SessionModel;
 
private:
    static constexpr auto P_NAME{"Name"};
 
public:
    explicit SessionItem(const QString& modelType);
    virtual ~SessionItem();
    SessionModel* model() const;
    SessionItem* parentItem() const;
 
    // these functions work without tags and operate on all children
    QModelIndex index() const;
    bool hasChildren() const;
    int numberOfChildren() const;
    QVector<SessionItem*> children() const;
    SessionItem* childAt(int row) const;
    int rowOfChild(SessionItem* child) const;
    SessionItem* getChildOfType(const QString& type) const;
    QVector<SessionItem*> childrenOfType(const QString& model_type) const;
    template <typename T>
    QVector<T*> childrenOfType() const;
    template <typename T>
    T* firstChildOfType() const;
    SessionItem* takeRow(int row);
    int parentRow();
 
    // manage and check tags
    bool registerTag(const QString& name, int min = 0, int max = -1, QStringList modelTypes = {});
    bool isTag(const QString& name) const;
    const SessionItemTags* sessionItemTags() const;
    QString tagFromItem(const SessionItem* item) const;
    bool acceptsAsDefaultItem(const QString& item_name) const;
    QVector<QString> acceptableDefaultItemTypes() const;
 
    // access tagged items
    SessionItem* getItem(const QString& tag = "", int row = 0) const;
    template <typename T>
    T* item(const QString& tag) const;
    QVector<SessionItem*> getItems(const QString& tag = "") const;
    template <typename T>
    QVector<T*> items(const QString& tag = "") const;
    void insertChild(int row, SessionItem* item, const QString& tag = "");
    SessionItem* takeItem(int row, const QString& tag);
 
    // convenience functions for properties
    //! Add new property item and register new tag.
    //! \a name is the tag name and the display name. The property's value will be set
    //! to \a variant
    SessionItem* addProperty(const QString& name, const QVariant& variant);
 
    // #migration: templated addProperty will eventually replace addGroupProperty
    template <typename T>
    T* addProperty(const QString& name);
 
    QVariant getItemValue(const QString& tag) const;
    void setItemValue(const QString& tag, const QVariant& variant) const;
 
    // convenience functions for groups
    SessionItem* addGroupProperty(const QString& groupTag, const GroupInfo& groupInfo);
    SessionItem* setGroupProperty(const QString& groupTag, const QString& modelType) const;
    template <typename T>
    T* setGroupPropertyType(const QString& groupTag);
    SessionItem* getGroupItem(const QString& groupName) const;
    template <typename T>
    T& groupItem(const QString& groupName) const;
 
    // access data stored in roles
    QVariant roleProperty(int role) const;
 
    //! Set the contained role property to the given value.
    //! See also setTranslatorForRolePropertySetter
    bool setRoleProperty(int role, const QVariant& value);
    QVector<int> getRoles() const;
    void emitDataChanged(int role = Qt::DisplayRole);
 
    // custom data types
    QString modelType() const;
    template <typename T>
    bool hasModelType() const;
 
    QVariant value() const;
    bool setValue(QVariant value);
 
    QString defaultTag() const;
    void setDefaultTag(const QString& tag);
 
    QString displayName() const;
    void setDisplayName(const QString& display_name);
 
    QString itemName() const;
    void setItemName(const QString& name);
    static bool isItemNamePropertyName(const QString& name);
 
    void setEnabled(bool enabled);
    void setEditable(bool enabled);
    bool isEnabled() const;
    bool isEditable() const;
 
    RealLimits limits() const;
    SessionItem& setLimits(const RealLimits& value);
 
    int decimals() const;
    SessionItem& setDecimals(int n);
 
    QString toolTip() const;
    SessionItem& setToolTip(const QString& tooltip);
 
    ModelMapper* mapper();
 
    virtual QByteArray serializeBinaryData() const;
    virtual void deserializeBinaryData(const QByteArray& data);
 
    virtual void writeNonSessionItems(QXmlStreamWriter* writer) const;
    virtual void readNonSessionItems(QXmlStreamReader* reader);
    virtual bool allowWritingChildToXml(SessionItem* child) const;
 
private:
    void childDeleted(SessionItem* child);
    void setParentAndModel(SessionItem* parent, SessionModel* model);
    void setModel(SessionModel* model);
    int flags() const;
    void changeFlags(bool enabled, int flag);
    int getCopyNumberOfChild(const SessionItem* item) const;
 
    SessionItem* m_parent;
    SessionModel* m_model;
    QVector<SessionItem*> m_children;
    std::unique_ptr<SessionItemData> m_properties;
    std::unique_ptr<SessionItemTags> m_tags;
    std::unique_ptr<ModelMapper> m_mapper;
};
 
// Extends namespace defined in GUI/Model/XML/Serialize.h
namespace Serialize {
 
//! Only for migration
// #bamigration Remove once the SessionItem migration is done
template <typename type>
void rwSessionItem(Streamer& s, const QString& tag, SessionItem* property);
 
} // namespace Serialize
 
//  ************************************************************************************************
//  Templates implementation
//  ************************************************************************************************
 
template <typename T>
T* SessionItem::item(const QString& tag) const
{
    auto* t = dynamic_cast<T*>(getItem(tag));
    ASSERT(t);
    return t;
}
 
template <typename T>
QVector<T*> SessionItem::items(const QString& tag) const
{
    QVector<T*> result;
 
    for (SessionItem* item : getItems(tag))
        if (auto* titem = dynamic_cast<T*>(item))
            result.push_back(titem);
    return result;
}
 
template <typename T>
QVector<T*> SessionItem::childrenOfType() const
{
    QVector<T*> result;
    for (auto* child : m_children)
        if (child->modelType() == T::M_TYPE)
            result.append(dynamic_cast<T*>(child));
 
    return result;
}
 
 
template <typename T>
T* SessionItem::firstChildOfType() const
{
    for (auto* child : m_children)
        if (child->modelType() == T::M_TYPE)
            return dynamic_cast<T*>(child);
 
    return nullptr;
}
 
template <typename T>
T* SessionItem::addProperty(const QString& tagname)
{
    auto property = new T;
    property->setDisplayName(tagname);
    registerTag(tagname, 1, 1, QStringList() << property->modelType());
    insertChild(0, property, tagname);
    return property;
}
 
template <typename T>
T* SessionItem::setGroupPropertyType(const QString& groupTag)
{
    SessionItem* item = getGroupItem(groupTag);
    if (!item->hasModelType<T>())
        return dynamic_cast<T*>(setGroupProperty(groupTag, T::M_TYPE));
    return dynamic_cast<T*>(item);
}
 
template <typename T>
T& SessionItem::groupItem(const QString& groupName) const
{
    auto* t = dynamic_cast<T*>(getGroupItem(groupName));
    ASSERT(t);
    return *t;
}
 
template <typename T>
bool SessionItem::hasModelType() const
{
    return modelType() == T::M_TYPE;
}
 
 
template <typename type>
void Serialize::rwSessionItem(Streamer& s, const QString& tag, SessionItem* property)
{
    if (QXmlStreamWriter* w = s.xmlWriter()) {
        auto v = property->value().value<type>();
        Serialize::rwValue(s, tag, v);
    } else if (QXmlStreamReader* r = s.xmlReader()) {
        type v;
        Serialize::rwValue(s, tag, v);
        property->setValue(v);
    }
}
 
#endif // BORNAGAIN_GUI_MODEL_BASEITEM_SESSIONITEM_H