Share via

CWnd::OnDSCNotify

  • Article

afx_msgBOOL OnDSCNotify( DSCSTATEnState**,DSCREASONnReason,BOOLpBool);**

Return Value

Returns TRUE if the operation represented by nReason and nState was handled. Otherwise, returns FALSE.

Parameters

nState

One of the named constants found in the DSCSTATE enumerator, which are listed under Remarks.

nReason

One of the named constants found in the DSCREASON enumerator, which are listed under Remarks.

pBool

A Boolean answer indicating whether the operation represented by nState and nReason should continue.

Remarks

This sink notification is called in response to an event that a data-source control fires when a control to which the data-source control is bound modifies or attempts to modify the underlying cursor. Use it to trap reasons (nReason) and states (nState) generated by a data-source control. All combinations of states and reasons are allowed by default. Write your code to test the states and reasons that are important to your application and return TRUE or FALSE as appropriate.

To use OnDSCNotify, declare a sink map and a handler for the sink notification in the header of the class that wishes to receive the sink notification as follows:

class CMyDlg : public CDialog
{
   ...
   DECLARE_EVENTSINK_MAP()
   BOOL OnDSCNotify(DSCSTATE nState,
             DSCREASON nReason, BOOL* pBool);
   ...
};

Then, in the implementation of your class, define the sink map and specify the function to receive the events as follows:

BEGIN_EVENTSINK_MAP(CMyDlg, CDialog)
   ON_DSCNOTIFY(CMyDlg, IDC_RDCCTRL1, OnDSCNotify)
END_EVENTSINK_MAP()

The notification callback function, your implementation of OnDSCNotify, will be called when the following events occur inside the data-source control:

enum DSCREASON
{
   dscNoReason = 0,
   dscClose, dscCommit, dscDelete,
   dscEdit, dscInsert, dscModify, dscMove
};

It will also be called multiple times for each of the following states:

enum DSCSTATE
{
   dscNoState = 0,
   dscOKToDo,
   dscCancelled,
   dscSyncBefore,
   dscAboutToDo,
   dscFailedToDo,
   dscSyncAfter,
   dscDidEvent
};

The multiple calls allow you to trap an event at different times. For example, since events are usually generated in response to modification of the cursor state by a control, the first thing that the data-source control will do is to fire events asking if it is okay to actually perform that action; hence the reason for the dscOKToDo state. If all clients that monitor the event (the data control, your application, and so on) accept the event, the data-source control will then move into the dscSyncBefore state, at which time all outstanding data will be flushed, if necessary. For example, if the content of an edit field has changed, the change will be committed to the cursor. Following this event, the data-source control moves into the dscAboutToDo and dscSyncAfter states and finally into the dscDidEvent state. These provide you with further opportunities to catch notifications from the data-source control.

CWnd Overview |  Class Members |  Hierarchy Chart

See Also   CWnd::GetDSCCursor, CWnd::BindDefaultProperty, CWnd::BindProperty