OOFILE  1.9
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
dbAbstractEditHelper Class Referenceabstract

dbHelper for managing an editing form that changes a record. More...

#include <oofgui.h>

Inheritance diagram for dbAbstractEditHelper:
Inheritance graph
[legend]
Collaboration diagram for dbAbstractEditHelper:
Collaboration graph
[legend]

Public Member Functions

void addReceiver (oofReceiver *)
 Append receiver to end of list. More...
 
void adoptLink (dbFieldLink *adoptedLink)
 
bool askAllReturningAny (bool returnAny, OOFmsgT msg, unsigned long senderDefined=0, const oofReceiver *skipping=0)
 
oofReceiveraskAllStoppingAtFirst (bool stopOn, OOFmsgT msg, unsigned long senderDefined=0, const oofReceiver *skipping=0)
 
void broadcast (OOFmsgT msg, unsigned long senderDefined=0, const oofReceiver *skipping=0)
 Broadcast a message to all anonymous subscribers. More...
 
void copyFieldsToLinks ()
 
void copyLinksToFields ()
 
virtual void * currentGUItarget () const =0
 
 dbAbstractEditHelper (dbTable *)
 
dbFieldLinkgetLink (void *)
 
bool isBroadcasting () const
 
bool isDirty ()
 Check if helper is dirty, implied by mMainTable being dirty. More...
 
bool isReadOnly () const
 
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. More...
 
virtual void maybeChangeTargetLink (dbFieldLink *)
 React to possibly leaving a field, calling validation and update methods. More...
 
virtual void maybeDirty (dbFieldLink *)
 
void msgChangedCurrentField (OOFmsgT)
 
OOFmsgT msgChangedCurrentField ()
 
void readOnly (bool isReadOnly=true)
 
virtual bool receiveMsg (OOFmsgT msg, unsigned long senderDefined)
 The default receiveMsg behaviour is to delete yourself when the broadcaster closes. More...
 
void removeReceiver (const oofReceiver *)
 
void resumeListening ()
 
virtual void subscribeTo (oofBroadcaster *)
 
void suspendListening ()
 
virtual dbTabletable () const
 
virtual void unsubscribe (oofBroadcaster *from=0)
 
virtual void updateDerivedFieldDisplays ()
 
virtual ~dbAbstractEditHelper ()
 
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 ()
 

Static Public Member Functions

static void warnUser (std::ostream &os)
 

Protected Member Functions

void BroadcastShutdown ()
 
virtual bool LeaveRecord ()
 Leave record, asking user to OK changes if necessary. More...
 
virtual void LoadData ()
 
void ResetDirtyLinks ()
 
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. More...
 
bool ValidateLinks ()
 Check all links to see if they are validToLeaveForm, stopping at first failure. More...
 
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. More...
 
virtual void ChangedCurrentField ()
 

Protected Attributes

bool mAutoSaveOnMoving
 
bool mChangingPages
 
dbFieldLinkmCurrentLink
 
OOF_Dictionary mLinks
 
oofBroadcastermListensTo
 
bool mLostReceiversWhileBroadcasting
 simple flag that removeReceiver was called during nested broadcast More...
 
dbTablemMainTable
 
OOFmsgT mMsgCanSaveRecord
 
OOFmsgT mMsgChangedCurrentField
 
OOFmsgT mMsgConfirmSave
 
OOFmsgT mMsgEnteringAboutToLoad
 
OOFmsgT mMsgEnteringAfterLoad
 
unsigned long mNestedBroadcastingDepth
 aid to debugging and removeReceiver More...
 
bool mReadOnly
 
OOF_ExpandableLongArraymReceivers
 owned More...
 
unsigned short mSuspendCount
 
oofBroadcastermSuspendedListensTo
 

Detailed Description

dbHelper for managing an editing form that changes a record.

Abstracted cross-platform interface, subclassed for each framework.

Definition at line 395 of file oofgui.h.

Constructor & Destructor Documentation

dbAbstractEditHelper::dbAbstractEditHelper ( dbTable tbl)

Definition at line 391 of file oofgui.cpp.

dbAbstractEditHelper::~dbAbstractEditHelper ( )
virtual

Definition at line 407 of file oofgui.cpp.

References OOF_Dictionary::deleteAll(), and mLinks.

Member Function Documentation

void oofBroadcaster::addReceiver ( oofReceiver addingReceiver)
inherited

Append receiver to end of list.

Includes assertion to check if already in list.

Definition at line 181 of file oofmsg.cpp.

