---

TGroup Class Reference

TGroup objects and their derivatives provide the central driving power to TVision. More...

#include <views.h>

Inheritance diagram for TGroup::

List of all members.

Public Methods
	TGroup (const TRect &bounds)
	~TGroup ()
virtual void	shutDown ()
ushort	execView (TView *p)
virtual ushort	execute ()
virtual void	awaken ()
void	insertView (TView *p, TView *Target)
void	remove (TView *p)
void	removeView (TView *p)
void	resetCurrent ()
void	setCurrent (TView *p, selectMode mode)
void	selectNext (Boolean forwards)
TView*	firstThat (Boolean(*func)(TView *, void *), void *args)
Boolean	focusNext (Boolean forwards)
void	forEach (void(*func)(TView *, void *), void *args)
void	insert (TView *p)
void	insertBefore (TView *p, TView *Target)
TView*	at (short index)
TView*	firstMatch (ushort aState, ushort aOptions)
short	indexOf (TView *p)
Boolean	matches (TView *p)
TView*	first ()
virtual void	setState (ushort aState, Boolean enable)
virtual void	handleEvent (TEvent &event)
void	drawSubViews (TView *p, TView *bottom)
virtual void	changeBounds (const TRect &bounds)
virtual ushort	dataSize ()
virtual void	getData (void *rec)
virtual void	setData (void *rec)
virtual void	draw ()
void	redraw ()
void	lock ()
void	unlock ()
virtual void	resetCursor ()
virtual void	endModal (ushort command)
virtual void	eventError (TEvent &event)
virtual ushort	getHelpCtx ()
virtual Boolean	valid (ushort command)
void	freeBuffer ()
void	getBuffer ()
Static Public Methods
TStreamable*	build ()
Public Attributes
TView*	current
TView*	last
TRect	clip
phaseType	phase
ushort*	buffer
uchar	lockFlag
ushort	endState
Static Public Attributes
const char* const	name
Protected Methods
	TGroup (StreamableInit)
virtual void	write (opstream &os)
virtual void*	read (ipstream &is)

---

Detailed Description

TGroup objects and their derivatives (called groups for short) provide the central driving power to TVision.

A group is a special breed of view. In addition to all the members derived from TView and TStreamable, a group has additional members and many overrides that allow it to control a dynamically linked list of views (including other groups) as though they were a single object.

We often talk about the subviews of a group even when these subviews are often groups in their own right.

Although a group has a rectangular boundary from its TView ancestry, a group is only visible through the displays of its subviews. A group draws itself via the draw() methods of its subviews. A group owns its subviews, and together they must be capable of drawing (filling) the group's entire rectangular bounds.

See also:

TView::draw

During the life of an application, subviews are created, inserted into groups, and displayed as a result of user activity and events generated by the application itself. The subviews can just as easily be hidden, deleted from the group, or disposed of by user actions (such as closing a window or quitting a dialog box).

Three derived object types of TGroup, namely TWindow, TDeskTop, and TApplication (via TProgram) illustrate the group and subgroup concept. The application typically owns a desktop object, a status line object, and a menu view object. TDeskTop is a TGroup derivative, so it, in turn, can own TWindow objects, which in turn own TFrame objects, TScrollBar objects, and so on.

TGroup overrides many of the basic TView methods in a natural way. TGroup objects delegate both drawing and event handling to their subviews. You'll rarely construct an instance of TGroup itself; rather you'll usually use one or more of TGroup's derived object types: TApplication, TDeskTop, and TWindow.

All TGroup objects are streamable, inheriting from TStreamable by way of TView. This means that TGroup objects (including your entire application group) can be written to and read from streams in a type-safe manner using the familiar C++ iostream operators.

Definition at line 2848 of file views.h.

---

Constructor & Destructor Documentation

TGroup::TGroup ( const TRect & bounds )

Calls TView::TView(bounds), sets ofSelectable and ofBuffered in options and sets eventMask to 0xFFFF. The members last, current, buffer, lockFlag and endState are all set to zero.

TGroup::~TGroup ( )

Hides the group using hide(), then disposes of each subview in the group using delete. Finally, the buffer is freed (if one).

TGroup::TGroup ( StreamableInit ) [protected]

Each streamable class needs a "builder" to allocate the correct memory for its objects together with the initialized virtual table pointers. This is achieved by calling this constructor with an argument of type StreamableInit.

---

Member Function Documentation

TView * TGroup::at ( short index )

