dbEditHelper Class Reference
[OOFILE GUI forms interface., Mac Specific]

#include <oofpp.h>

Inheritance diagram for dbEditHelper:

[legend]Collaboration diagram for dbEditHelper:

[legend]List of all members.

Detailed Description

dbHelper that manages edit controls accessing a main record.

May have related data to the main table being edited. There will be one of these per dialog editing a record except possibly if the only controls on the dialog are lists of records. This copy of the class implements PowerPlant linkField methods. dbEditHelper will be reimplemented for each GUI platform and has linkField classes for that GUI's different control types.

platform-specific links

void linkField (dbField &, const dbGUIAdapterFactoryPP &)

void linkField (dbField *, const dbGUIAdapterFactoryPP &)

void linkPickField (dbField &, const dbGUIAdapterFactoryPP &, dbRelRef *pickVia=0)

void linkPickField (dbField *, const dbGUIAdapterFactoryPP &, dbRelRef *pickVia=0)

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

dbEditHelper (dbTable *)

virtual void * currentGUItarget () 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.

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)

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

dbEditHelper::dbEditHelper ( dbTable * )

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 ) [inherited]

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, inherited]

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

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

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 ( ) [inherited]

void dbAbstractEditHelper::copyLinksToFields ( ) [inherited]

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

void * dbEditHelper::currentGUItarget ( ) const [virtual]

Implements dbAbstractEditHelper.

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

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

dbFieldLink * dbAbstractEditHelper::getLink ( void * ) [inherited]

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

bool dbAbstractEditHelper::isDirty ( ) [inherited]

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, inherited]

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

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

) [inherited]

void dbAbstractEditHelper::linkAdapter ( dbField & ,

dbGUIAdapter * adoptedAdapter,

bool becomeReadOnly = false

) [inline, inherited]

void dbEditHelper::linkField ( dbField * ,

const dbGUIAdapterFactoryPP &

) [inline]

void dbEditHelper::linkField ( dbField & ,

const dbGUIAdapterFactoryPP &

) [inline]

void dbAbstractEditHelper::linkPickAdapter ( dbField * fld,

dbGUIAdapter * adoptedAdapter,

bool becomeReadOnly = false,

dbRelRef * pickVia = 0

) [inherited]

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, inherited]

void dbEditHelper::linkPickField ( dbField * ,

const dbGUIAdapterFactoryPP & ,

dbRelRef * pickVia = 0

) [inline]

void dbEditHelper::linkPickField ( dbField & ,

const dbGUIAdapterFactoryPP & ,

dbRelRef * pickVia = 0

) [inline]

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

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

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, inherited]

Reimplemented from dbHelper.

OOFmsgT dbAbstractEditHelper::msgCanSaveRecord ( ) [inline, inherited]

void dbAbstractEditHelper::msgCanSaveRecord ( OOFmsgT ) [inline, inherited]

OOFmsgT dbAbstractEditHelper::msgChangedCurrentField ( ) [inline, inherited]

void dbAbstractEditHelper::msgChangedCurrentField ( OOFmsgT ) [inline, inherited]

OOFmsgT dbAbstractEditHelper::msgConfirmSave ( ) [inline, inherited]

void dbAbstractEditHelper::msgConfirmSave ( OOFmsgT ) [inline, inherited]

OOFmsgT dbAbstractEditHelper::msgEnteringAboutToLoad ( ) [inline, inherited]

void dbAbstractEditHelper::msgEnteringAboutToLoad ( OOFmsgT ) [inline, inherited]

OOFmsgT dbAbstractEditHelper::msgEnteringAfterLoad ( ) [inline, inherited]

void dbAbstractEditHelper::msgEnteringAfterLoad ( OOFmsgT ) [inline, inherited]

void dbAbstractEditHelper::readOnly ( bool isReadOnly = true ) [inherited]

bool dbAbstractEditHelper::receiveMsg ( OOFmsgT msg,

unsigned long senderDefined

) [virtual, inherited]

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, inherited]

void oofSingleListener::resumeListening ( ) [inherited]

bool dbEditHelper::SendFrameworkMessage ( OOFmsgT ,

void * ioParam = 0

) [protected, virtual]

Implements dbAbstractEditHelper.

bool dbAbstractEditHelper::SendImmediateFrameworkMessage ( OOFmsgT inMsg,

void * ioParam = 0

) [protected, virtual, inherited]

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, inherited]

Reimplemented from dbHelper.

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

Reimplemented from oofReceiver.

void dbAbstractEditHelper::updateDerivedFieldDisplays ( ) [virtual, inherited]

bool dbAbstractEditHelper::ValidateLinks ( ) [protected, inherited]

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

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

Member Data Documentation

bool dbAbstractEditHelper::mAutoSaveOnMoving [protected, inherited]

bool dbAbstractEditHelper::mChangingPages [protected, inherited]

dbFieldLink* dbAbstractEditHelper::mCurrentLink [protected, inherited]

OOF_Dictionary dbAbstractEditHelper::mLinks [protected, inherited]

oofBroadcaster* oofSingleListener::mListensTo [protected, inherited]

bool oofBroadcaster::mLostReceiversWhileBroadcasting [protected, inherited]

simple flag that removeReceiver was called during nested broadcast

dbTable* dbAbstractEditHelper::mMainTable [protected, inherited]

OOFmsgT dbAbstractEditHelper::mMsgCanSaveRecord [protected, inherited]

OOFmsgT dbAbstractEditHelper::mMsgChangedCurrentField [protected, inherited]

OOFmsgT dbAbstractEditHelper::mMsgConfirmSave [protected, inherited]

OOFmsgT dbAbstractEditHelper::mMsgEnteringAboutToLoad [protected, inherited]

OOFmsgT dbAbstractEditHelper::mMsgEnteringAfterLoad [protected, inherited]

unsigned long oofBroadcaster::mNestedBroadcastingDepth [protected, inherited]

aid to debugging and removeReceiver

bool dbAbstractEditHelper::mReadOnly [protected, inherited]

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 Thu Jan 1 21:35:52 2004 for OOFILE by

1.3.5


platform-specific links
void	linkField (dbField &, const dbGUIAdapterFactoryPP &)
void	linkField (dbField *, const dbGUIAdapterFactoryPP &)
void	linkPickField (dbField &, const dbGUIAdapterFactoryPP &, dbRelRef *pickVia=0)
void	linkPickField (dbField , const dbGUIAdapterFactoryPP &, dbRelRef pickVia=0)
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
	dbEditHelper (dbTable *)
virtual void *	currentGUItarget () 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.
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)
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

dbEditHelper Class Reference [OOFILE GUI forms interface., Mac Specific]

Detailed Description

platform-specific links

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

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

dbEditHelper Class Reference
[OOFILE GUI forms interface., Mac Specific]