Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members | Related Pages

dbAbstractEditHelper Class Reference
[OOFILE GUI forms interface.]

#include <oofgui.h>

Inheritance diagram for dbAbstractEditHelper:

Inheritance graph
[legend]
Collaboration diagram for dbAbstractEditHelper:

Collaboration graph
[legend]
List of all members.

Detailed Description

dbHelper for managing an editing form that changes a record.

Abstracted cross-platform interface, subclassed for each framework.


USER-HOOK messages as alternative to subclassing and overriding the hook methods

void msgEnteringAboutToLoad (OOFmsgT)
OOFmsgT msgEnteringAboutToLoad ()
void msgEnteringAfterLoad (OOFmsgT)
OOFmsgT msgEnteringAfterLoad ()
void msgCanSaveRecord (OOFmsgT)
OOFmsgT msgCanSaveRecord ()
void msgConfirmSave (OOFmsgT)
OOFmsgT msgConfirmSave ()

USER-HOOKS override the following virtual methods as documented in guihooks.htm

virtual void EnteringAboutToLoad ()
virtual void EnteringAfterLoad ()
virtual bool CanSaveRecord ()
virtual YNCancelT ConfirmSave ()
 Ask user to confirm if should save or not, allowing cancel.

virtual void ChangedCurrentField ()

Public Member Functions

 dbAbstractEditHelper (dbTable *)
virtual ~dbAbstractEditHelper ()
void linkAdapter (dbField &, dbGUIAdapter *adoptedAdapter, bool becomeReadOnly=false)
void linkAdapter (dbField *, dbGUIAdapter *adoptedAdapter, bool becomeReadOnly=false)
void linkPickAdapter (dbField &, dbGUIAdapter *adoptedAdapter, bool becomeReadOnly=false, dbRelRef *pickVia=0)
void linkPickAdapter (dbField *, dbGUIAdapter *adoptedAdapter, bool becomeReadOnly=false, dbRelRef *pickVia=0)
 Link an Adapter to control used to select from lookup table.

virtual void * currentGUItarget () const=0
virtual bool receiveMsg (OOFmsgT msg, unsigned long senderDefined)
 The default receiveMsg behaviour is to delete yourself when the broadcaster closes.

void adoptLink (dbFieldLink *adoptedLink)
dbFieldLink * getLink (void *)
virtual dbTable * table () const
bool isDirty ()
 Check if helper is dirty, implied by mMainTable being dirty.

void copyLinksToFields ()
void copyFieldsToLinks ()
virtual void maybeChangeTargetLink (dbFieldLink *)
 React to possibly leaving a field, calling validation and update methods.

virtual void maybeDirty (dbFieldLink *)
virtual void updateDerivedFieldDisplays ()
bool isReadOnly () const
void readOnly (bool isReadOnly=true)
void msgChangedCurrentField (OOFmsgT)
OOFmsgT msgChangedCurrentField ()
virtual void subscribeTo (oofBroadcaster *)
virtual void unsubscribe (oofBroadcaster *from=0)
void suspendListening ()
void resumeListening ()
void broadcast (OOFmsgT msg, unsigned long senderDefined=0, const oofReceiver *skipping=0)
 Broadcast a message to all anonymous subscribers.

oofReceiver * askAllStoppingAtFirst (bool stopOn, OOFmsgT msg, unsigned long senderDefined=0, const oofReceiver *skipping=0)
bool askAllReturningAny (bool returnAny, OOFmsgT msg, unsigned long senderDefined=0, const oofReceiver *skipping=0)
bool isBroadcasting () const
void addReceiver (oofReceiver *)
 Append receiver to end of list.

void removeReceiver (const oofReceiver *)

Static Public Member Functions

void warnUser (std::ostream &os)

Protected Member Functions

virtual bool SendFrameworkMessage (OOFmsgT, void *ioParam=0)=0
virtual bool SendImmediateFrameworkMessage (OOFmsgT, void *ioParam=0)
 Send a message so any listeners can approve an action.

virtual void LoadData ()
void ResetDirtyLinks ()
virtual bool LeaveRecord ()
 Leave record, asking user to OK changes if necessary.

