Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members

UGroup Class Reference

Logical "grouping" container. More...

#include <ugroup.hpp>

Inheritance diagram for UGroup:

UTrow List of all members.

Public Types

enum  ChildListType { ATTR_LIST, ELEM_LIST }
enum  RemoveMode { REMOVE_FROM_PARENTS = -1, NO_DEL = false, AUTO_DEL = true }

Public Member Functions

 UGroup (const UArgs &a=UArgs::none)
 constructor; see also creator shortcut ugroup()
virtual ~UGroup ()
 see important notes on recursive deletion
virtual const UStylegetStyle (UContext *) const
 returns the contextual UStyle of this object
UGroupaddlist (const UArgs &)
 adds a list of children to the end of the object's child list
virtual void add (UBrick *child, bool update=true)
virtual void add (UBrick &child, bool update=true)
virtual void add (ULink *child, bool update=true)
virtual void add (ULink &child, bool update=true)
 adds a 'child' to the end of the object's child list
virtual void addOnce (UBrick *child, bool update=true)
virtual void addOnce (UBrick &child, bool update=true)
 adds a 'child' if not already in the child list
virtual void insert (int pos, UBrick *child, bool update=true)
virtual void insert (int pos, UBrick &child, bool update=true)
virtual void insert (int pos, ULink *child, bool update=true)
virtual void insert (int pos, ULink &child, bool update=true)
 insert a 'child' into the object's child list at this position
virtual void remove (UBrick *child, bool auto_delete=true, bool update=true)
virtual void remove (UBrick &child, bool auto_delete=true, bool update=true)
 removes 'child' OR deletes 'child' and its descendants
virtual void remove (int pos, bool auto_delete=true, bool update=true)
 removes OR deletes the child at position 'pos' and its descendants
virtual void removeAll (bool auto_delete=true, bool update=true)
 removes all children OR deletes all children and their descendants
virtual int getChildCount () const
 returns the number of children
virtual UBrick ** getChildren () const
virtual UBrick ** getChildren (int &child_count) const
 returns a copy of the child list
virtual int getChildren (std::vector< UBrick * > &) const
 returns a copy of the child list
virtual UBrickgetChild (int pos) const
 returns the child at this position in the child list
virtual UBrickgetChild (UListPos &) const
 efficient API to retreive children iteratively
virtual UBrickgetChild (bool(predicate)(const UBrick *child), UListPos &=UListPos::none) const
virtual UBrickgetChild (UListCall &predicate, bool &status, UListPos &=UListPos::none) const
 searches for children that statisfy a certain condition
virtual int getChildPos (const UBrick &obj, int nth=0) const
virtual int getChildPos (const UBrick *obj, int nth=0) const
 returns the position of the Nth occurence of 'obj' in the child list (returns -1 if not found)
virtual int getChildPos (const UBrick *obj, UListPos &) const
 returns the position of the next occurence of 'obj' in the child list (returns -1 if not found)
virtual UBrick ** getAttrs () const
virtual UBrick ** getAttrs (int &child_count) const
 returns a copy of the attribute list (works in the same way as getChildren()).
virtual int getAttrCount () const
 returns the number of attributes.
virtual void addAttr (UBrick *child, bool update=true)
virtual void addAttr (UBrick &child, bool update=true)
virtual void addAttr (ULink &child, bool update=true)
 adds an attribute (works in the same way as add()).
virtual void insertAttr (int pos, UBrick *child, bool update=true)
virtual void insertAttr (int pos, UBrick &child, bool update=true)
virtual void insertAttr (int pos, ULink &child, bool update=true)
 adds an attribute (works in the same way as insert()).
virtual void removeAttr (UBrick *child, bool auto_delete=true, bool update=true)
virtual void removeAttr (UBrick &child, bool auto_delete=true, bool update=true)
 removes an attribute (works in the same way as remove()).
virtual void removeAllAttr (bool auto_delete=true, bool update=true)
 removes all attributes (works in the same way as removeAll()).
virtual UBrickgetAttrChild (UListPos &from) const
virtual UBrickgetAttrChild (bool(predicate)(const UBrick *child), UListPos &=UListPos::none) const
virtual UBrickgetAttrChild (UListCall &predicate, bool &stat, UListPos &from) const
 searches in the attribute list (works in the same way as getChild()).
virtual UBrickgetAnyChild (UListPos &from) const
virtual UBrickgetAnyChild (bool(predicate)(const UBrick *), UListPos &from=UListPos::none) const
virtual UBrickgetAnyChild (UListCall &predc, bool &stat, UListPos &from=UListPos::none) const
 searches in the attribute then in the element list (works in the same way as getChild()).
virtual UStr copyText (bool recursive=true) const
virtual void copyText (UStr &, bool recursive=true) const
 collates and returns the text that is enclosed in this object
virtual int getViews (std::vector< UView * > &) const
virtual const UStrgetTextSeparator () const
 text separator used by retreiveText() for separating enclosed children
virtual void show (bool=true)
 shows the object if argument is true; hides it if false
virtual void hide ()
 same as: show(false)