Returns a pointer to the subview at `index' position in Z-order.

void TGroup::awaken ( ) [virtual]

Calls the TView::awaken() methods of each of the group's subviews in Z-order. Reimplemented from TView.

TStreamable * TGroup::build ( ) [static]

Called to create an object in certain stream-reading situations. Reimplemented from TView. Reimplemented in TDeskTop, TColorDialog, TDialog, TEditWindow, TFileDialog, TChDirDialog, and TWindow.

void TGroup::changeBounds ( const TRect & bounds ) [virtual]

Overrides TView::changeBounds(). Changes the group's bounds to `bounds' and then calls calcBounds() followed by TView::changeBounds() for each subview in the group. Reimplemented from TView.

ushort TGroup::dataSize ( ) [virtual]

Overrides TView::dataSize(). Returns total size of group by calling and accumulating dataSize() for each subview. See also: TGroup::getData , TGroup::setData Reimplemented from TView. Reimplemented in TColorDialog, and TChDirDialog.

void TGroup::draw ( ) [virtual]

Overrides TView::draw(). If a cache buffer exists (see TGroup::buffer data member), then the buffer is written to the screen using TView::writeBuf(). Otherwise, each subview is told to draw itself using a call to TGroup::redraw(). Reimplemented from TView.

void TGroup::drawSubViews ( TView * p, TView * bottom )

Calls TView::drawView() for each subview starting at `p', until the subview `bottom' is reached.

void TGroup::endModal ( ushort command ) [virtual]

If this group is the current modal view, endModal() terminates its modal state. Parameter `command' is passed to TGroup::execView() (which made this view modal in the first place), which returns `command' as its result. If this group is not the current modal view, it calls TView::endModal(). Reimplemented from TView.

void TGroup::eventError ( TEvent & event ) [virtual]

Is called whenever the modal TGroup::execute() event-handling loop encounters an event that cannot be handled. The default action is: if the group's owner is nonzero, eventError() calls its owner's eventError(). Normally this chains back to TApplication's eventError(). You can override eventError() to trigger appropriate action. See also: TProgram::eventError

ushort TGroup::execView ( TView * p )

execView() is the "modal" counterpart of the "modeless" insert() and remove() member functions. Unlike insert(), after inserting a view into the group, execView() waits for the view to execute, then removes the view, and finally returns the result of the execution. execView() is used in a number of places throughout TVision, most notably to implement TProgram::run() and to execute modal dialog boxes. execView() saves the current context (the selected view, the modal view, and the command set), makes `p' modal by calling p->setState(sfModal, True), inserts `p' into the group (if it isn't already inserted), and calls p->execute(). See also: TView::execute , TView::setState When p->execute() returns, the group is restored to its previous state, and the result of p->execute() is returned as the result of the execView() call. If `p' is 0 upon a call to execView(), a value of cmCancel is returned.

ushort TGroup::execute ( ) [virtual]

Overrides TView::execute(). execute() is a group's main event loop: it repeatedly gets events using getEvent() and handles them using handleEvent(). The event loop is terminated by the group or some subview through a call to endModal(). Before returning, however, execute() calls valid() to verify that the modal state can indeed be terminated. Reimplemented from TView.

TView * TGroup::first ( )

Returns a pointer to the first subview (the one closest to the top in Z-order), or 0 if the group has no subviews.

TView * TGroup::firstMatch ( ushort aState, ushort aOptions )

Returns a pointer to the first subview that matches its state with `aState' and its options with `aOptions'.

TView * TGroup::firstThat ( Boolean(* func)(TView *, void *), void * args )

firstThat() applies a user-supplied Boolean function `func', along with an argument list given by `args' (possibly empty), to each subview in the group (in Z-order) until `func' returns True. The returned result is the subview pointer for which `func' returns True, or 0 if `func' returns False for all items. The first pointer argument of `func' scans the subview. The second argument of `func' is set from the `args' pointer of firstThat(), as shown in the following implementation: TView *TGroup::firstThat(Boolean (*func)(TView *, void *), void *args) { TView *temp = last; if (temp == 0) return 0; do { temp = temp->next; if (func(temp, args) == True) return temp; } while(temp != last); return 0; }

Boolean TGroup::focusNext ( Boolean forwards )

Undocumented.

void TGroup::forEach ( void(* func)(TView *, void *), void * args )

forEach() applies an action, given by the function `func', to each subview in the group in Z-order. The `args' argument lets you pass arbitrary arguments to the action function: void TGroup::forEach(void (*func)(TView*, void *), void *args) { TView *term = last; TView *temp = last; if (temp == 0) return; TView *next = temp->next; do { temp = next; next = temp->next; func(temp, args); } while(temp != term); }

void TGroup::freeBuffer ( )

Frees the group's draw buffer (if one exists) by calling delete buffer and setting buffer to 0.

void TGroup::getBuffer ( )

If the group is sfExposed and ofBuffered, a draw buffer is created. The buffer size will be (size.x * size.y) and the buffer data member is set to point at the new buffer. See also: TView::options , TView::state

