Integration: Nested Tree Parent Child C++ Classes with Models/Delegates for QML

[anda_skoa]

I don't see anything that would narrow your option down to just (1), however, it is often benefitial to not design data structures and data handling with just the UI's needs in mind.

Lets look at this with a simplied example, an address book:

1) for that I would have
* a Contact class that can hold all data for a single address book entry
* an AddressBook class that has a list or maybe even a hash of Contact objects and which would have methods to add/remove/change/get/list contacts

2a) a list model that gets a pointer to an AddressBook and provides the list of contacts, contact details as roles

2b) an Import/Export class or classes that also get an AddressBook pointer or reference and implement data I/O

3) optionally, a Contact adapter/editor class that serves as an QML adapter for modifying a single contact. It would get a Contact object and provide its data as separate Q_PROPERTY fields, it can provide methods to check for validity of the data, etc.

(2a) and (2b) are different usages of the data but can still work on the same data. the base classes only need to ensure they can provide all the functionality required for these two use cases.

For your application I wonder if you really want cards nested inside albums.
I.e. is an Album not just a "view" of cards, a selection from the whole?
For example could a user have "All my cards", "All time favorites", "Favorite Water Pokemons", with the same "Vaporeon" card being in all three?

Cheers,
_

[Nizars]

You make a good point!
I didn't really think of that. The thing is, for now at least and to narrow down my project, I have decided to work only with one set of Pokemon cards. Those cards exist in <cardID>.json files in a resource. Those JSON documents contain all the variable values for the cards such name, hp, attacks and so on. The card images exist in another folder in the resources as <cardID>.jpg. I have done this so that I have something to work with and not risk spending a month or two working with network, ssl, cache, json classes and risk not having anything to present as the deadline aproaches. I do like the project I am working with and I am planning to add those functionalities in the future, maybe even a function that adds cards by scanning them with a phone camera. The JSON documents are retreived from: pokemontcg.io but that is something that I won't touch until the main application fully works.

My line of thinking has been that when the user wants to add a card to an album. He or she will type the name or the id of the card and the program creates an instance of that card in the album. If he doesn't add it to the album and decided just to see it, it will be deleted once he exits the view. I also thought of having an instance of all the cards pre-loaded in a hidden default album that the App uses to display the cards before the user adds them to his or her Album.

You make a good point about a Card being available in more than one album. I guess there should be a default "All my cards" Album. I guess cards in that Album determines what cards are made available to the other albums. I assume that this would be a bit problematic if the user wants to create a "My wishlist" or "To buy" Album. There is also the problem of duplicate cards.

I will try to rethink the relationships between the Albums and between the Cards and Albums. I think that having an Album as an isolated container of cards from other Cards in other Albums might make the implementation a bit easier assuming that the user will manually add Cards to Albums and not expect them to be shared among the Albums. I can however create a "view" that shows all the cards in all the albums or multiple Albums.

[anda_skoa]

Just sketching some ideas here:

class Card
{
    QString id;
    QString name;
    // ....
};
 
class CardManager : public QObject
{
    Q_OBJECT
 
public:
    // returns an invalid card if ID is not found, e.g. Card object with empty "id"
    Card addCardById(const QString &id);
    Card addCardByName(const QString &name);
 
    Card card(const QString &id) const;
    QList<Card> cards() const;
 
    int count() const;
 
signals:
    void cardAdded(const QString &id);
    void cardRemoved(const QString &id);
 
private:
    QList<Card> m_cards;
};

class Card
{
    QString id;
    QString name;
    // ....
};

class CardManager : public QObject
{
    Q_OBJECT

public:
    // returns an invalid card if ID is not found, e.g. Card object with empty "id"
    Card addCardById(const QString &id);
    Card addCardByName(const QString &name);

    Card card(const QString &id) const;
    QList<Card> cards() const;

    int count() const;

signals:
    void cardAdded(const QString &id);
    void cardRemoved(const QString &id);

private:
    QList<Card> m_cards;
};

To copy to clipboard, switch view to plain text mode 

class Album
{
    QString id;
    QString name;
    QStringList cardIDs;
};
 
class AlbumManager : public QObject
{
    Q_OBJECT
public:
    Album createAlbum(const QString &name);
 
    Album album(const QString &id) const;
 
    QList<Album> albums() const;
 
    int count() const;
 
    void addCard(const QString &albumId, const QString &cardId);
    void removeCard(const QString &albumId, const QString &cardId);
 
signals:
    void albumAdded(const QString &id);
    void albumRemoved(const QString &id);
 