virtual void highlight (bool state)
 highlight the object (and brings it to the top if it is a window)
virtual void update ()
virtual void update (UUpdate upmode)
 updates this object's paint and/or layout
virtual void close (int status)
 closes this object Default behavior: hides the object (same as show(false))
virtual void closeWin (int status)
 closes the first window (UDialog, UMenu...) that contains this object
virtual void addImpl (ChildListType, UBrick *child, class ULink *childlink, int pos, bool update, bool *should_update)
virtual void removeImpl (ChildListType, UBrick *child, class ULink *prevlink, RemoveMode remove_mode, bool update, bool *should_update)
ULink * getChildImpl (ChildListType, const UBrick *child, int nth, class ULink *&prevlink, int *pos) const
ULink * getChildImpl (ChildListType, int pos, class ULink *&prevlink) const
ULink * getChildImpl (ChildListType, UListPos &from) const
ULink * getChildImpl (ChildListType, UListCall &, bool &status, UListPos &from) const
 [impl] implementation of public add/remove/getChild methods
virtual void fire (class UEvent &, const class UOn &) const
 [impl] fires callback functions and callback methods.
virtual void destructs ()
 [impl] see important note on subclassing

Static Public Member Functions

static const UStylemakeStyle ()
 creates the Style of this object
static void closeWin (class UEvent &, int status)

Static Public Attributes

static UStylestyle = null
 corresponding Ubit UStyle

Friends

UGroupugroup (const UArgs &a=UArgs::none)
 creator shortcut that is equivalent to *new UGroup()
UCall & ucloseWin (int status=0)
 callback that closes the first window (UDialog, UMenu...) that contains this object

Detailed Description

Logical "grouping" container.

This class is used for grouping objects. it is a very lightweight and general container. by opposition to the UBox class (and subclasses) UGroup objects do not have Views and, thus, do not correspond to any specific location on the Screen (there are just genuine containers)

See:


Constructor & Destructor Documentation

UGroup::UGroup const UArgs a0 = UArgs::none  ) 
 

constructor; see also creator shortcut ugroup()

!init

UGroup::~UGroup  )  [virtual]
 

see important notes on recursive deletion

refer to: UBrick::~UBrick()


Member Function Documentation

void UGroup::add ULink &  child,
bool  update = true
[virtual]
 

adds a 'child' to the end of the object's child list

Arguments:

  • graphics are updated if 'update' is true. clients should call the update() function later otherwise. (this is useful when many children are added: graphics update then take place only one time)
  • the same child can be added several times to the child list.

UGroup & UGroup::addlist const UArgs  ) 
 

adds a list of children to the end of the object's child list

Notes:

  • this function is NOT virtual and returns the object
  • this function updates graphics if the list contains UProp, UElem, or UGroup objects Exemple:
  • UGroup& g = ugroup(); g.addlist(UColor::red + UFont::bold + "abcd"):

void UGroup::close int  status  )  [virtual]
 

closes this object Default behavior: hides the object (same as show(false))

Can be redefined by subclasses for appropriate behaviors (such as object deletion, saving or freeing data, etc.)

Note: status is only meaningful for UWin subclasses.

See also: UBox::closeWin(), UWin::close()

void UGroup::closeWin int  status  )  [virtual]
 

closes the first window (UDialog, UMenu...) that contains this object

Notes:

void UGroup::copyText UStr ,
bool  recursive = true
const [virtual]
 

collates and returns the text that is enclosed in this object

'recursive' means that the text included in descendants is also collated.

Notes:

void UGroup::destructs  )  [virtual]
 

[impl] see important note on subclassing

destructs() unlinks the object from its parents and destroys children (when applicable). Any class that redefines removingFrom() MUST HAVE A DESTRUCTOR that calls destructs().

UBrick * UGroup::getChild UListCall &  predicate,
bool &  status,
UListPos = UListPos::none
const [virtual]
 

searches for children that statisfy a certain condition

usage:

  • returns the first child that verifies the condition if UListPos == none (the default)
  • returns the next child that verifies the condition otherwise
  • use UListPos::reset() to rescan the list

Examples:


 UBrick* child = parent.getChild(&UBrick::isInstance<UButton>);
 or:
 UListPos lpos;
 while ((child = parent.getChild(&UBrick::isInstance<UStr>, lpos)))  {....}
 

UBrick * UGroup::getChild UListPos  )  const [virtual]
 

efficient API to retreive children iteratively

Notes:

  • use UListPos::reset() to rescan the list

Example:


 UBrick* child = null;
 UListPos lpos;

 while ((child = parent.getChild(lpos)))  {
 cout << "Class: " << child->getClassName() << endl;
 }

 // rescan the child list from the beginning
 lpos.reset();
 while ((child = parent.getChild(lpos)))  {....}
 

UBrick * UGroup::getChild int  pos  )  const [virtual]
 

returns the child at this position in the child list

