Document Class Reference

Declared in

flip/Document.h

class Document;

flip::Document is a type that represents a flip document.

Member Functions Synopsys

Constructor	Constructs the `Document`
Destructor	Destructs the `Document`

Manipulating

`set_label`	Sets the label of the current modifications of the document
`set_metadata`	Sets the metadata of the current modifications of the document
`commit`	Commits the current modifications of the document
`commit_no_tx`	Commits the current modifications of the document
`revert`	Reverts the current modifications of the document
`push`	Pushes the transactions to the upstream
`pull`	Pulls document modifications from the upstream

Transaction

`execute_forward`	Executes a transaction on a document in forward direction
`execute_backward`	Executes a transaction on a document in backward direction
`execute_correct_forward`	Executes and corrects a transaction on a document in forward direction
`execute_correct_backward`	Executes and corrects a transaction on a document in backward direction

Observing

controller

Returns the current controller source of modification

Input/Ouput

`write`	Write the current state of the document to an intermediate representation format
`read`	Read from an intermediate representation format

Accessing Objects

`root`	Returns the root object
`object`	Returns an object given its unique flip reference number
`object_ptr`	Returns an object pointer given its unique flip reference number, or `nullptr`

Member Functions

Constructor

Document (const DataModelBase & data_model, DocumentObserverBase & observer, DocumentValidatorBase & validator, uint64_t user_id, uint32_t manufacturer_id, uint32_t component_id);
Document (const DataModelBase & data_model, DocumentObserverBase & observer, uint64_t user_id, uint32_t manufacturer_id, uint32_t component_id);
Document (const DataModelBase & data_model, DocumentValidatorBase & validator, uint64_t user_id, uint32_t manufacturer_id, uint32_t component_id);
Document (const DataModelBase & data_model, uint64_t user_id, uint32_t manufacturer_id, uint32_t component_id);

Constructs the document from a data model, an optional observer, and optional validator, a unique user id, a manufacturer id and a component id.

The data model represents the blueprint or template the document is going to rely on. The data model is previously defined and used for the document.

The unique user identifier is a 64-bit unsigned number that represents a user in a unique way.

The manufacturer id shall represents your company abbreviated name in a four char code format.

The component id shall represents the component the document represents in a four char code format. Typically this could be gui.

WARNING: the tuple make of user identifier, manufacturer id and component id must be guanranteed unique for every documents connected together

See Ref for more details about user identifiers.

Destructor

~Document ();

Destructor.

`set_label`

void  set_label (std::string label);

Sets the label (ie. name) of the current modifications of the document. This metadata will be added to the transaction at commit stage.

This is typically use to display the undo/redo name in the Edit menu of the menubar.

If called multiple times before commit, only the last state of the metadata is taken into account at commit stage.

Example :

Root & root = document.root <Root> ();
root.notes.emplace <Note> (2.0, 4.0);
document.set_label ("Add note");
Transaction tx = document.commit ();
// the transaction contains the new note modification in 'root.notes'
// as well as the metadata label "Add note"

`set_metadata`

void  set_metadata (std::string key, std::string value);

Sets the metadata value for key of the current modifications of the document. This metadata will be added to the transaction at commit stage.

If called multiple times before commit, only the last state of the metadata is taken into account at commit stage.

This is a more general version of set_label. Actually, set_label calls this methods with the key "label".

This can be used to present even more textual informations for undo/redo operations, for example detailing the nature of the change.

`commit`

Transaction commit ();

Commits the current modifications of the document and returns the resulting transaction. The modifications are validated through the validator if the document has one, and will throw if the document state is invalid.

Once the function returns, the document is valid from a validation point of view and the transaction is put on the push stack for later upstream synchronization.

`commit_no_tx`

void commit_no_tx ();

Commits the current modifications of the document without returning a transaction. The modifications are validated through the validator if the document has one, and will throw if the document state is invalid.

Once the function returns, the document is valid from a validation point of view and the transaction is put on the push stack for later upstream synchronization.

In the case where the document is not connected to an upstream, this performs an important optimisation since no transaction is produced and there is no need to store a transaction.