bool ValidateLinks ()
 Check all links to see if they are validToLeaveForm, stopping at first failure.

void BroadcastShutdown ()

Protected Attributes

bool mChangingPages
bool mAutoSaveOnMoving
dbTable * mMainTable
OOF_Dictionary mLinks
bool mReadOnly
dbFieldLink * mCurrentLink
OOFmsgT mMsgEnteringAboutToLoad
OOFmsgT mMsgEnteringAfterLoad
OOFmsgT mMsgCanSaveRecord
OOFmsgT mMsgConfirmSave
OOFmsgT mMsgChangedCurrentField
oofBroadcaster * mListensTo
oofBroadcaster * mSuspendedListensTo
unsigned short mSuspendCount
OOF_ExpandableLongArray * mReceivers
 owned

unsigned long mNestedBroadcastingDepth
 aid to debugging and removeReceiver

bool mLostReceiversWhileBroadcasting
 simple flag that removeReceiver was called during nested broadcast

Constructor & Destructor Documentation

dbAbstractEditHelper::dbAbstractEditHelper (  dbTable *   ) 
 

dbAbstractEditHelper::~dbAbstractEditHelper (   )  [virtual]
 

Member Function Documentation

void oofBroadcaster::addReceiver (  oofReceiver *  addingReceiver  )  [inherited]
 

Append receiver to end of list.

Includes assertion to check if already in list.

void dbAbstractEditHelper::adoptLink (  dbFieldLink *  adoptedLink  ) 
 

bool oofBroadcaster::askAllReturningAny (  bool  returnAny,
OOFmsgT  msg,
unsigned long  senderDefined = 0,
const oofReceiver *  skipping = 0
)  [inherited]
 

oofReceiver * oofBroadcaster::askAllStoppingAtFirst (  bool  stopOn,
OOFmsgT  msg,
unsigned long  senderDefined = 0,
const oofReceiver *  skipping = 0
)  [inherited]
 

void oofBroadcaster::broadcast (  OOFmsgT  msg,
unsigned long  senderDefined = 0,
const oofReceiver *  skipping = 0
)  [inherited]
 

Broadcast a message to all anonymous subscribers.

Parameters:
msg constant value indicating the action or event that has occurred.
senderDefined additional param for caller to pass through
skipping a receiver to be skipped when broadcasting, to avoid circular messages
Todo:
use void* for senderDefined so can cope with values >32bits eg oidT in HUGE databases or 64bit pointers.

void oofBroadcaster::BroadcastShutdown (   )  [protected, inherited]
 

bool dbAbstractEditHelper::CanSaveRecord (   )  [protected, virtual]
 

void dbAbstractEditHelper::ChangedCurrentField (   )  [protected, virtual]
 

YNCancelT dbAbstractEditHelper::ConfirmSave (   )  [protected, virtual]
 

Ask user to confirm if should save or not, allowing cancel.

Can override by subclassing. msgConfirmSave(OOFmsgT) also lets you specify a message to be sent to application to allow confirmation - an easier way to hook in behaviour without subclassing.

Note:
you could totally disable this behaviour by having your reaction to mMsgConfirmSave be No, eg: if you were running in demo mode.
Returns:
triple value YNCancelT indicating user response.

void dbAbstractEditHelper::copyFieldsToLinks (   ) 
 

void dbAbstractEditHelper::copyLinksToFields (   ) 
 

Note:
not used by OOFILE any more but User may invoke for mass update
See also:
dbFieldLink::leaveLink - we copy back on field by field basis so database matches visuals, and calc fields work on the visible values

virtual void* dbAbstractEditHelper::currentGUItarget (   )  const [pure virtual]
 

Implemented in dbEditHelper.

void dbAbstractEditHelper::EnteringAboutToLoad (   )  [protected, virtual]
 

void dbAbstractEditHelper::EnteringAfterLoad (   )  [protected, virtual]
 

dbFieldLink * dbAbstractEditHelper::getLink (  void *   ) 
 

bool oofBroadcaster::isBroadcasting (   )  const [inline, inherited]
 

