Display Progress and Debugger Messages

Report Generation Messages

The DOM API includes a set of messages that can display when you generate a report. The messages are triggered every time a document element is created or appended during report generation.

You can define additional messages to display during report generation. The DOM API provides these classes for defining messages:

ProgressMessage
DebugMessage
WarningMessage
ErrorMessage

The DOM API provides additional classes for handling report message dispatching and display. It uses MATLAB^® events and listeners to dispatch messages. A message is dispatched based on event data for a specified DOM object. For an introduction to events and listeners, see Event and Listener Concepts.

Note

When you create a message dispatcher, the DOM API keeps the dispatcher until the end of the current MATLAB session. Delete message event listeners to avoid duplicate reporting of message objects during a MATLAB session.

Display DOM Default Messages

This example shows how to display the default DOM debug messages. Use a similar approach for displaying other kinds of DOM report messages.

Create a message dispatcher, using the MessageDispatcher.getTheDispatcher method. Use the same dispatcher for all messages.
```
dispatcher = MessageDispatcher.getTheDispatcher;
```
Use the MessageDispatcher.Filter property to specify to display debug messages.
```
dispatcher.Filter.DebugMessagesPass = true;
```
Add a listener using the MATLAB addlistener function. Specify the dispatcher object, the source and event data, and a disp function that specifies the event data and format to use for the message.
```
l = addlistener(dispatcher,'Message', ...
      @(src, evtdata) disp(evtdata.Message.formatAsText));
```
Include a code to delete the listener. Place it after the code that generates the report.
```
delete(l);
```

This report displays debug messages.

import mlreportgen.dom.*;
d = Document('test','html');

dispatcher = MessageDispatcher.getTheDispatcher;
dispatcher.Filter.DebugMessagesPass = true;

l = addlistener(dispatcher,'Message', ...
      @(src, evtdata) disp(evtdata.Message.formatAsText));

open(d);

p = Paragraph('Chapter ');
p.Tag = 'chapter title';
p.Style = { CounterInc('chapter'),...
    CounterReset('table'),WhiteSpace('pre') };
append(p, AutoNumber('chapter'));
append(d,p);

close(d);
rptview('test','html');
     
delete(l);

Create and Display Progress Messages

This example shows how to create and dispatch a progress message. You can use a similar approach for other kinds of messages, such as warnings.

Create a message dispatcher.

dispatcher = MessageDispatcher.getTheDispatcher;

Add a listener using the MATLAB addlistener function.

l = addlistener(dispatcher,'Message', ...
      @(src, evtdata) disp(evtdata.Message.formatAsText));

Dispatch the message, using the Message.dispatch method. Specify the dispatcher object and the message to dispatch. Here the message is a debug message called starting chapter, and the Document object d is the source of the message.
```
dispatch(dispatcher,ProgressMessage('starting chapter',d));
```
Include code to delete the listener, after the code that generates the report.
```
delete(l);
```

This report uses this progress message.

import mlreportgen.dom.*;
d = Document('test','html');

dispatcher = MessageDispatcher.getTheDispatcher;

l = addlistener(dispatcher,'Message', ...
      @(src, evtdata) disp(evtdata.Message.formatAsText));

open(d);
dispatch(dispatcher,ProgressMessage('starting chapter',d));

p = Paragraph('Chapter ');
p.Tag = 'chapter title';
p.Style = { CounterInc('chapter'),...
    CounterReset('table'),WhiteSpace('pre') };
append(p, AutoNumber('chapter'));
append(d,p);

close(d);
rptview('test','html');
     
delete(l);

The MATLAB Command Window displays progress messages, including the starting chapter message and the messages the DOM API dispatches by default.