ObjectRef Class Reference

Inherits from	`BasicType`
Declared in	`flip/ObjectRef.h`

template <class T>   class ObjectRef;

flip::ObjectRef is a type that represents a pointer or reference to an actual flip object.

Internally it stores a flip unique reference number (see flip::Ref for more details)

Therefore, getting a potentially associated object can be done in a safe way.

It is perfectly valid to have a flip::ObjectRef pointing to a reference which is no longer in the model. In this case accessing the underlying object will return nullptr.

It only provides a convenient interface to store a flip::Ref into the model and a way to dereference it safely.

Important: In particular, unlike containers, an ObjectRef won't have a changed state when the pointee element is changed.

Template Parameters

`T`	The type of the elements. `T` must inherit from `flip::Object`

Member Functions Synopsys

Constructor	Constructs the `ObjectRef`
Destructor	Destructs the `ObjectRef`
`operator =`	Assigns value

Document Management

`document`	Returns the document to which the object is attached to
`ref`	Returns the unique reference number of the object
`added`	Returns `true` iff the object was just attached to the document tree
`removed`	Returns `true` iff the object was just detached from the document tree
`resident`	Returns `true` iff the object was neither attached nor detached from the document tree
`changed`	Returns `true` iff the object or one of its children was modified
`ancestor`	Returns a reference to a parent in the current parent chain of the object
`disable_in_undo`	Disables the record state modification in history
`inherit_in_undo`	Inherits the record state modification in history
`is_in_undo_enabled`	Returns `true` iff this object modifications are recorded in history
`revert`	Reverts all the changes made to the object and its children if any
`assign`	Replaces the content of the object with the content of the provided object

Value Access

`operator T *`	Returns the current value of the object
`get`	Returns the current value of the object as a flip unique reference number
`before`	Returns the previous value of the object
`get_before`	Returns the previous value of the object as a flip unique reference number

Comparaison

`operator ==`	Returns `true` iff objects current values are equal
`operator !=`	Returns `true` iff objects current values are different

Member Functions

Constructor

ObjectRef ();                          (1)
ObjectRef (const ObjectRef & other);   (2)
ObjectRef (T * ptr);                   (3)
ObjectRef (const Ref & ref);           (4)

Default constructor, constructs with a nullptr value.
Copy constructor. Constructs the object with the value of other.
Constructor. Constructs the object with pointer ptr.
Constructor. Constructs the object with a flip unique reference number.

WARNING: Variant 3 and 4 of the constructor cannot be called from the default constructor of a flip object.

Destructor

~ObjectRef ();

Destructor.

`operator =`

ObjectRef & operator = (const ObjectRef & other);  (1)
ObjectRef & operator = (T * ptr);                  (2)
ObjectRef & operator = (const Ref & ref);          (3)

Copy assignment operator.
Assignment operator. Assigns the object with pointer ptr.
Assignment operator. Assigns the object with a flip unique reference number.

`document`

DocumentBase & document () const;

Returns the document to which the object is attached to.

WARNING: Temporary flip objects are not attached to a document

`ref`

const Ref & ref () const;

Returns the unique reference number of the object.

`added`

bool  added () const;

Returns true iff the object was just attached to the document tree.

Example :

void  Observer::document_changed (Note & note)
{
   if (note.added ())
   {
      // A note was added to the document. Create the corresponding
      // view element
      note.entity ().emplace <NoteView> ();
   }
   [...]
}

`removed`

bool  removed () const;

Returns true iff the object was just detached from the document tree.

Example :

void  Observer::document_changed (Note & note)
{
   [...]
   if (note.removed ())
   {
      // A note was removed from the document. Release the corresponding
      // view element
      note.entity ().erase <NoteView> ();
   }
}

`resident`

bool  resident () const;

Returns true iff the object was neither attached nor detached from the document tree.

An object can be resident but moved. In this case the iterator pointing to it will allow to detect the move.

Example :

void  Observer::document_changed (Array <Track> & tracks)
{
   auto it = tracks.begin ();
   auto it_end = tracks.end ();
   for (; it != it_end ; ++it)
   {
      Track & track = *it;
      if (it.added () && track.resident ())
      {
         // the track was moved in the container
         // this is the destination position
      }
      if (it.added () && track.resident ())
      {
         // the track was moved in the container
         // this is the source position
      }
   }
}

`changed`

bool  changed () const;

Returns true iff the object or one of its children was modified.

Example :

void  Observer::document_changed (Note & note)
{
   auto & view = note.entity ().use <ViewNote> ();
   if (note.changed ())
   {
      // one or more properties of the note changed
      if (note.position.changed ())
      {
         view.set_position (note.position);
      }
      if (note.duration.changed ())
      {
         view.set_duration (note.duration);
      }
   }
}

`ancestor`

template <class T>   T &   ancestor ();
template <class T>   const T &   ancestor () const;

Returns a reference to a parent in the current parent chain of the object.

Note: If an object or its parent is moved from one container to another, this function will always return the current parent, that is not the previous one

`disable_in_undo`

void   disable_in_undo ();

Disables the record state modification in history of the object and its subtree if any.

Example :

void  add_user (Root & root)
{
   // emplace a new User of the document to store
   // user specific data. User is constructed with
   // the unique user id number given at document
   // creation
   User & user = root.users.emplace <User> (root.document ().user ());
   // we don't want the scroll position in the document
   // to be part of undo
   user.scroll_position.disable_in_undo ();
}

`inherit_in_undo`

void   inherit_in_undo ();

Inherits the record state modification in history of the object and its subtree if any, from its parent state. This is the default mode.

Note: If the Root object of the tree is in inherited mode, then it is considered as enabled in undo.

`is_in_undo_enabled`

bool  is_in_undo_enabled () const;

Returns true iff this object modifications are recorded in history. The function recursively search for disabled state starting from the object itself and navigating through the parent objects, if the state is inherited.

`revert`

void  revert () const;

Reverts all the changes make to the object and its children if any.

Example :

// initially, note.position == 1
note.position = 2;
note.revert ();
// now, note.position == 1

`assign`

void  assign (const Type & rhs);

Replaces the content of the object with the content of the provided object. Both objects need to be bound to a document for the function to succeed.

Example :

// initially :
// note.position == 1
// note.duration == 3
// note2.position == 2
// note2.duration == 1
note.assign (note2);
// now :
// note.position == 2
// note.duration == 1

`operator T *`

operator T * () const;

Returns the current value of the object or nullptr, if the referenced object does not exist anymore.

`get`

Ref   get () const;

Returns the current value of the object as a flip unique reference number, even if the object does not exist anymore.

`before`

T *  before () const;

Returns the previous value of the object or nullptr, if the referenced object does not exist anymore.

`get_before`

Ref   get_before () const;

Returns the previous value of the object as a flip unique reference number, even if the object does not exist anymore.

`operator ==`

bool  operator == (const ObjectRef & rhs) const;
bool  operator == (T * rhs) const;

`operator !=`

bool  operator != (const ObjectRef & rhs) const;
bool  operator != (T * rhs) const;

previous next