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:

UBox UTrow UBar UButton UCheckbox UFlowbox UHbox UItem ULabel UListbox UPane UScrollbar USepar USpinbox UTable UTextbox UVbox UWin 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.
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"):

Reimplemented in UBox.

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()

Reimplemented in UMenu, UWin, and UFrame.

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:

  • copyTextTo() is more efficient than copyText()
  • getTextSeparator() is used for separating enclosed children when 'recursive' is true.

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 UBox, UVbox, UHbox, UBar, UFlowbox, USepar, ULabel, UItem, UButton, UFlatbutton, ULinkbutton, URadiobutton, UCheckbox, UTextbox, UListbox, USpinbox, UMenubar, UMenu, UPopmenu, UPane, UScrollbar, UTable, UTrow, UTcell, UWin, UDialog, UFrame, and UIncrust.

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 UBox, UVbox, UHbox, UBar, UFlowbox, ULabel, UItem, UButton, UTextbox, UListbox, USpinbox, UMenubar, UMenu, UPopmenu, UPane, UTable, UTrow, UTcell, UWin, UDialog, UFrame, and UIncrust.

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()

Reimplemented in UAlertbox, UWin, and UDialog.

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:

  • update() must be called after add() or remove() if their last argument was set to 'false'

Reimplemented in UBox, and UWin.


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 Thu May 19 11:39:25 2005 for Ubit[Eric.Lecolinet@enst.fr] by  doxygen 1.4.2