void TGroup::getData ( void * rec ) [virtual]

Overrides TView::getData(). Calls getData() for each subview in reverse order, incrementing the location given by `rec' by the dataSize() of each subview. See also: TGroup::dataSize , TGroup::setData Reimplemented from TView. Reimplemented in TColorDialog, TFileDialog, and TChDirDialog.

ushort TGroup::getHelpCtx ( ) [virtual]

Returns the help context of the current focused view by calling the selected subviews' TView::getHelpCtx() member function. If no help context is specified by any subview, getHelpCtx() returns the value of its own helpCtx member, by calling TView::getHelpCtx(). Reimplemented from TView.

void TGroup::handleEvent ( TEvent & event ) [virtual]

Overrides TView::handleEvent(). A group basically handles events by passing them to the handleEvent() member functions of one or more of its subviews. The actual routing, however, depends on the event class. For focused events (by default, evKeyDown and evCommand), event handling is done in three phases (see phase for more): The group's phase member is set to phPreProcess and the event is passed to the handleEvent() of all subviews that have the ofPreProcess flag set in options. Phase is set to phFocused and the event is passed to the handleEvent() of the currently selected view. Phase is set to phPostProcess and the event is passed to the handleEvent() of all subviews that have the ofPostProcess flag set in options. For positional events (by default, evMouse), the event is passed to the handleEvent() of the first subview whose bounding rectangle contains the point given by `event.where'. For broadcast events (events that aren't focused or positional), the event is passed to the handleEvent() of each subview in the group in Z-order. If a subview's eventMask member masks out an event class, TGroup::handleEvent() will never send events of that class to the subview. For example, the TView::eventMask disables evMouseUp, evMouseMove, and evMouseAuto, so TGroup::handleEvent() will never send such events to a standard TView. Reimplemented from TView. Reimplemented in TDeskTop, TProgram, TColorDialog, TDialog, TEditWindow, TFileDialog, TChDirDialog, and TWindow.

short TGroup::indexOf ( TView * p )

Returns the Z-order position (index) of the subview `p'.

void TGroup::insert ( TView * p )

Inserts the view given by `p' in the group's subview list. The new subview is placed on top of all other subviews. If the subview has the ofCenterX and/or ofCenterY flags set, it is centered accordingly in the group. See also: TView::options If the view has the sfVisible flag set, it will be shown in the group. Otherwise it remains invisible until specifically shown. If the view has the ofSelectable flag set, it becomes the currently selected subview. See also: TView::state

void TGroup::insertBefore ( TView * p, TView * Target )

Inserts the view given by `p' in front of the view given by `Target'. If `Target' is 0, the view is placed behind all other subviews in the group.

void TGroup::insertView ( TView * p, TView * Target )

Undocumented.

void TGroup::lock ( )

Locks the group, delaying any screen writes by subviews until the group is unlocked. lock() has no effect unless the group has a cache buffer (see ofBuffered flag and buffer data member). lock() works by incrementing the data member lockFlag. This semaphore is likewise decremented by unlock(). See also: TView::options When a call to unlock() decrements the count to zero, the entire group is written to the screen using the image constructed in the cache buffer. By "sandwiching" draw-intensive operations between calls to lock() and unlock(), unpleasant "screen flicker" can be reduced, if not eliminated. lock() and unlock() calls must be balanced; otherwise, a group may end up in a permanently locked state, causing it to not redraw itself properly when so requested.

Boolean TGroup::matches ( TView * p )

Returns True if the state and options settings of the view `p' are identical to those of the calling view.

void * TGroup::read ( ipstream & is ) [protected, virtual]

Reads from the input stream `is'. Reimplemented from TView. Reimplemented in TColorDialog, TEditWindow, TFileDialog, TChDirDialog, and TWindow.

void TGroup::redraw ( )

Redraws the group's subviews in Z-order. TGroup::redraw() differs from TGroup::draw() in that redraw() will never draw from the cache buffer.

void TGroup::remove ( TView * p )

Removes the subview `p' from the group and redraws the other subviews as required. p's owner and next members are set to 0.

void TGroup::removeView ( TView * p )

Removes the subview `p' from this group. Used internally by remove().

void TGroup::resetCurrent ( )

Selects (makes current) the first subview in the chain that is sfVisible and ofSelectable. resetCurrent() works by calling setCurrent(firstMatch(sfVisible, ofSelectable), normalSelect). See also: TGroup::firstMatch , TGroup::setCurrent , TView::options , TView::state The following enum type is useful for select mode arguments: enum selectMode { normalSelect, enterSelect, leaveSelect };

void TGroup::resetCursor ( ) [virtual]