Arguments:

  • 'pos' = 0 means "first child" and 'pos' = -1 means "last child"
  • returns null if 'pos' is out of range (doesn't generate an error).

Note: use getChild(UListPos&) or getChildren() is you need to access many children in the child list: this will be more efficient than multiple calls to getChild(int pos)

ULink * UGroup::getChildImpl ChildListType  ,
UListCall &  ,
bool &  status,
UListPos from
const
 

[impl] implementation of public add/remove/getChild methods

these methods are called by add(), remove(), getChild() and operator delete. They can can possibly be redefined by subclasses. Note however its is generally necessary to redefine all of them simultaneously as these methods call each other

int UGroup::getChildPos const UBrick obj,
UListPos
const [virtual]
 

returns the position of the next occurence of 'obj' in the child list (returns -1 if not found)

works in the same way as getChild(UListPos&).

int UGroup::getChildPos const UBrick obj,
int  nth = 0
const [virtual]
 

returns the position of the Nth occurence of 'obj' in the child list (returns -1 if not found)

'Nth' = 0 means "search first occurence", 'Nth' = 1 "search second occurence", etc.

See also: getChildPos(const UBrick*, UListPos&) for multiple calls.

int UGroup::getChildren std::vector< UBrick * > &   )  const [virtual]
 

returns a copy of the child list

returns the number of children and intializes the vector of children. Note: child_vect is not cleared : children are added to the child_vect argument if its is not empty See also: UBrick** getChildren() and getChild() (and other variants).

UBrick ** UGroup::getChildren int &  child_count  )  const [virtual]
 

returns a copy of the child list

Returned value:

  • returns null if there are no children.
  • returns the child list if there is at least one child. This list must be destroyed by clients by calling delete[].

Note:

  • Ubit objects can be added several times to the same parent. So, be careful when you delete children not to delete them twice (or more!) as some of them may appear several times in the child list. See also:
  • getChild() and other variants.

virtual const UStyle& UGroup::getStyle UContext *   )  const [virtual]
 

returns the contextual UStyle of this object

This virtual function calls the makeStyle() static function that was redefined for this specific class

Reimplemented in UTrow.

void UGroup::insert int  pos,
ULink &  child,
bool  update = true
[virtual]
 

insert a 'child' into the object's child list at this position

Arguments:

  • pos = 0 means "before the first child"
  • pos = -1 means "after the last child"
  • a non fatal error if produced if 'pos' is out of range

  • this function updates graphics if 'update' is true. clients should call the update() function later otherwise. (this is useful when many children are added: graphics update then take place only one time)

const UStyle & UGroup::makeStyle  )  [static]
 

creates the Style of this object

This static function is redefined by each class that derives from UGroup. It is called by the virtual function UGroup::getStyle()

Reimplemented in UTrow.

void UGroup::remove int  pos,
bool  auto_delete = true,
bool  update = true
[virtual]
 

removes OR deletes the child at position 'pos' and its descendants

Works in the same way as: remove(UBrick&, bool, bool) except that:

  • 'pos' = 0 means "first child"
  • 'pos' = -1 means "last child"
  • a non fatal error if produced if 'pos' is out of range

void UGroup::remove UBrick child,
bool  auto_delete = true,
bool  update = true
[virtual]
 

removes 'child' OR deletes 'child' and its descendants

Arguments:

  • if auto_delete is false: the first occurence of 'child' is removed from the object's child list (other occurences are not removed if 'child' appears several times in the child list). 'child' is not deleted

  • if auto_delete is true: the first occurence of 'child' is removed AND DELETED if it has no other parent and is not pointed by an uptr()

  1. this option is generally preferable as this is the only way to free unreferenced objects
  2. when 'child' is deleted, its descendants are also be deleted (if they have no other parent and are not pointed by an uptr()). See: UGroup::~UGroup for details.
  3. 'child' is not deleted if it appears several times in the object's child list

  • this function updates graphics if 'update' is true. clients should call the update() function later otherwise. (this is useful when many children are removed: graphics update then take place only one time)

void UGroup::removeAll bool  auto_delete = true,
bool  update = true
[virtual]
 

removes all children OR deletes all children and their descendants

Works in the same way as: remove(UBrick&, bool, bool).

void UGroup::show bool  = true  )  [virtual]
 

shows the object if argument is true; hides it if false

see also: hide(), isShown(), isShowable()

void UGroup::update UUpdate  upmode  )  [virtual]
 

updates this object's paint and/or layout

Arguments:

  • no argument: updates layout then repaints
  • 'upmode' argument : updates according to this argument. see class UUpdate for details

Note:


Friends And Related Function Documentation

UCall& ucloseWin int  status = 0  )  [friend]
 

callback that closes the first window (UDialog, UMenu...) that contains this object

same effect as: UGroup::closeWin()

UGroup& ugroup const UArgs a = UArgs::none  )  [friend]
 

creator shortcut that is equivalent to *new UGroup()

Note: watch the case: UGroup is a class while ugroup() is a function!


The documentation for this class was generated from the following files:
Generated on Fri Mar 4 01:34:32 2005 for Ubit[Eric.Lecolinet@enst.fr] by  doxygen 1.4.1