bool dbAbstractEditHelper::isDirty (   ) 
 

Check if helper is dirty, implied by mMainTable being dirty.

dbField dirty back-propagation ensures edits to related data dirty main table.

Returns:
true indicates dirty, will need to save

bool dbAbstractEditHelper::isReadOnly (   )  const [inline]
 

bool dbAbstractEditHelper::LeaveRecord (   )  [protected, virtual]
 

Leave record, asking user to OK changes if necessary.

If record needs saving and not in auto-save mode, calls ConfirmSave.

Returns:
true if were allowed to leave.

void dbAbstractEditHelper::linkAdapter (  dbField *  fld,
dbGUIAdapter *  adoptedAdapter,
bool  becomeReadOnly = false
) 
 

void dbAbstractEditHelper::linkAdapter (  dbField &  ,
dbGUIAdapter *  adoptedAdapter,
bool  becomeReadOnly = false
)  [inline]
 

void dbAbstractEditHelper::linkPickAdapter (  dbField *  fld,
dbGUIAdapter *  adoptedAdapter,
bool  becomeReadOnly = false,
dbRelRef *  pickVia = 0
) 
 

Link an Adapter to control used to select from lookup table.

Often popup menu but may be an edit control - we abstract that.

Parameters:
pickVia used to clarify which is lookup table, in complex multi-rel chain eg: Patients->Visits->Doctor->Staff->Name with pickVia == Patients->Visits->Doctor pickVia is the relationship going from left to right. It will usually point to the table containing the choice field, ie: fld->table()==pickVia->relatedTable().
Note:
a very important role of this method is in most cases work out the default pickVia
Warning:
an easy mistake is to specify just the relationship, NOT the field pointed to, eg: 
        mEditHelper->linkPickField (mOOFData->Prefs->DefaultAssignee, mAssignedToPopup);
    instead of
        mEditHelper->linkPickField (mOOFData->Prefs->DefaultAssignee->ShortDesc, mAssignedToPopup);
Todo:
allow for picking via date entry fields, like dbDateLink2Editor

void dbAbstractEditHelper::linkPickAdapter (  dbField &  ,
dbGUIAdapter *  adoptedAdapter,
bool  becomeReadOnly = false,
dbRelRef *  pickVia = 0
)  [inline]
 

void dbAbstractEditHelper::LoadData (   )  [protected, virtual]
 

void dbAbstractEditHelper::maybeChangeTargetLink (  dbFieldLink *  newLink  )  [virtual]
 

React to possibly leaving a field, calling validation and update methods.

Calls updateDerivedFieldDisplays so calculated fields can react to changes.

Note:
some GUI toolkits rely on direct dependencies to provide this kind of updating, which has huge performance implications with cascading broadcasts (like Swing). By centralising the update here we have the chance to control GUI behaviour and react optimally.
Todo:
make field display updates optional

Reimplemented from dbHelper.

void dbAbstractEditHelper::maybeDirty (  dbFieldLink *   )  [virtual]
 

Reimplemented from dbHelper.

OOFmsgT dbAbstractEditHelper::msgCanSaveRecord (   )  [inline]
 

void dbAbstractEditHelper::msgCanSaveRecord (  OOFmsgT   )  [inline]
 

OOFmsgT dbAbstractEditHelper::msgChangedCurrentField (   )  [inline]
 

void dbAbstractEditHelper::msgChangedCurrentField (  OOFmsgT   )  [inline]
 

OOFmsgT dbAbstractEditHelper::msgConfirmSave (   )  [inline]
 

void dbAbstractEditHelper::msgConfirmSave (  OOFmsgT   )  [inline]
 

OOFmsgT dbAbstractEditHelper::msgEnteringAboutToLoad (   )  [inline]
 

void dbAbstractEditHelper::msgEnteringAboutToLoad (  OOFmsgT   )  [inline]
 

OOFmsgT dbAbstractEditHelper::msgEnteringAfterLoad (   )  [inline]
 

void dbAbstractEditHelper::msgEnteringAfterLoad (  OOFmsgT   )  [inline]
 

void dbAbstractEditHelper::readOnly (  bool  isReadOnly = true  ) 
 