References OOF_ExpandableLongArray::append(), OOF_ExpandableLongArray::find(), and oofBroadcaster::mReceivers.

Referenced by oofSingleListener::oofSingleListener(), oofReceiver::subscribeTo(), and oofSingleListener::subscribeTo().

void dbAbstractEditHelper::adoptLink ( dbFieldLink adoptedLink)

Definition at line 416 of file oofgui.cpp.

References OOF_Dictionary::append(), mLinks, and dbFieldLink::owner().

Referenced by linkAdapter(), and linkPickAdapter().

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
msgconstant value indicating the action or event that has occurred.
senderDefinedadditional param for caller to pass through
skippinga 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.

Definition at line 82 of file oofmsg.cpp.

References OOF_ExpandableLongArray::count(), OOF_ExpandableLongArray::deleteAllMatching(), oofBroadcaster::mLostReceiversWhileBroadcasting, oofBroadcaster::mNestedBroadcastingDepth, oofBroadcaster::mReceivers, oofReceiver::receiveMsg(), and OOF_ExpandableLongArray::value().

Referenced by dbTable::addOIDtoSelection(), dbTable::appendSelection(), oofBroadcaster::BroadcastShutdown(), dbTable::clearSelection(), oofGraphSettingsCompleter::completePromises(), oofRepTextStyleCompleter::completePromises(), dbTable::deleteRecord(), dbTable::difference_with(), dbTable::dropRecordFromSelection(), dbTable::insert(), dbTable::intersection_with(), dbTable::invert(), dbGUI::leaveRecord(), LoadData(), dbTable::loadRelatedContextJoiningFromTo(), dbGUI::newRecord(), dbRelRefBase::relateFromRecord(), dbRelRefBase::relateRecord(), dbTable::removeSelection(), dbTable::resumeSorting(), dbGUI::revertRecord(), dbTable::revertRecord(), dbGUI::saveRecord(), dbTable::saveRecord(), dbTable::search(), dbTable::searchSelection(), dbRelRefBase::selectAllRelated(), dbTable::selectJustOID(), dbTable::setSelection(), dbTable::suspendSorting(), dbTable::union_with(), dbTable::union_with_no_overlap(), and dbTable::unloadRecord().

void oofBroadcaster::BroadcastShutdown ( )
protectedinherited
bool dbAbstractEditHelper::CanSaveRecord ( )
protectedvirtual

Definition at line 519 of file oofgui.cpp.

References mMsgCanSaveRecord, OOFmsg_None, SendImmediateFrameworkMessage(), and ValidateLinks().

Referenced by LeaveRecord(), and receiveMsg().

void dbAbstractEditHelper::ChangedCurrentField ( )
protectedvirtual

Definition at line 531 of file oofgui.cpp.

References mMsgChangedCurrentField, OOFmsg_None, and SendFrameworkMessage().

Referenced by maybeChangeTargetLink().

YNCancelT dbAbstractEditHelper::ConfirmSave ( )
protectedvirtual

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.

Definition at line 477 of file oofgui.cpp.

References Cancel, IDCANCEL, IDNO, IDYES, mMsgConfirmSave, oofYNC::msgBox(), No, OOFmsg_None, SendImmediateFrameworkMessage(), and Yes.

Referenced by LeaveRecord().

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

Definition at line 703 of file oofgui.cpp.

References dbFieldLink::copyLinkToField(), OOF_Dictionary::count(), and mLinks.

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

Implemented in dbEditHelper.

Referenced by maybeChangeTargetLink().

void dbAbstractEditHelper::EnteringAboutToLoad ( )
protectedvirtual

Definition at line 502 of file oofgui.cpp.

References mMsgEnteringAboutToLoad, OOFmsg_None, and SendFrameworkMessage().

Referenced by LoadData().

void dbAbstractEditHelper::EnteringAfterLoad ( )
protectedvirtual

Definition at line 510 of file oofgui.cpp.

References mMsgEnteringAfterLoad, OOFmsg_None, and SendFrameworkMessage().

Referenced by LoadData().

dbFieldLink * dbAbstractEditHelper::getLink ( void *  targetPane)
bool oofBroadcaster::isBroadcasting ( ) const
inlineinherited

Definition at line 160 of file oofmsg.h.

References oofBroadcaster::mNestedBroadcastingDepth.

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

Definition at line 763 of file oofgui.cpp.

References dbTable::isDirty(), and mMainTable.

Referenced by LeaveRecord().

bool dbAbstractEditHelper::isReadOnly ( ) const
inline

