DoMessage Method
Provides a modal dialog box when AllowModalMessages is True (.T.), otherwise triggers DoStatus.
oReportListener.DoMessage(cMessage[,nParams[,cTitle])
Parameters
- cMessage
Specifies the message shown by the ReportListener object's user feedback mechanism.
- nParams
Numeric value specifying dialog box attributes, identical to the values allows in the MESSAGEBOX function.
- cTitle
Specifies caption for the dialog box. Like the MESSAGEBOX function, this value defaults to Microsoft Visual FoxPro if you do not include it.
Return Value
None.
Remarks
Applies To: ReportListener Object.
The baseclass ReportListener object uses a MESSAGEBOX dialog box to provide modal feedback. Its second and third parameters are identical to those you use in the MESSAGEBOX function. For more information, see MESSAGEBOX( ) Function.
If you override or augment this method, you should observe the same parameter conventions, as well as additional interface requirements set by the baseclass: respect the values of AllowModalMessages and QuietMode properties when evaluating what type of feedback the method should display. For more information, see MESSAGEBOX( ) Function and QuietMode Property.
Unlike the MESSAGEBOX function, the baseclass ReportListener does not have a fourth argument specifying a numeric Timeout value, and it has no mechanism for responding to a return value. In a class deriving from ReportListener, however, you can opt to implement this functionality, and you can choose how you want to handle the user's response.
For example, the ReportListener User Feedback Foundation Class uses an augmented version of this method to allow users to cancel a report midway through a report run.
Example
The following code shows the way ReportListener User Feedback Class invokes DoMessage to allow users to cancel a report. This class leverages the version of DoMessage implemented by ReportListener Base Foundation Class, its parent. The enhanced method provides a suitable return value, so the User Feedback Class can respond to the user's choice. ReportListener Base Foundation Class's implementation of the DoMessage method is also shown below.
Tip
Notice that ReportListener Base Foundation Class provides a consistent numeric value for the second parameter when it invokes MESSAGEBOX. If you use the baseclass ReportListener's DoMessage method, and if you do not need to specify dialog box attributes but wish to provide a custom dialog box caption, you should provide a value of 0 for the second parameter, similar to what you see in this example. If you specify a non-numeric value for this parameter (such as .F.), an error occurs.
* UpdateListener class
* (ReportListener User Feedback Foundation Class)
PROCEDURE CancelReport
IF THIS.IsRunning AND ;
(THIS.QuietMode OR ;
(NOT THIS.AllowModalMessages) OR ;
THIS.DoMessage(;
OUTPUTCLASS_REPORT_CANCELQUERY_LOC, ;
MB_ICONQUESTION+MB_YESNO) = IDYES )
DODEFAULT()
IF SYS(2024) = "Y"
THIS.ThermForm = NULL
THIS.DoMessage(OUTPUTCLASS_REPORT_INCOMPLETE_LOC, ;
MB_ICONEXCLAMATION)
ENDIF
ELSE
NODEFAULT
ENDIF
ENDPROC
* _ReportListener class
* (ReportListener Base Foundation Class)
PROCEDURE DoMessage(cMessage,iParams,cTitle)
NODEFAULT
IF THIS.QuietMode OR ;
(THIS.IsRunning AND THIS.CommandClauses.NoDialog)
* to emulate the base class behavior, do both checks,
* in case the call to DoMessage() occurs
* before the baseclass sets QuietMode .T. in response
* to NoDialog at the beginning of the report run,
* or after the baseclass re-sets QuietMode to .F.
* at the end of the report run.
RETURN 0
ELSE
IF THIS.AllowModalMessages
IF VARTYPE(cTitle) = "C"
RETURN ;
MESSAGEBOX(TRANS(cMessage), ;
VAL(TRANS(iParams)),cTitle)
ELSE
RETURN ;
MESSAGEBOX(TRANS(cMessage), ;
VAL(TRANS(iParams)),THIS.AppName)
ENDIF
ELSE
THIS.DoStatus(cMessage)
RETURN 0
ENDIF
ENDIF
ENDPROC
See Also
Reference
ReportListener Object
DoStatus Method
ReportListener User Feedback Foundation Class
ReportListener Base Foundation Class