Home > User Guide > Memory Management

ACIS Progress Metering

A uniform progress callback mechanism is available for the following ACIS functionality:

The callback mechanism provides information needed by an application to implement a progress meter widget. This section describes the customer interface for this callback mechanism, and the requirements for customer implementation.

The customer interface consists of the SPA_progress_info class, and a customer callback which takes a pointer to a SPA_progress_info object, and returns an integer status code. The status code returned should normally be 0, but a status code of -1 can be returned to halt further ACIS calls to the customer callback, for the current instance of ACIS functionality. Before calling the ACIS functionality, the callback must be registered with ACIS using the function set_progress_callback. ACIS functionality agrees to call the customer callback at its start, at regular intervals during its task, and at the completion of its task. At each call to the customer callback, customer code may query the SPA_progress_info for information on the current state of the ACIS operation, and may update the progress meter accordingly. The query is done with the SPA_progress_info method percentage, which returns 0 on the first ACIS callback call, a positive integer between 1 and 99 at intermediate calls, and 100 on the final ACIS callback call.

Implementing Progress Metering for a Particular ACIS Functionality

The steps you must take are as follows:

  1. Write the callback function.

    2. The responsibilities of the callback function are to create the progress meter window (widget) on the first callback call, update the progress meter window on intermediate calls, and destroy the progress meter window on the last call.

  2. Register the callback using the ACIS function set_progress_callback before calling the ACIS functionality.

    3. A sample callback function is given by the function my_spa_progress_callback in the source file spa_progress_info.hxx. The customer callback is typedefed as: 
    typedef int (*SPA_progress_callback)(SPA_progress_info*);
    A sample code snippet registering the callback for advanced covering is: 
    int my_spa_progress_callback (SPA_progress_info* spi) {"dosomething"};
set_progress_callback(my_spa_progress_callback,
                             SPA_progress_info_ADV_COVER);
    The second argument set_progress_callback takes is a SPA_progress_info_type_id enum, which identifies the type of ACIS functionality being progress metered.

    There is also an overloaded function which takes a single argument, the callback function pointer, and registers it for all available ACIS functionality: 
    logical set_progress_callback(SPA_progress_callback callback_func_ptr);

Implementing Progress Metering for Additional ACIS Functionality

The SPA_progress_info avoids code duplication and provides a common look and feel via a common interface. The SPA_progress_info has a type query, get_type which returns a SPA_progress_info_type_id enum, noting which ACIS functionality it is metering. Using the type query, logic in a single callback can uniformly handle progress metering for all ACIS functionality desired. A single customer callback can be registered for all ACIS functionality: only one registration function in ACIS which takes a callback function pointer and a type argument. Of course, different customer callbacks can be registered for various ACIS functionality.

To uninstall the progress metering for advanced covering, for example, call:

set_progress_callback(NULL, SPA_progress_info_ADV_COVER);

The customer interface for uniform progress metering is found in the header file spa_progress_info.hxx. This header contains the customer callback typedef and customer callback registration prototype:

typedef int (*SPA_progress_callback)(SPA_progress_info*);
    logical set_progress_callback(SPA_progress_callback callback_func_ptr, SPA_progress_info_type_id type);

There is also an overloaded function which takes a single argument, the callback function pointer, and registers it for all available ACIS functionality:

logical set_progress_callback(SPA_progress_callback callback_func_ptr);

The function contains the SPA_progress_info_type_id enum declaration:

enum SPA_progress_info_type_id { SPA_progress_info_UNKNOWN, SPA_progress_info_RESTORE, 
    SPA_progress_info_STITCH, SPA_progress_info_ADV_COVER };

and contains the SPA_progress_info class declaration. The relevant methods of the SPA_progress_info class are:

int percentage() const;
SPA_progress_info_type_id get_type() const;

[Top]

© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.