#include <views.h>
Inheritance diagram for TGroup::
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) |
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.
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.
|
|
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. |
|
|
Hides the group using hide(), then disposes of each subview in the group using delete. Finally, the buffer is freed (if one). |
|
|
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. |
|
|
Returns a pointer to the subview at `index' position in Z-order. |
|
|
Calls the TView::awaken() methods of each of the group's subviews in Z-order. Reimplemented from TView. |
|
|
Called to create an object in certain stream-reading situations. Reimplemented from TView. Reimplemented in TDeskTop, TColorDialog, TDialog, TEditWindow, TFileDialog, TChDirDialog, and TWindow. |
|
|
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. |
|
|
Overrides TView::dataSize(). Returns total size of group by calling and accumulating dataSize() for each subview.
Reimplemented from TView. Reimplemented in TColorDialog, and TChDirDialog. |
|
|
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. |
|
|
Calls TView::drawView() for each subview starting at `p', until the subview `bottom' is reached. |
|
|
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. |
|
|
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.
|
|
|
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().
If `p' is 0 upon a call to execView(), a value of cmCancel is returned. |
|
|
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. |
|
|
Returns a pointer to the first subview (the one closest to the top in Z-order), or 0 if the group has no subviews. |
|
|
Returns a pointer to the first subview that matches its state with `aState' and its options with `aOptions'. |
|
|
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; } |
|
|
Undocumented. |
|
|
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); } |
|
|
Frees the group's draw buffer (if one exists) by calling delete buffer and setting buffer to 0. |
|
|
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.
|
|
|
Overrides TView::getData(). Calls getData() for each subview in reverse order, incrementing the location given by `rec' by the dataSize() of each subview.
Reimplemented from TView. Reimplemented in TColorDialog, TFileDialog, and TChDirDialog. |
|
|
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. |
|
|
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):
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. |
|
|
Returns the Z-order position (index) of the subview `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.
|
|
|
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. |
|
|
Undocumented. |
|
|
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().
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. |
|
|
Returns True if the state and options settings of the view `p' are identical to those of the calling view. |
|
|
Reads from the input stream `is'. Reimplemented from TView. Reimplemented in TColorDialog, TEditWindow, TFileDialog, TChDirDialog, and TWindow. |
|
|
Redraws the group's subviews in Z-order. TGroup::redraw() differs from TGroup::draw() in that redraw() will never draw from the cache buffer. |
|
|
Removes the subview `p' from the group and redraws the other subviews as required. p's owner and next members are set to 0. |
|
|
Removes the subview `p' from this group. Used internally by remove(). |
|
|
Selects (makes current) the first subview in the chain that is sfVisible and ofSelectable. resetCurrent() works by calling setCurrent(firstMatch(sfVisible, ofSelectable), normalSelect).
enum selectMode { normalSelect, enterSelect, leaveSelect };
|
|
|
Undocumented. Reimplemented from TView. |
|
|
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. |
|
|
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().
|
|
|
Overrides TView::setData(). Calls setData() for each subview in reverse Z-order, incrementing the location given by `rec' by the dataSize() of each subview.
Reimplemented from TView. Reimplemented in TColorDialog, TFileDialog, and TChDirDialog. |
|
|
Overrides TView::setState(). First calls the inherited TView::setState(), then updates the subviews as follows (see state for more):
Reimplemented from TView. Reimplemented in TWindow. |
|
|
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. |
|
|
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.
|
|
|
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. |
|
|
Writes to the output stream `os'. Reimplemented from TView. Reimplemented in TColorDialog, TEditWindow, TFileDialog, TChDirDialog, and TWindow. |
|
|
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. |
|
|
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. |
|
|
Points to the subview that is currently selected, or is 0 if no subview is selected. |
|
|
Holds the state of the group after a call to endModal(). |
|
|
Points to the last subview in the group (the one furthest from the top in Z-order). |
|
|
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. |
|
|
Undocumented. Reimplemented from TView. Reimplemented in TDeskTop, TColorDialog, TDialog, TEditWindow, TFileDialog, TChDirDialog, and TWindow. |
|
|
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.
enum phaseType {phFocussed, phPreProcess, phPostProcess};
|
1.2.8.1 written by Dimitri van Heesch,
© 1997-2001