Definition at line 615 of file oofgui.h.

References mReadOnly.

bool dbAbstractEditHelper::LeaveRecord ( )
protectedvirtual

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.

Definition at line 615 of file oofgui.cpp.

References dbTable::autoOnContextChange, Cancel, CanSaveRecord(), ConfirmSave(), isDirty(), dbFieldLink::leaveLink(), mAutoSaveOnMoving, mCurrentLink, mMainTable, No, dbTable::tableSaveOption(), and dbTable::unloadRecord().

Referenced by receiveMsg().

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

Definition at line 692 of file oofgui.h.

Referenced by dbEditHelper::linkField().

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

Definition at line 787 of file oofgui.cpp.

References adoptLink(), boolField, dateField, dateTimeField, and dbField::fieldType().

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

Definition at line 699 of file oofgui.h.

Referenced by dbEditHelper::linkPickField().

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
pickViaused 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

Definition at line 829 of file oofgui.cpp.

References adoptLink(), dbTable::baseTableOfRelationChain(), dbField::fieldIsStandalone(), dbField::fieldTable(), dbRelRefBase::inverse(), dbRelRefBase::isManyToOne(), dbRelRefBase::isOneToOne(), and dbRelRefBase::isRelBackToParent().

void dbAbstractEditHelper::LoadData ( )
protectedvirtual
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.

Definition at line 548 of file oofgui.cpp.

References ChangedCurrentField(), currentGUItarget(), getLink(), dbFieldLink::leaveLink(), mCurrentLink, and updateDerivedFieldDisplays().

void dbAbstractEditHelper::maybeDirty ( dbFieldLink inLink)
virtual

Reimplemented from dbHelper.

Definition at line 572 of file oofgui.cpp.

References mCurrentLink.

void dbAbstractEditHelper::msgCanSaveRecord ( OOFmsgT  inMsg)
inline

Definition at line 650 of file oofgui.h.

References mMsgCanSaveRecord.

OOFmsgT dbAbstractEditHelper::msgCanSaveRecord ( )
inline

Definition at line 657 of file oofgui.h.

References mMsgCanSaveRecord.

void dbAbstractEditHelper::msgChangedCurrentField ( OOFmsgT  inMsg)
inline

Definition at line 678 of file oofgui.h.

References mMsgChangedCurrentField.

OOFmsgT dbAbstractEditHelper::msgChangedCurrentField ( )
inline

Definition at line 685 of file oofgui.h.

References mMsgChangedCurrentField.

void dbAbstractEditHelper::msgConfirmSave ( OOFmsgT  inMsg)
inline

Definition at line 664 of file oofgui.h.

References mMsgConfirmSave.

OOFmsgT dbAbstractEditHelper::msgConfirmSave ( )
inline

Definition at line 671 of file oofgui.h.

References mMsgConfirmSave.

void dbAbstractEditHelper::msgEnteringAboutToLoad ( OOFmsgT  inMsg)
inline

Definition at line 622 of file oofgui.h.

References mMsgEnteringAboutToLoad.

OOFmsgT dbAbstractEditHelper::msgEnteringAboutToLoad ( )
inline

Definition at line 629 of file oofgui.h.

References mMsgEnteringAboutToLoad.

void dbAbstractEditHelper::msgEnteringAfterLoad ( OOFmsgT  inMsg)
inline

Definition at line 636 of file oofgui.h.

References mMsgEnteringAfterLoad.

OOFmsgT dbAbstractEditHelper::msgEnteringAfterLoad ( )
inline

Definition at line 643 of file oofgui.h.

References mMsgEnteringAfterLoad.

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.

Definition at line 425 of file oofgui.cpp.

References CanSaveRecord(), kRecordLockedByOtherUser, dbFieldLink::leaveLink(), LeaveRecord(), LoadData(), mCurrentLink, mMainTable, OOFmsg_AttemptLeaveRecord, OOFmsg_AttemptSaveRecord, OOFmsg_ChangeSelection, OOFmsg_NewRecord, OOFmsg_RevertRecord, OOFmsg_SaveRecord, readOnly(), dbTable::reloadRecord(), ResetDirtyLinks(), and dbTable::unloadRecord().

void oofBroadcaster::removeReceiver ( const oofReceiver rcvrPtr)
inherited
void dbAbstractEditHelper::ResetDirtyLinks ( )
protected

Definition at line 687 of file oofgui.cpp.

References OOF_Dictionary::count(), dbFieldLink::markClean(), and mLinks.

