Ohm Force Developer LibraryFlip Programming Guide

Flip Programming Guide

• About Flip Programming Guide
• Designing your Flip Application
• Writing a Flip Class Part 1
• Writing a Flip Class Part 2
• Using Containers
• Using Enums
• Using Blobs
• Using ObjectRefs
• Using Cues
• Navigating the Model
  • Overview
  • Visiting Children
  • Visiting Ancestors
• Writing a DocumentObserver
• Writing a DocumentValidator
• Using the Undo/Redo system
• Managing Pseudo Const Members
• Using an ObjectMold
• Writing a Converter
• Writing a DocumentTweaker

Navigating the Model

This chapter will describe how to navigate the model that is either visit an object children or parent.

Overview

Using the Flip framework, the model is implicitely a tree, that is, each object has exactly one parent, except root which has no parent.

The model tree can be navigated, parsed using the Flip framework when handling a model change, or when controlling the model.

The following sections will show how to first visit children, then to visit a parent or more generally ancestors.

Visiting Children

Children of an object are always in containers. The containers themselves defines iterators and reverse iterators to visit children.

However the iterators are a bit different from the ones defined in the standard library. Since the containers support the property of holding simulatenously two revision of the model (the previous revision and the current revision), it was decided for the iterator to support this special property by allowing them to know how the container should be iterated.

In practice, objects in a container can have exactly 3 states :

• Added: compared to the previous revision, an object was added to the container
• Resident: compared to the previous revision, the object was neither added or removed
• Removed: compared to the previous revision, an object was removed from the container

The iteration property is defined as the ability to only iterate over a set of defined states in the container. This property is then injected in the iterator, and the iterator is then used as usual.

In practice the iterator is constructed with a FindMask constant. Also in practice, only two of the FindMask are used and defined in the sub-sections below.

MyArray::iterator it = my_array.begin (flip::FindMask_NATURAL);

MyArray::iterator it2 = my_array.begin (flip::FindMask_CUR);

FindMask_NATURAL

The flip::FindMask_NATURAL is the most used property for iterators. Therefore it is always the default parameter value for Flip methods taking a flip::FindMask parameter.

When injected from a document_changed the iterator will have the property of iterating over all the elements states, and in particular objects which are going to be removed after the document_changed call.

When injected outside a document_changed the iterator will have the property of iterating over all the elements (which are all residents)

FindMask_CUR

The flip::FindMask_CUR is sometimes used in a model change to just iterate over elements that will be resident after the model change.

When injected from a document_changed the iterator will have the property of iterating only over added or resident objects, and in particular not over objects which are going to be removed after a document_changed call.

When injected outside a document_changed the iterator will have the property of iterating over all the elements (which are all residents)

Visiting Ancestors

Since every object of the model has one and only one parent except root which has no parent, it is possible to navigate through each parent, recursively, until the root object is reached. All those parents are called ancestors below.

Each Flip object supports the get_ancestor method which allow to grab an ancestor by type.

SomeAncestorClass & ancestor = element.get_ancestor <SomeAncestorClass> ();

In practice, the get_ancestor function is very often used in the model code, or the model client code.