`revert`

void revert ();

Reverts the current modifications of the document.

`push`

void push ();

Pushes the transactions in the push stack to the upstream and empty the push stack. If no upstream is present then this function will just empty the push stack.

WARNING: Even if not connected to an upstream, it is important to call push regularly to empty the push stack.

`pull`

void pull ();

Pulls document modifications from the upstream. If no upstream is present then this function does nothing.

If the document contains modifications, they are temporarily saved and rollbacked, then external modifications are applied, and the local modifications are reapplied. If the local modifications cannot be reapplied, then they are dropped silently.

`execute_forward`

bool  execute_forward (const Transaction & tx, bool undo_mode_flag = false);

Executes a transaction on a document in forward direction. Returns true if the execution was successful, false otherwise. Executing a transaction does not call the validator nor commits the transaction.

If undo_mode_flag is set to true, then the instructions of the transaction that are marked to be out of undo (through a prior call to disable_in_undo) won't be executed unless the top object disabled in undo has a container parent enabled in undo and the top object was either added or removed. This is the default mode when using flip History class.

`execute_backward`

bool  execute_backward (const Transaction & tx, bool undo_mode_flag = false);

Executes a transaction on a document in backward direction. Returns true if the execution was successful, false otherwise. Executing a transaction does not call the validator nor commits the transaction.

If undo_mode_flag is set to true, then the instructions of the transaction that are marked to be out of undo (through a prior call to disable_in_undo) won't be executed. This is the default mode when using flip History class.

`execute_correct_forward`

bool  execute_correct_forward (const Transaction & tx, bool undo_mode_flag = false);

Executes and corrects a transaction on a document in forward direction. Returns true if the execution was successful, false otherwise. Executing a transaction does not call the validator nor commits the transaction.

Correcting allows to force a transaction to execute if possible. Transaction instructions are similar to compare & exchange processor instructions. Only if the old state of the document matches the instruction old value then the new value is applied. In this case correcting allows the virtual machine to force the execution and change the instruction to match virtual machine constraints.

`execute_correct_backward`

bool  execute_correct_forward (const Transaction & tx, bool undo_mode_flag = false);

Executes and corrects a transaction on a document in backward direction. Returns true if the execution was successful, false otherwise. Executing a transaction does not call the validator nor commits the transaction.

`controller`

Controller  controller () const;

When called from document observer callback, returns the current controller source of modification. If the callback resulted from a pull operation, the returned controller is the last one from the pull queue.

enum class Controller
{
   NONE,          (1)
   SELF,          (2)
   UNDO,          (3)
   READ,          (4)
   LOCAL,         (5)
   EXTERNAL,      (6)
   ACKNOWLEDGED,  (7)
   DENIED,        (8)
};

Returned when called outside of an observer callback
Returned when originated to this document
Returned when originated from an undo operation (History)
Returned when originated from a read operation
Returned when originated from a local change
Returned when originated from a remote change
Returned when the server accepted one of the pushed transaction
Returned when the server rejected one of the pushed transaction

`write`

BackEndIR   write ();

Write the current state of the document (with its potential modifications) to an intermediate representation format backend.

The resulting object can be used with concrete backends format such as BackEndBinary or BackEndMl to store them on a media.

See BackEndMl or BackEndBinary for an example of use of this method.

`read`

void  read (BackEndIR & backend);

Read from an intermediate representation format backend. Internally this will create a transaction that represents the difference between the new backend and the current state of the document. As such, the document modification are not commited at the end of this operation.

See BackEndMl or BackEndBinary for an example of use of this method.

`root`

template <class T>   T & root ();

Returns the root object of the document.

`object`

template <class T>   T & object (const Ref & ref);

Returns an object given its unique flip reference number. The function will throw if the reference number does not exist in the document or if the resulting object cannot be casted to T.

See Ref for more details.

`object_ptr`

template <class T>   T * object_ptr (const Ref & ref);

Returns an object given its unique flip reference number. The function will return nullptr if the reference number does not exist in the document or if the resulting object cannot be casted to T.

See Ref for more details.

previous next