GraphicsMagick

- Home
- Project
- Download
- Install
- Source
- News
- Utilities
- Programming
- Reference

# monitor

## Progress monitor support

Contents

- MagickMonitor
- MagickMonitorFormatted
- SetMonitorHandler

# MagickMonitor

## Synopsis

    MagickPassFail MagickMonitor( const char *text, const magick_int64_t quantum,
                                  const magick_uint64_t span, ExceptionInfo *exception );

## Description

MagickMonitor() calls the monitor handler method with a text string that describes the task and a measure of completion. The method returns True on success otherwise False if an error is encountered, e.g. if there was a user interrupt.

This function is deprecated. Please use MagickMonitorFormatted() instead.

The format of the MagickMonitor method is:

    MagickPassFail MagickMonitor( const char *text, const magick_int64_t quantum,
                                  const magick_uint64_t span, ExceptionInfo *exception );

text:
  Description of the task being performed.
quantum:
  The position relative to the span parameter which represents how much progress has been made toward completing a task.
span:
  The span relative to completing a task.
exception:
  Return any errors or warnings in this structure.

# MagickMonitorFormatted

## Synopsis

    MagickPassFail MagickMonitorFormatted( const magick_int64_t quantum,
                                           const magick_uint64_t span,
                                           ExceptionInfo *exception, const char *format,
                                           ... );

## Description

MagickMonitorFormatted() calls the monitor handler method with a printf type format specification and variable argument list. Also passed are quantum and span values which provide a measure of completion. The method returns MagickPass on success otherwise MagickFail if an error is encountered, e.g. if there was a user interrupt. If MagickFail is returned, the calling code is expected to terminate whatever is being monitored as soon as possible.

Most callers of this function will use the QuantumTick() macro to decide when it should be called. The QuantumTick() macro is designed to deliver no more than 100 events in a span (representing 1-100%) and to distribute events as evenly as possible over the span so that events are reported for every 1% of progress when possible.

The format of the MagickMonitorFormatted method is:

    MagickPassFail MagickMonitorFormatted( const magick_int64_t quantum,
                                           const magick_uint64_t span,
                                           ExceptionInfo *exception, const char *format,
                                           ... );

quantum:
  The position relative to the span parameter which represents how much progress has been made toward completing a task.
span:
  The span relative to completing a task.
exception:
  Return any errors or warnings in this structure.
format:
  A string describing the format to use to write the remaining arguments.

# SetMonitorHandler

## Synopsis

    MonitorHandler SetMonitorHandler( MonitorHandler handler );

## Description

SetMonitorHandler() sets the monitor handler to the specified method and returns the previous monitor handler.

The format of the SetMonitorHandler method is:

    MonitorHandler SetMonitorHandler( MonitorHandler handler );

A description of each parameter follows:

handler:
  Specifies a pointer to a method to handle monitors.