    void cardAdded(const QString &albumId, const QStringList &cardIDs);
    void cardRemoved(const QString &albumId, const QStringList &cardIDs);
};

class Album
{
    QString id;
    QString name;
    QStringList cardIDs;
};

class AlbumManager : public QObject
{
    Q_OBJECT
public:
    Album createAlbum(const QString &name);

    Album album(const QString &id) const;

    QList<Album> albums() const;

    int count() const;

    void addCard(const QString &albumId, const QString &cardId);
    void removeCard(const QString &albumId, const QString &cardId);

signals:
    void albumAdded(const QString &id);
    void albumRemoved(const QString &id);

    void cardAdded(const QString &albumId, const QStringList &cardIDs);
    void cardRemoved(const QString &albumId, const QStringList &cardIDs);
};

To copy to clipboard, switch view to plain text mode 

class AbstractCardModel : public QAbstractListModel
{
    Q_OBJECT
public:
    enum Roles {
        IdRole = Qt::UserRole + 1,
        NameRole,
        // ....
    }
 
    explicit AbstractCardModel(CardManager *cardManager, QObject *parent = 0);
 
    // this uses cardForIndex to get the card, then uses role to return the actual data
    QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const;
 
protected:
    QHash<int, QByteArray> roleNames() const;
 
    virtual Card cardForIndex(const QModelIndex &index) const = 0;
 
protected:
    CardManager *m_cardManager;
};

class AbstractCardModel : public QAbstractListModel
{
    Q_OBJECT
public:
    enum Roles {
        IdRole = Qt::UserRole + 1,
        NameRole,
        // ....
    }

    explicit AbstractCardModel(CardManager *cardManager, QObject *parent = 0);

    // this uses cardForIndex to get the card, then uses role to return the actual data
    QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const;

protected:
    QHash<int, QByteArray> roleNames() const;

    virtual Card cardForIndex(const QModelIndex &index) const = 0;

protected:
    CardManager *m_cardManager;
};

To copy to clipboard, switch view to plain text mode 

// for showing the cards of a single album
class AlbumCardsModel : public AbstractCardsModel
{
    Q_OBJECT
public:
    AlbumCardsModel(AlbumManager *albumManager, CardManager *cardManager, QObject *parent = 0);
 
    void showAlbum(const QString &albumId);
 
    int rowCount(const QModelIndex &parent) const;
 
protected:
    Card cardForIndex(const QModelIndex &index) const;
 
private slots:
    // gets connected to m_albumManager's albumRemoved() signal
    void onAlbumRemoved(const QString &albumId);
 
    void onCardAdded(const QString &albumId, const QString cardId);
    void onCardRemoved(const QString &albumId, const QString cardId);
 
private:
    AlbumManager *m_albumManager;
    Album m_album;
};
 
void AlbumCardsModel::showAlbum(const QString &albumId)
{
    beginResetModel();
 
    m_album = m_albumManager->album(albumId);
 
    endResetModel();
}
 
int AlbumCardsModel::rowCount(const QModelIndex&) const
{
    return m_album.cardIDs.count();
}
 
