ubit::UBrick Class Reference

Base class of objects that can be added to the scene graph (and of XML nodes): see important note on RECURSIVE DESTRUCTION. More...

#include <ubrick.hpp>

Inheritance diagram for ubit::UBrick:

List of all members.

Public Types
	ELEMENT_NODE = 1
	ATTRIBUTE_NODE = 2
	TEXT_NODE = 3
	CDATA_SECTION_NODE = 4
	ENTITY_REFERENCE_NODE = 5
	ENTITY_NODE = 6
	PROCESSING_INSTRUCTION_NODE = 7
	COMMENT_NODE = 8
	DOCUMENT_NODE = 9
	DOCUMENT_TYPE_NODE = 10
	DOCUMENT_FRAGMENT_NODE = 11
	NOTATION_NODE = 12
enum	{   ELEMENT_NODE = 1, ATTRIBUTE_NODE = 2, TEXT_NODE = 3, CDATA_SECTION_NODE = 4,   ENTITY_REFERENCE_NODE = 5, ENTITY_NODE = 6, PROCESSING_INSTRUCTION_NODE = 7, COMMENT_NODE = 8,   DOCUMENT_NODE = 9, DOCUMENT_TYPE_NODE = 10, DOCUMENT_FRAGMENT_NODE = 11, NOTATION_NODE = 12 }
Public Member Functions
virtual unsigned short	getNodeType () const
	returns the XML node type.
virtual const UStr *	getNodeName () const
	return the XML node name.
virtual const UStr *	getNodeValue () const
	return the XML node value.
