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 (MATLAB).

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.

  1. Create a message dispatcher, using the MessageDispatcher.getTheDispatcher method. Use the same dispatcher for all messages.

    dispatcher = MessageDispatcher.getTheDispatcher;
    dispatcher.Filter.DebugMessagesPass = true;
    
  2. Use the MessageDispatcher.Filter property to specify to display debug messages.

    dispatcher.Filter.DebugMessagesPass = true;
    
  3. 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));
    
  4. 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 a Progress Message

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.

  1. Create a message dispatcher.

    dispatcher = MessageDispatcher.getTheDispatcher;
    
  2. Add a listener using the MATLAB addlistener function.

    l = addlistener(dispatcher,'Message', ...
          @(src, evtdata) disp(evtdata.Message.formatAsText));
    
  3. 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));
    
  4. 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.

See Also

Functions

Classes