Card AlbumCardsModel::cardForIndex(const QModelIndex &index) const
{
    return m_cardManager->card(m_album.cardIDs.at(index.row());
}
 
void AlbumCardsModel::onAlbumRemoved(const QString &albumId)
{
    if (albumId != m_album.id) return;
 
    beginResetModel();
    m_album = Album();
    endResetModel();
}
 
void AlbumCardsModel::onCardAdded(const QString &albumId, const QString &cardId)
{
    if (albumId != m_album.id) return;
 
    const Album updatedAlbum = m_albumManager->album(albumId);
    const int row = updatedAlbum.cardIDs.indexOf(cardId);
 
    beginInsertRows(QModelIndex(), row, row);
 
    m_album = updatedAlbum;
 
    endInsertRows();
}
 
void AlbumCardsModel::onCardRemoved(const QString &albumId, const QString &cardId)
{
    if (albumId != m_album.id) return;
 
    const Album updatedAlbum = m_albumManager->album(albumId);
    const int row = m_album.cardIDs.indexOf(cardId);
 
    beginRemoveRows(QModelIndex(), row, row);
 
    m_album = updatedAlbum;
 
    endRemoveRows();
}

// for showing the cards of a single album
class AlbumCardsModel : public AbstractCardsModel
{
    Q_OBJECT
public:
    AlbumCardsModel(AlbumManager *albumManager, CardManager *cardManager, QObject *parent = 0);

    void showAlbum(const QString &albumId);

    int rowCount(const QModelIndex &parent) const;

protected:
    Card cardForIndex(const QModelIndex &index) const;

private slots:
    // gets connected to m_albumManager's albumRemoved() signal
    void onAlbumRemoved(const QString &albumId);

    void onCardAdded(const QString &albumId, const QString cardId);
    void onCardRemoved(const QString &albumId, const QString cardId);

private:
    AlbumManager *m_albumManager;
    Album m_album;
};

void AlbumCardsModel::showAlbum(const QString &albumId)
{
    beginResetModel();

    m_album = m_albumManager->album(albumId);

    endResetModel();
}

int AlbumCardsModel::rowCount(const QModelIndex&) const
{
    return m_album.cardIDs.count();
}

Card AlbumCardsModel::cardForIndex(const QModelIndex &index) const
{
    return m_cardManager->card(m_album.cardIDs.at(index.row());
}

void AlbumCardsModel::onAlbumRemoved(const QString &albumId)
{
    if (albumId != m_album.id) return;

    beginResetModel();
    m_album = Album();
    endResetModel();
}

void AlbumCardsModel::onCardAdded(const QString &albumId, const QString &cardId)
{
    if (albumId != m_album.id) return;

    const Album updatedAlbum = m_albumManager->album(albumId);
    const int row = updatedAlbum.cardIDs.indexOf(cardId);

    beginInsertRows(QModelIndex(), row, row);
    
    m_album = updatedAlbum;

    endInsertRows();
}

void AlbumCardsModel::onCardRemoved(const QString &albumId, const QString &cardId)
{
    if (albumId != m_album.id) return;

    const Album updatedAlbum = m_albumManager->album(albumId);
    const int row = m_album.cardIDs.indexOf(cardId);

    beginRemoveRows(QModelIndex(), row, row);
    
    m_album = updatedAlbum;

    endRemoveRows();
}

To copy to clipboard, switch view to plain text mode 

Cheers,
_

[Nizars]

I really appreciate your time and all the help you are offering me on this!

I have a quick question for you while I finish making changes to my classes.

What is the role of a <class>Manager class? I am just trying to understand how it fits in.
Say I want to to add copy constractors and assignment opperators for the App, Album and Card classes, where would those be implemented? in their respective classes? or in the their accompanying <class>Manager classes?
What about the Setter and Getter class methods such as "QString getCardName() const;"? Same with the default and overloaded constructors? should I even have a default constructor in the original class?

I have noticed that you combine each class and it's Manager class in the same document. Is there a reason or a benifit behind this practise? or is this simple down to preference and time saving?
I have created three different classes for each of the "core" classes. An Album class, an AlbumsManager class and an AlbumModel class. I am totally open to changing it to the template you wrote if it makes a difference.

[d_stranz]

Yes, anda_skoa has been very generous with his help on this one and has given you a well-thought-out and flexible design.

If you use the Card and Album classes as anda_skoa has defined them in his code, you don't actually need an explicit copy constructor (or even an assignment operator) because C++ will implement default ones for you. Usually default constructor / assignment does a bitwise copy of the right-hand side instance (i.e. the instance you are copying from), except when the class being copied contains member variables which themselves have copy / assignment operators, which QString and QStringList do (and which fundamental types like int, float, etc. also have). If you add anything to the definitions of these classes which does not have explicit copy / assignment, you'll either have to make copy and assignment methods for them, or implement them in the Card or Album class. For example, if you add a pointer variable, you'll probably want to either wrap it in a smart pointer (which has copy / assignment), make a deep copy of the contents of the instance pointed to, or add another "manager" which is in charge of the lifetime of these pointers (rather than delete them in the Card or Album destructor).

Combining the Card and CardManager class in the same file is basically just for convenience. More importantly, only the CardManager should be allowed to create Card instances, because then it will automatically add them to the list of Card instances it is managing. Likewise for Album and AlbumManager. You can't have a standalone, unmanaged Card or Album. But on the other hand, anda_skoa's design allows for cards that belong to no album as well as cards that belong to multiple albums.

You'll probably only have one instance each of the AlbumManager and CardManager classes, but the design also anticipates that you might want to expand to handle multiple users, each one of whom will have their own card and album collections, so you'd need a card and album manager for each of them.

The AlbumManager and CardManager classes are the GUI-independent classes that are used by the AlbumCardsModel. This model is the interface to the views; when either the CardManager or AlbumManager make changes to their content, they emit signals that the model listens for so it can in turn update the views. You might have several instances of AlbumCardsModel - one for interfacing to one or more views of different albums.