bool dbAbstractEditHelper::receiveMsg (  OOFmsgT  msg,
unsigned long  senderDefined
)  [virtual]
 

The default receiveMsg behaviour is to delete yourself when the broadcaster closes.

In many user subclasses oofSingleListener is a mixin and you have a class owned elsewhere, not self-deleting.

Warning:
If a subclass is not self-deleting it MUST override receiveMsg handling of the msg OOFmsg_BroadcasterClosing to prevent runtime error.
However it is still important to set mListensTo=0 otherwise when you finally get around to deleting your oofSingleListener, it will try to update a deleted oofBroadcaster and cause a crash.

Reimplemented from oofSingleListener.

void oofBroadcaster::removeReceiver (  const oofReceiver *   )  [inherited]
 

void dbAbstractEditHelper::ResetDirtyLinks (   )  [protected]
 

void oofSingleListener::resumeListening (   )  [inherited]
 

virtual bool dbAbstractEditHelper::SendFrameworkMessage (  OOFmsgT  ,
void *  ioParam = 0
)  [protected, pure virtual]
 

Implemented in dbEditHelper.

bool dbAbstractEditHelper::SendImmediateFrameworkMessage (  OOFmsgT  inMsg,
void *  ioParam = 0
)  [protected, virtual]
 

Send a message so any listeners can approve an action.

Must be implemented by synchronous message posting, not delayed queue as is used to provide user hooks to influence editing behaviour.

See also:
dbAbstractEditHelper::CanSaveRecord
Returns:
true if action approved

void oofSingleListener::subscribeTo (  oofBroadcaster *   )  [virtual, inherited]
 

Reimplemented from oofReceiver.

void oofSingleListener::suspendListening (   )  [inherited]
 

dbTable * dbAbstractEditHelper::table (   )  const [virtual]
 

Reimplemented from dbHelper.

void oofSingleListener::unsubscribe (  oofBroadcaster *  from = 0  )  [virtual, inherited]
 

Reimplemented from oofReceiver.

void dbAbstractEditHelper::updateDerivedFieldDisplays (   )  [virtual]
 

bool dbAbstractEditHelper::ValidateLinks (   )  [protected]
 

Check all links to see if they are validToLeaveForm, stopping at first failure.

void dbAbstractEditHelper::warnUser (  std::ostream &  os  )  [static]
 

Member Data Documentation

bool dbAbstractEditHelper::mAutoSaveOnMoving [protected]
 

bool dbAbstractEditHelper::mChangingPages [protected]
 

dbFieldLink* dbAbstractEditHelper::mCurrentLink [protected]
 

OOF_Dictionary dbAbstractEditHelper::mLinks [protected]
 

oofBroadcaster* oofSingleListener::mListensTo [protected, inherited]
 

bool oofBroadcaster::mLostReceiversWhileBroadcasting [protected, inherited]
 

simple flag that removeReceiver was called during nested broadcast

dbTable* dbAbstractEditHelper::mMainTable [protected]
 

OOFmsgT dbAbstractEditHelper::mMsgCanSaveRecord [protected]
 

OOFmsgT dbAbstractEditHelper::mMsgChangedCurrentField [protected]
 

OOFmsgT dbAbstractEditHelper::mMsgConfirmSave [protected]
 

OOFmsgT dbAbstractEditHelper::mMsgEnteringAboutToLoad [protected]
 

OOFmsgT dbAbstractEditHelper::mMsgEnteringAfterLoad [protected]
 

unsigned long oofBroadcaster::mNestedBroadcastingDepth [protected, inherited]
 

aid to debugging and removeReceiver

bool dbAbstractEditHelper::mReadOnly [protected]
 

OOF_ExpandableLongArray* oofBroadcaster::mReceivers [protected, inherited]
 

owned

unsigned short oofSingleListener::mSuspendCount [protected, inherited]
 

oofBroadcaster* oofSingleListener::mSuspendedListensTo [protected, inherited]
 

The documentation for this class was generated from the following files:
Generated on Fri Jan 2 00:45:35 2004 for OOFILE by doxygen 1.3.5