Object Class Reference
Inherits from |
|
Declared in |
|
class Object; |
flip::Object
is the base type to provide custom flip classes. In the following, MyClass
denotes a custom flip class.
Member Functions Synopsys
Constructs the | |
Destructs the | |
Assigns value |
Document Management
Returns the document to which the object is attached to | |
Returns the unique reference number of the object | |
Returns | |
Returns | |
Returns | |
Returns | |
Returns a reference to a parent in the current parent chain of the object | |
Disables the record state modification in history | |
Inherits the record state modification in history | |
Returns | |
Reverts all the changes made to the object and its children if any | |
Replaces the content of the object with the content of the provided object | |
Replaces the content of the object with the content of the provided object by moving it |
Miscellaneous
Returns the current or previous parent of the object | |
Returns an entity |
Member Functions
Constructor
Object (); (1) |
MyClass (flip::Default &); (2) |
Object (const Object & other); (3) |
- Default constructor.
- Default flip constructor. See discussion below.
- Copy constructor. Constructs the object with the value of
other
.
For readability or legacy support, it might be convenient for a new flip object not to be default constructed with 0 values and/or empty containers. One might also want to not provide a default constructor.
At the same time, the flip virtual machine expect to be have a way to construct a flip object, and this newly constructed flip object to have only 0 values and empty containers.
For this reason, the flip::Default
constructor was introduced. When the VM is constructing a new object, it will instantiate the flip::Default
constructor instead of the C++ default constructor if the former exist. Flip default constructed object shall only have 0 values and empty containers.
Example:
class MyClass : public flip::Object |
{ |
public: |
MyClass () : position (2), content () {} |
MyClass (flip::Default & d) : content (d) {} |
flip::Int position; |
MyOtherClass content; |
}; |
class MyOtherClass : public flip::Object |
{ |
MyOtherClass () : volume (2) {} |
MyOtherClass (flip::Default & d) {} |
flip::Float volume; |
}; |
Destructor
~Object (); |
Destructor.
operator =
Object & operator = (const Object & other); |
Copy assignment operator.
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 |
move_assign
template <class T> |
void move_assign (T && rhs) |
Replaces the content of the object with the content of the provided object by moving it.
Important: The left hand side object needs to be bound to the document but the right hand side object needs not to be bound to a document. This is checked at runtime and will issue a flip_FATAL
if this pre-condition is not met.
When the right hand object can be moved, this function should be prefered to assign
as it does important optimizations internally.
Example :
// initially : |
// note.position == 1 |
// note.duration == 3 |
Note note2; |
note2.position = 2; |
note2.duration = 1; |
note.move_assign (std::move (note2)); |
// now : |
// note.position == 2 |
// note.duration == 1 |
parent
template <class T> T & parent (); |
Parent & parent (); |
Returns the current or previous parent of the object.
Example:
object.parent <MyClass> (); (1) |
object.parent ().ptr <MyClass> (); (2) |
object.parent ().before <MyClass> (); (3) |
object.parent ().before_ptr <MyClass> (); (4) |
- Return the current parent as
MyClass
, throws if casting is incorrect - Return the current parent as
MyClass
, returnsnullptr
if casting is incorrect - Return the previous parent as
MyClass
, throws if casting is incorrect - Return the previous parent as
MyClass
, returnsnullptr
if casting is incorrect
entity
Entity & entity (); |
Returns an entity. Entity
are described in details here.
Note: Entities can be made available in all types (including all basic types like Int
and Array
) by defining the macro flip_ENTITY_LOCATION
to flip_ENTITY_LOCATION_TYPE