Referenced by receiveMsg().

void oofSingleListener::resumeListening ( )
inherited
virtual bool dbAbstractEditHelper::SendFrameworkMessage ( OOFmsgT  ,
void *  ioParam = 0 
)
protectedpure virtual
bool dbAbstractEditHelper::SendImmediateFrameworkMessage ( OOFmsgT  inMsg,
void *  ioParam = 0 
)
protectedvirtual

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

Definition at line 778 of file oofgui.cpp.

References SendFrameworkMessage().

Referenced by CanSaveRecord(), and ConfirmSave().

void oofSingleListener::subscribeTo ( oofBroadcaster broad)
virtualinherited
void oofSingleListener::suspendListening ( )
inherited
dbTable * dbAbstractEditHelper::table ( ) const
virtual

Reimplemented from dbHelper.

Definition at line 586 of file oofgui.cpp.

References mMainTable.

Referenced by updateDerivedFieldDisplays().

void oofSingleListener::unsubscribe ( oofBroadcaster from = 0)
virtualinherited
void dbAbstractEditHelper::updateDerivedFieldDisplays ( )
virtual
bool dbAbstractEditHelper::ValidateLinks ( )
protected

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

Definition at line 717 of file oofgui.cpp.

References OOF_Dictionary::count(), dbFieldLink::highlightLink(), mLinks, and dbFieldLink::validToLeaveForm().

Referenced by CanSaveRecord().

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

Definition at line 657 of file oofgui.cpp.

References MB_ICONEXCLAMATION, and dbConnect::raise().

Member Data Documentation

bool dbAbstractEditHelper::mAutoSaveOnMoving
protected

Definition at line 471 of file oofgui.h.

Referenced by LeaveRecord().

bool dbAbstractEditHelper::mChangingPages
protected

Definition at line 471 of file oofgui.h.

dbFieldLink* dbAbstractEditHelper::mCurrentLink
protected

Definition at line 480 of file oofgui.h.

Referenced by LeaveRecord(), maybeChangeTargetLink(), maybeDirty(), and receiveMsg().

OOF_Dictionary dbAbstractEditHelper::mLinks
protected
oofBroadcaster* oofSingleListener::mListensTo
protectedinherited
bool oofBroadcaster::mLostReceiversWhileBroadcasting
protectedinherited

simple flag that removeReceiver was called during nested broadcast

Definition at line 98 of file oofmsg.h.

Referenced by oofBroadcaster::broadcast(), and oofBroadcaster::removeReceiver().

dbTable* dbAbstractEditHelper::mMainTable
protected

Definition at line 472 of file oofgui.h.

Referenced by isDirty(), LeaveRecord(), LoadData(), readOnly(), receiveMsg(), and table().

OOFmsgT dbAbstractEditHelper::mMsgCanSaveRecord
protected

Definition at line 485 of file oofgui.h.

Referenced by CanSaveRecord(), and msgCanSaveRecord().

OOFmsgT dbAbstractEditHelper::mMsgChangedCurrentField
protected

Definition at line 487 of file oofgui.h.

Referenced by ChangedCurrentField(), and msgChangedCurrentField().

OOFmsgT dbAbstractEditHelper::mMsgConfirmSave
protected

Definition at line 486 of file oofgui.h.

Referenced by ConfirmSave(), and msgConfirmSave().

OOFmsgT dbAbstractEditHelper::mMsgEnteringAboutToLoad
protected

Definition at line 483 of file oofgui.h.

Referenced by EnteringAboutToLoad(), and msgEnteringAboutToLoad().

OOFmsgT dbAbstractEditHelper::mMsgEnteringAfterLoad
protected

Definition at line 484 of file oofgui.h.

Referenced by EnteringAfterLoad(), and msgEnteringAfterLoad().

unsigned long oofBroadcaster::mNestedBroadcastingDepth
protectedinherited

aid to debugging and removeReceiver

Definition at line 97 of file oofmsg.h.

Referenced by oofBroadcaster::broadcast(), oofBroadcaster::isBroadcasting(), and oofBroadcaster::removeReceiver().

bool dbAbstractEditHelper::mReadOnly
protected

Definition at line 479 of file oofgui.h.

Referenced by isReadOnly(), and readOnly().

OOF_ExpandableLongArray* oofBroadcaster::mReceivers
protectedinherited
unsigned short oofSingleListener::mSuspendCount
protectedinherited
oofBroadcaster* oofSingleListener::mSuspendedListensTo
protectedinherited

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