Undocumented. Reimplemented from TView.

void TGroup::selectNext ( Boolean forwards )

If `forwards' is True, selectNext() selects (makes current) the next selectable subview (one with its ofSelectable bit set) in the group's Z-order. If `forwards' is False, the member function selects the previous selectable subview.

void TGroup::setCurrent ( TView * p, selectMode mode )

Parameter `selectMode' is an enumeration defined in TGroup as follows: enum selectMode {normalSelect, enterSelect, leaveSelect}; If `p' is the current subview, setCurrent() does nothing. Otherwise, `p' is made current (that is, selected) by a call to setState(). See also: resetCurrent

void TGroup::setData ( void * rec ) [virtual]

Overrides TView::setData(). Calls setData() for each subview in reverse Z-order, incrementing the location given by `rec' by the dataSize() of each subview. See also: TGroup::dataSize , TGroup::getData Reimplemented from TView. Reimplemented in TColorDialog, TFileDialog, and TChDirDialog.

void TGroup::setState ( ushort aState, Boolean enable ) [virtual]

Overrides TView::setState(). First calls the inherited TView::setState(), then updates the subviews as follows (see state for more): If `aState' is sfActive or sfDragging, then each subview's setState() is called to update the subview correspondingly. If `aState' is sfFocused, then the currently selected subview is called to focus itself correspondingly. If `aState' is sfExposed, TGroup::doExpose() is called for each subview. Finally, if `enable' is False, freeBuffer() is called. Reimplemented from TView. Reimplemented in TWindow.

void TGroup::shutDown ( ) [virtual]

Used internally by TObject::destroy() to ensure correct destruction of derived and related objects. shutDown() is overridden in many classes to ensure the proper setting of related data members when destroy is called. Reimplemented from TView. Reimplemented in TDeskTop, TProgram, TFileDialog, TChDirDialog, and TWindow.

void TGroup::unlock ( )

Unlocks the group by decrementing lockFlag. If lockFlag becomes zero, then the entire group is written to the screen using the image constructed in the cache buffer. See also: TGroup::lock

Boolean TGroup::valid ( ushort command ) [virtual]

Overrides TView::valid(). Returns True if all the subview's valid() calls return True. TGroup::valid() is used at the end of the event-handling loop in execute() to confirm that termination is allowed. A modal state cannot terminate until all valid() calls return True. A subview can return False if it wants to retain control. Reimplemented from TView. Reimplemented in TDialog, TFileDialog, and TChDirDialog.

void TGroup::write ( opstream & os ) [protected, virtual]

Writes to the output stream `os'. Reimplemented from TView. Reimplemented in TColorDialog, TEditWindow, TFileDialog, TChDirDialog, and TWindow.

---

Member Data Documentation

ushort * TGroup::buffer

Points to a buffer used to cache redraw operations, or is 0 if the group has no cache buffer. Cache buffers are created and destroyed automatically, unless the ofBuffered flag is cleared in the group's options member. Definition at line 3279 of file views.h.

TRect TGroup::clip

Holds the clip extent of the group, as returned by TView::getExtent() or TView::getClipRect(). The clip extent is defined as the minimum area that needs redrawing when draw() is called. Definition at line 3257 of file views.h.

TView * TGroup::current

Points to the subview that is currently selected, or is 0 if no subview is selected. Definition at line 3042 of file views.h.

ushort TGroup::endState

Holds the state of the group after a call to endModal(). Definition at line 3295 of file views.h.

TView * TGroup::last

Points to the last subview in the group (the one furthest from the top in Z-order). Definition at line 3250 of file views.h.

uchar TGroup::lockFlag

Acts as a semaphore to control buffered group draw operations. lockFlag keeps a count of the number of locks set during a set of nested draw calls. lock() and unlock() increment and decrement this value. When it reaches zero, the whole group will draw itself from its buffer. Intensive TGroup::draw() operations should be sandwiched between calls to lock() and unlock() to prevent excessive CPU load. Definition at line 3291 of file views.h.

const char *const TGroup::name [static]

Undocumented. Reimplemented from TView. Reimplemented in TDeskTop, TColorDialog, TDialog, TEditWindow, TFileDialog, TChDirDialog, and TWindow. Definition at line 3338 of file views.h.

phaseType TGroup::phase

The current phase of processing for a focused event. Subviews that have the ofPreProcess or ofPostProcess flags set can examine owner->phase to determine whether a call to their TView::handleEvent() is happening in the phPreProcess, phFocused, or phPostProcess phase. See also: TView::options phaseType is an enumeration defined as follows in TView: enum phaseType {phFocussed, phPreProcess, phPostProcess}; Definition at line 3272 of file views.h.

---

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

• views.h

---