virtual UBrick *	brickCast ()
	dynamic cast (
virtual bool	isChildOf (const UGroup &parent, bool indirect=true) const
	returns true if this object a child of 'parent'.
UParentIter	pbegin () const
	returns an iterator to the beginning of the list of direct parents.
UParentIter	pend () const
	returns an iterator to the end of the parent list (
virtual UParents &	parents () const
	returns the list of direct parents (
virtual bool	hasFullParent () const
virtual bool	hasOnlyPseudoParents () const
virtual UGroup *	getParent (int pos=0) const
	returns the Nth direct parent.
template<class CC>
CC *	findParent () const
	returns first the direct or indirect parent with that class.
virtual int	getBoxParents (std::vector< UBox * > &parvect) const
	retrieves direct and indirect parents that are boxes.
virtual UBox *	getParent (const UView *) const
	returns the direct or indirect parent that contains this view.
virtual UView *	getParentView (const UView *) const
	returns the direct or indirect parent's view that contains this view.
virtual UBox *	getParent (const UEvent &) const
virtual UView *	getParentView (const UEvent &) const
	returns the direct or *indirect* UBox parent (resp.
virtual void	removeFromParents (bool update_parents=true)
	[impl] removes this object from all direct parents.
UChildIter	abegin () const
	returns an iterator to the beginning the attribute list.
UChildIter	aend () const
	returns an iterator to the end of the attribute list (
virtual UChildren &	attributes () const
	returns the attribute list (
virtual void	addAttr (const UChild &attribute)
	adds an attribute (that should derive from UAttribute) to the end of the attribute list.
virtual void	removeAllAttrs (bool autodel=true)
	removes all attributes.
virtual bool	fire (UEvent &, const UOn &condition) const
	fires callback functions that match this condition.
virtual void	update ()
	updates object graphics.
UBrick &	autoUpdate (bool state)
	speficies update policy when the object is modified.
bool	isAutoUpdate () const
	return current update policy:
bool	isConst () const
	logical constness: see setConst().
void	setConst ()
	logical constness.
UMask	getBModes () const
	[impl] returns the current B-Modes bitmask.
bool	hasBMode (UMask modes) const
	[impl] true if ONE of these B-Modes is verified (see class UMode for details).
void	addBModes (UMask modes)
	[impl] add these modes to the B-Modes bitmask.
void	removeBModes (UMask modes)
	[impl] remove these modes from the B-Modes bitmask.
Protected Member Functions
	UBrick ()
	the UBrick constructor can anly be called by subclasses.
	UBrick (UMask b_modes)
	the UBrick constructor can anly be called by subclasses.
virtual	~UBrick ()
	BEWARE: subclasses that have a destructor MUST call destructs() in their destr.
virtual void	addingTo (UChild *self, UGroup *parent)
	called when this object is added to a parent.
virtual void	removingFrom (UChild *self, UGroup *parent)
	called when this object is removed from a parent (SEE DETAILS!).
virtual void	destructs ()
	unlinks the object from its parents and destroys its children.
virtual bool	canPtrDelete () const
	returns true if the object should be deleted when its last uptr<> is removed.
Friends
UChild	operator/ (const UCond &, UBrick &)
UChild	operator/ (const UCond &, UBrick *)
	conditional expression for callback functions and conditionnal objects.

---

Detailed Description

Base class of objects that can be added to the scene graph (and of XML nodes): see important note on RECURSIVE DESTRUCTION.

XML:

• a Ubit scene graph can be seen as a XML document. UBrick plays the same role as "Node", the base class of all XML nodes.

RECURSIVE DESTRUCTION OF CHILDREN

• the destruction of a "brick" triggers the delection of ALL its children (and descendants) that are NOT "referenced elsewhere"
• an object is "referenced elsewhere" if it has another parent in the scene graph (than the one being destructed) *OR* if it is pointed by a uptr<> (Ubit Smart Pointer).

SMART POINTERS provide automatic memory management and prevent errors: an object that is pointed by one (or several) uptr<>

• is not destroyed when its parents are destroyed in the scene graph
• is automatically destroyed when the last uptr<> that pointed to it is removed

    uptr<UBox> box = new UBox();            // 'box' is a Ubit Smart Pointer
    uptr<UButton> btn = ubutton("Do It!");  // ubutton() == *new UButton()
    box->add(*btn);             // the UButton becomes a child of the UBox

    box = null;  // the UBox is destroyed because it is no longer pointed
                 // by a uptr and has no parents; its UButton child is 
                 // not destroyed beause it is still pointed by 'btn'

    btn = null;  // the UButton is destroyed because it is no longer pointed
                 // by a uptr and has no parents
  

NOTES:

• recursive destruction makes standard C++ pointers and C++ references DANGEROUS as they may still point to objects that have been implicitely destructed
• a uptr<> should point to an object allocated in the heap or in static memory, but NOT in the stack (because C++ automatically deallocates objects in the stack when functions return)

See also:

: the uptr<> template for details.

---

Constructor & Destructor Documentation

virtual ubit::UBrick::~UBrick

(

)

[protected, virtual]

BEWARE: subclasses that have a destructor MUST call destructs() in their destr.

See also:

: removingFrom() for details.

---

Member Function Documentation

UChildIter ubit::UBrick::abegin

(

)

const

returns an iterator to the beginning the attribute list.

UChildIter is a child iterator. It is compatible with standard STL algorithms. This example prints the class name of the attributes of an object :

    UBrick* obj = ...;
    for (UChildIter c = obj->abegin(); c != obj->aend(); ++c)
        cout << (*c)->getClassName() << endl;
 

See also:

also: attributes(), aend(), pbegin(), pend()

Reimplemented in ubit::UGroup.

UChildIter ubit::UBrick::aend

(

)

const

returns an iterator to the end of the attribute list (

See also:

abegin()).

Reimplemented in ubit::UGroup.

virtual UChildren& ubit::UBrick::attributes

(

)

const [virtual]

returns the attribute list (

See also:

abegin()).

Reimplemented in ubit::UGroup.

UBrick & ubit::UBrick::autoUpdate

(

bool

state

)

speficies update policy when the object is modified.

• if 'state' is true, the object if automatically updated when its is modified (either by adding/removing children for UGroup and subclasses, or by setting new values for UData, UStr, UProp ...)
• if 'state' is false, the update() function must be called explicitely to update the graphics. This can be useful in certain cases to avoid intermediate updates in order to to speed up rendition

Reimplemented in ubit::UGroup.

virtual UBrick* ubit::UBrick::brickCast

(

)

[virtual]

dynamic cast (

See also:

UObject).

Reimplemented from ubit::UObject.

UBox * ubit::UBrick::getParent

(

const UView *

)

const [virtual]

returns the direct or indirect parent that contains this view.

intermediate UGroup parents are ignored (ie. traversed) by this function.

UGroup * ubit::UBrick::getParent

(

int

pos = 0

)

const [virtual]

returns the Nth direct parent.

returns the first parent if 'pos' = 0 and the last parent if 'pos' = -1. returns null and issues an error message if 'pos' is out of range. Notes:

• objects can have several parents
• getParents() is more efficient for accessing multiple parents.

UView * ubit::UBrick::getParentView

(

const UEvent &

)

const [virtual]

returns the direct or *indirect* UBox parent (resp.

parent's view) that contains this event. intermediate UGroup parents are ignored (ie. traversed) by this function.

UView * ubit::UBrick::getParentView

(

const UView *

)

const [virtual]

returns the direct or indirect parent's view that contains this view.

intermediate UGroup parents are ignored (ie. traversed) by this function.

bool ubit::UBrick::isAutoUpdate

(

)

const

return current update policy:

See also:

autoUpdate().

bool ubit::UBrick::isChildOf	(	const UGroup &	parent,
		bool	indirect = true
	)			const [virtual]

returns true if this object a child of 'parent'.

'indirect' specifies if indirect childhood is taken into account.

virtual UParents& ubit::UBrick::parents

(

)

const [virtual]

returns the list of direct parents (

See also:

pbegin()).

UParentIter ubit::UBrick::pbegin

(

)

const

returns an iterator to the beginning of the list of direct parents.

UParentIter is a parent iterator. It is compatible with standard STL algorithms. This example prints the class name of the direct parents of an object :

    UBrick* obj = ...;
    for (UParentIter p = obj->pbegin(); p != obj->pend(); ++p)
        cout << (*p)->getClassName() << endl;
 

See also:

also: parents(), abegin(), aend().

UParentIter ubit::UBrick::pend

(

)

const

returns an iterator to the end of the parent list (

See also:

pbegin()).

void ubit::UBrick::removeFromParents

(

bool

update_parents = true

)

[virtual]

[impl] removes this object from all direct parents.

notes:

• objects can have several parents!
• this function is potentially dangerous: UGroup::remove() methods should be prefered when possible.

virtual void ubit::UBrick::removingFrom	(	UChild *	self,
		UGroup *	parent
	)			[protected, virtual]

called when this object is removed from a parent (SEE DETAILS!).

BEWARE: UBrick subclasses that redefine removingFrom() MUST have a destructor that calls destructs().

Details: polymorphism does not work in C++ destructors. Hence, if class X has no destructor, X::removingFrom() (that is called by X::destructs()) won't be called when a X instance is deleted.

Reimplemented in ubit::UMode, and ubit::UViewStyle.

void ubit::UBrick::setConst

(

)

logical constness.

setConst() makes this object logically constant: any attempt to modify it will produce an error. Note that constness can't be changed once set. See also: UMode::UCONST

---

Friends And Related Function Documentation

UChild operator/	(	const UCond &	cond,
		UBrick *	b
	)			[friend]

conditional expression for callback functions and conditionnal objects.

example:

    struct Demo {
       void saveFile();
       void showMsg(const char*);
       ....
    };
    Demo* d = new Demo;
    // NB: ubutton(...) returns *new UButton(...)
    UBox& b = ubutton(" Save..." + UOn::action / ucall(d, &Demo::saveFile));
    ....
    b.addAttr(UOn::enter / ucall(d, "Saves the file", &Demo::showMsg)
 

See also:

: addAttr(), UCall, UOn, UFlag for more details.

---

The documentation for this class was generated from the following files:

• ubrick.hpp
• ubrick.cpp

---