Flip Reference

MessageCached Class Reference

Inherits from

BasicType

Declared in

flip/MessageCached.h

template <class... Args>   class MessageCached;

flip::MessageCached is a type that allows signalling of non-persistent data. In particular, flip::MessageCached is type-safe and endian-safe.

It is different from flip::Signal in the sense that it is part of a transaction and is broadcasted to every client in a collaboration scheme. In particular, receiving a message is done in the observer.

Additionally to flip::Message, flip::MessageCached keeps in cache the value of the last message sent.

Template Parameters

Args...

The types of the elements that the MessageCached signals. Each element must be compatible with StreamBinIn and StreamBinOut.

Member Functions Synopsys

Constructor

Constructs the MessageCached

Destructor

Destructs the MessageCached

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

Sending & Receiving

send

Sends a message

operator const std::tuple <Args...> &

Get the last message

has_value

Returns true iff has a message

value

Get the last message

has_before

Returns true iff has a message before

before

Get the last message before

Member Functions

Constructor

MessageCached ();
  1. Default constructor.

Destructor

~MessageCached ();

Destructor.


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

send

MessageCached &   send (Args... args);

Sends a message. Multiple messages may be sent before commiting the document.

Example :

class Root : public Object
{
public:
   MessageCached <int, float> message;
}
Model::version ("test.document");
Model::declare <Root> ()
   .name ("Root")
   .member <MessageCached <int, float>, &Root::message> ("message");
Document document (Model::use (), observer, 123456789UL, 'appl', 'gui ');
Root & root = document.root <Root> ();
root.message.send (20, 2.f);
root.message.send (25, 3.f);
document.commit ();
// observer will read *only one* message,
// the second with '25' and '3.f' as values
// see below on how to read messages in the observer

operator const std::tuple <Args...> &

operator const std::tuple <Args...> & () const;

Get the last message in MessageCached, or flip_FATAL if no message is present.

Example :

void  Observer::document_changed (Root & root)
{
   // considering the example in 'send' upper
   std::tuple <int, float> val = root.message;
   // val is (25, 3.f)
}

has_value

bool  has_value () const;

Returns true iff a message is present in MessageCached.

Example :

void  Observer::document_changed (Root & root)
{
   // considering the example in 'send' upper
   bool ok = root.message.has_value ();
   // ok is true
}

value

const std::tuple <Args...> &  value () const;

Get the last message in MessageCached, or flip_FATAL if no message is present.

Example :

void  Observer::document_changed (Root & root)
{
   // considering the example in 'send' upper
   std::tuple <int, float> val = root.message;
   // val is (25, 3.f)
}

has_before

bool  has_before () const;

Returns true iff a message before is present in MessageCached.

This is only true if two consecutive messages where separated by exactly one commit.

Example :

void  Observer::document_changed (Root & root)
{
   // considering the example in 'send' upper
   bool ok = root.message.has_before ();
   // ok is false
}

before

const std::tuple <Args...> &  before () const;

Get the last message before in MessageCached, or flip_FATAL if no message before is present.

Example :

Root & root = document.root <Root> ();
root.message.send (20, 2.f);
root.message.send (25, 3.f);
document.commit ();
// in the observer call
// - before does not exist
// - value is (25, 3.f)
root.message.send (21, 4.f);
root.message.send (27, 5.f);
// in the observer call :
// - before is (25, 3.f)
// - value is (27, 5.f)