ProgressCallback class

Declaration

package com.kryptel;

public class ProgressCallback implements IProgressCallback {

    public interface IProgressDialog {
        void CreateProgress(Object arg,
                            String strTitle,
                            boolean totalBar,
                            BooleanFlag abortRequested) throws Exception;

        void SetProgressMessage(Object arg, String strMessage) throws Exception;
        void SetProgressStep(Object arg, int fileStep, int totalStep) throws Exception;
        void DismissProgress(Object arg) throws Exception;
    }

    public ProgressCallback(String title, IProgressDialog dialog, BooleanFlag abortRequested)

    public boolean Callback(Object arg, String curFile,
                            int stepFile, int stepTotal) throws Exception
}

Description

This class helps to implement IProgressCallback interface. Instead of implementing rather low-level IProgressCallback.Callback, the user needs to implement ProgressCallback.IProgressDialog, which directly maps to dialog window operations.

Note that this class is intended for library users; component authors should use the Progress class.

Constructor

public ProgressCallback(String title, IProgressDialog dialog, BooleanFlag abortRequested)

The constructor connects this class to ProgressCallback.IProgressDialog interface.

Parameters

title

Progress window title. Should not be confused with progress message. Progress title is a window title, which is being set on progress window creation and never changes. Progress message is actually the name of the file being processed and changes often.

dialog

Class implementing ProgressCallback.IProgressDialog interface.

abortRequested

A pointer to a BooleanFlag variable. If this variable changes to true during processing, then IProgressCallback.Callback will return false, signaling the calling library component that processing must be aborted. Note that this class neither creates nor modifies this flag. It receives this variable during class construction, initializes it to false, and passes it to IProgressDialog.CreateProgress. After that only IProgressDialog may change it; this class just monitors the flag value. This argument may be null if the client does not need to monitor user's abort requests.

Callback

public boolean Callback(Object arg, String curFile,
                        int stepFile, int stepTotal) throws Exception

Implementation of IProgressCallback.Callback. This method is called by the component, and that call is translated to the appropriate IProgressDialog call.

IProgressDialog interface

public interface IProgressDialog {
    void CreateProgress(Object arg,
                        String strTitle,
                        boolean totalBar,
                        BooleanFlag abortRequested) throws Exception;

    void SetProgressMessage(Object arg, String strMessage) throws Exception;
    void SetProgressStep(Object arg, int fileStep, int totalStep) throws Exception;
    void DismissProgress(Object arg) throws Exception;
}

This interface represents user-created progress window.

void CreateProgress(Object arg,
                    String strTitle,
                    boolean totalBar,
                    BooleanFlag abortRequested) throws Exceptio

Create a progress window.

Parameters

arg

An object representing execution context, or null for context-free operation. The client provides this pointer to the component during component initialization; the component passes it to the progress callback, and the ProgressCallback class passes it to this interface. Note that neither the component nor ProgressCallback use this argument; it is just some data that the client application passes to its own progress window implementation.

strTitle

Progress window title. See the description of title argument of ProgressCallback constructor.

totalBar

true if the progress window must have two bars, false if single-file operation.

abortRequested

BooleanFlag variable. If the user pressed the Abort button, the progress window implementation must set this flag, instructing the component to abort processing, perform cleanup, and throw UserAbortException. Note that this argument may be null, in which case user's abort requests are not to be monitored.

SetProgressMessage

void SetProgressMessage(Object arg, String strMessage) throws Exception;

Set the progress message string. Typically it is the name of the file being processed. See CreateProgress for a discussion of arg argument.

SetProgressStep

void SetProgressStep(Object arg, int fileStep, int totalStep) throws Exception;

Set the position of the progress bars. Steps are in range from 0 to IProgressCallback.PROGRESS_STEPS inclusively. For a single-file operation totalStep will be equal to IProgressCallback.NO_TOTAL_PROGRESS_BAR. See CreateProgress for a discussion of arg argument.

DismissProgress

void DismissProgress(Object arg) throws Exception;

Close the progress window. See CreateProgress for a discussion of arg argument.

If the progress window is not active, just do nothing.

Class Usage

1. Create a progress window class implementing ProgressCallback.IProgressDialog interface.
2. Create an instance of ProgressCallback class, and pass the progress window class to ProgressCallback constructor.
3. Pass the instance of ProgressCallback to the component that needs an IProgressCallback argument.
4. If the progress window need some data from the main application, pass it in the arg argument.