SessionModel

The SessionModel is the main class to hold the hierarchy of SessionItem objects. It contains a single root SessionItem as an entry point to other top-level items through the model API. In pseudo-code it it can be expressed as:

class SessionModel
{
public:
  SessionModel() : m_root_item(std::make_unique<SessionItem>()) {}

private:
  std::unique_ptr<SessionItem> m_root_item;
};

SessionModel implements SessionModelInterface. It doesn’t have any notification capabilities, do not have any unddo/redo mechanism and implements only basic functionality to add, remove and access items.

Inserting item

To insert an item in a model, one has to use the InsertItem method and provide a pointer to a parent item and TagIndex specifying the position in the parent’s containers. When no arguments are provided, appending to a root item is assumed:

SessionModel model;

// appends new compound to the root item
auto parent = model.InsertItem<CompoundItem>();

// inserting child into parent's tag
auto child = model.InsertItem<PropertyItem>(parent, {"tag", 0});

In the example above it is assumed that the parent item is properly configured, and can accept items of a given type under the given tag.

Removing item

Item can be removed from the model by using either RemoveItem or TakeItem. The first method will remove item and discard it completely:

// inserts and removes the item
auto item = model.InsertItem<CompoundItem>();
model.RemoveItem(item)

The second item requires the knowledge of item’s parent and location:

// insert a child into a parent
auto parent = model.InsertItem<CompoundItem>();
auto child = model.InsertItem<SessionItem>(parent, {"tag", 0});

// taking a child from parent
auto taken = model.RemoveItem<SessionItem>(parent, {"tag", 0});

Memory pool

Every SessionItem carries a unique identifier that is assigned to it at the moment of construction. This identifier can be accessed using the GetIdentifier method:

SessionItem item;
std::cout << item.GetIdentifier() << std::endl;
>>> "4c281780-1bf6-4d98-8de2-b9775085c755"

When SessionItem is inserted in the model, this identifier gets registered in the model’s ItemPool together with the item’s address. When the item is removed from the model, the record is removed too. During serialization of the model, and following reconstruction of the model from serialized content, items’ identifiers are preserved.

Knowing the identifier, one can find the SessionItem address. It allows using identifiers for cross-linking between model parts, also for the case of different models:

SessionModel model;

auto item = model.InsertItem<SessionItem>();
auto identifier = item->GetIdentifier();

auto found_item = model.FindItem(identifier);
assert(item == found_item);

SessionModel API

class SessionModel : public mvvm::ISessionModel

The SessionModel class is the main model to hold hierarchy of SessionItem objects.

Subclassed by mvvm::ApplicationModel

Public Functions

virtual std::unique_ptr<ISessionModel> Clone() const override

Creates a partial model clone.

The resulting model will not inherit the content of the command stack, and will not have any connections. It will rely on the same item pool as the original model. All items in a cloned tree will have regenerated identifiers.

virtual std::string GetType() const override

Returns model type.

virtual SessionItem *GetRootItem() const override

Returns root item.

virtual ModelEventHandler *GetEventHandler() const override

Returns event handler.

Returns:

Event handler.

virtual ICommandStack *GetCommandStack() const override

Returns command stack.

virtual SessionItem *InsertItem(std::unique_ptr<SessionItem> item, SessionItem *parent, const TagIndex &tag_index) override

Inserts an item into the given parent and takes ownership of it.

Parameters:

  • An – item to insert.

  • parent – The parent where to insert.

  • tag_index – A tag_index pointing to the inserted place.

Returns:

The pointer to the inserted item.

virtual std::unique_ptr<SessionItem> TakeItem(SessionItem *parent, const TagIndex &tag_index) override

Takes a child from a parent and returns it to the caller.

Parameters:

  • parent – A parent item from where take the item.

  • tag_index – A tag_index pointing to the child.

Returns:

Taken item.

virtual void RemoveItem(SessionItem *item) override

Removes an item from the model and discards it.

The item should belong to the model. Its exact parent and tag_index will be deduced from the item itself.

Parameters:

item – The item to remove.

virtual void MoveItem(SessionItem *item, SessionItem *new_parent, const TagIndex &tag_index) override

Moves an item from it’s current parent to a new parent.

Old and new parents should belong to the same model. Please note, that the current implementation moves and item via combination of take/insert. This leads to corresponding notifications: about-to-remove, item removed, about-to-insert, item inserted.

Parameters:

  • item – The item to move.

  • new_parent – New parent where to insert.

  • tag_index – A tag_index pointing to the insert place.

virtual bool SetData(SessionItem *item, const variant_t &value, role_t role) override

Sets the value to the given data role of the given item.

If the data is the same as before, will return false and will suppress notifications. It is not possible to change the data type for a given role, once the role is set for the first time. I.e. an attempt to set an integer to the role containing a string will lead to the exception. User utils::ReplaceData if you need to change a data type.

Parameters:

  • item – The item to set the data.

  • value – The value.

  • role – The data role.

Returns:

Returns true, if the data was changed.

virtual SessionItem *FindItem(const std::string &id) const override

Finds an item with the given identifier among all model’s items.

Parameters:

id – A unique item identifier.

Returns:

A pointer to the item.

virtual void Clear() override

Clears the model.

Internally replaces root item with new empty root item.

virtual void ReplaceRootItem(std::unique_ptr<SessionItem> root_item) override

Replaces existing root item with new root item.

This method is used in serialization to restore the model from persistent content. New root item must be initialized (unique_ptr shall not be empty).

Parameters:

root_item – New root item, possibly pre-filled with some content.

virtual void CheckIn(SessionItem *item) override

A tech method to inform the model about new item.

Internally it just registers an item in memory pool for faster search.

virtual void CheckOut(SessionItem *item) override

A tech method to inform the model that item is no longer belongs to the model.

Internally it just un-registers an item from memory pool.

virtual ICommand *ExecuteCommand(std::unique_ptr<ICommand> command) override

Execute the command.

template<typename T>
T *InsertItem(SessionItem *parent = nullptr, const TagIndex &tag_index = TagIndex::Append())

Creates and inserts an item of a given type into the given parent and takes ownership of it.

Template Parameters:

Type – of item to create.

Parameters:

  • parent – The parent where to insert.

  • tag_index – A tag_index pointing to the place to insert.

Returns:

The pointer to the inserted item.

struct SessionModelImpl

Pimpl class for SessionModel.