class MProgressWindow

Jump to documentation

public members:

static bool	reserve ()
static MStatus	startProgress ()
static MStatus	endProgress ()
static MStatus	setProgressRange (const int minValue, const int maxValue)
static MStatus	setProgressMin (const int minValue)
static MStatus	setProgressMax (const int maxValue)
static int	progressMin ()
static int	progressMax ()
static MStatus	setProgress (const int progress )
static MStatus	advanceProgress (const int amount)
static int	progress ()
static MStatus	setTitle (const MString & title )
static MString	title ()
static MStatus	setProgressStatus (const MString & progressStatus )
static MString	progressStatus ()
static MStatus	setInterruptable (const bool value)
static bool	isInterruptable ()
static bool	isCancelled ()

Documentation

Description

The MProgressWindow class manages a window containing a status message, a graphical progress gauge, and optionally a "Hit ESC to Cancel" label for interruptable operations.

Only a single progress window may be displayed at any time. To reserve the use of the progress window, use the reserve() method in this class. Any methods that change the state of the progress window will fail unless the progress window has first been successfully reserved.

The startProgress() and endProgress() functions show and hide the progress window. endProgress() also has the effect of unreserving the progress window, allowing it to be reserved for another use.

The MEL command "progressWindow" provides equivalent functionality to this class. Attempting to manipulate a progress window that is in use by MEL will cause the methods in this class to fail.

Functions

MStatus MProgressWindow:: setProgressRange (const int minValue, const int maxValue)

Description

Sets the range (minValue, maxValue) of the progress indicator. When the progress value is set through setProgress() or advanceProgress(), it is checked against the minimum and maximum progress values. If the new progress value lies outside this range, it is clamped to a value in this range.

When the progress value is set to a value of minValue, the progress bar is displayed as empty. When the progress value is set to a value of maxValue, the progress bar is displayed as full. Intermediate progress values are displayed as intermediate positions of the progress bar.

Arguments

• minValue Minimum progress value
• maxValue Maximum progress value

Return Value

• Status code

Status Codes

• MS::kSuccess The range was set successfully.
• MS::kInvalidParameter max is less than or equal to min.
• MS::kFailure Progress has not been started.

MStatus MProgressWindow:: setProgressMin (const int minValue)

Description

Sets the minimum value for the progress. Any progress value less then minValue will be set to minValue, with the progress bar displayed as empty.

Arguments

• minValue Minimum progress value

Return Value

• Status code

Status Codes

• MS::kSuccess The minimum was set successfully.
• MS::kInvalidParameter max is less than or equal to min.
• MS::kFailure Progress has not been started.

MStatus MProgressWindow:: setProgressMax (const int maxValue)

Description

Sets the maximum value for the progress. Any progress value greater then maxValue will be set to maxValue, with the progress bar displayed as full.

Arguments

• maxValue Maximum progress value

Return Value

• Status code

Status Codes

• MS::kSuccess The maximum was set successfully.
• MS::kInvalidParameter max is less than or equal to min.
• MS::kFailure Progress has not been started.

int MProgressWindow:: progressMin ()

Description

Get the minimum progress value.

Return Value

• Minimum progress value

int MProgressWindow:: progressMax ()

Description

Get the maximum progress value.

Return Value

• Maximum progress value

MStatus MProgressWindow:: setProgress (const int progress )

Description

Sets the progress value. If progress is not between progressMin() and progressMax() inclusively, it is set to whichever of progressMin() or progressMax() is closest.

Advancing the progress value updates the progress bar to show the new amount of progress.

Arguments

• progress New progress value

Return Value

• Status code

Status Codes

• MS::kSuccess Progress value set.
• MS::kFailure Progress has not been started.

int MProgressWindow:: progress ()

Description

Get the progress value.

Return Value

• progress value

MStatus MProgressWindow:: advanceProgress (const int amount)

Description

Increases the progress value by amount. If the resulting progress value is not between progressMin() and progressMax() inclusively, it is set to whichever of progressMin() or progressMax() is closest.

Advancing the progress value updates the progress bar to show the new amount of progress.

Arguments

• amount Value to add to current progress

Return Value

• Status code

Status Codes

• MS::kSuccess Progress value set.
• MS::kFailure Progress has not been started.

MStatus MProgressWindow:: setTitle (const MString & title )

Description

Sets the title of the progress window.

Arguments

• title New title

Return Value

• Status code

Status Codes

• MS::kSuccess Title set.
• MS::kFailure Progress has not been started.

MString MProgressWindow:: title ()

Description

Get the window title.

Return Value

• window title string

MStatus MProgressWindow:: setProgressStatus (const MString & progressStatus )

Description

Sets the progress status string. This string is shown above the progress bar and usually is of the form "Performing operation: <x>" where <x> is a numerical indication of the amount completed.

Arguments

• progressStatus New status string

Return Value

• Status code

Status Codes

• MS::kSuccess Progress status set.
• MS::kFailure Progress has not been started.

MString MProgressWindow:: progressStatus ()

Description

Get the progress status string.

Return Value

• progress status string

MStatus MProgressWindow:: setInterruptable (const bool value)

Description

Sets whether the progress window is interruptable. An interruptable progress window can accept a signal from the user indicating that the operation should be cancelled.

isCancelled() is used to check if the user has tried to cancel an interruptable progress window.

Arguments

• value True if the progress window should be made interruptable.

Return Value

• Status code

Status Codes

• MS::kSuccess Interruptable value set.
• MS::kFailure Progress has not been started.

bool MProgressWindow:: isInterruptable ()

Description

Determine whether the progress window is interruptable.

Return Value

• true when the progress window is interruptable

bool MProgressWindow:: isCancelled ()

Description

Determine whether the user has tried to cancel an interruptable progress window. If the progress window is not interruptable, this method returns false.

Return Value

• true when user has tried to cancel progress

bool MProgressWindow:: reserve ()

Description

Reserves a progress window for use through this class. This method must be called before setting progress window parameters or starting progress.

Return Value

• true if the progress window was successfully reserved

MStatus MProgressWindow:: startProgress ()

Description

Displays the progress window on the screen.

Return Value

• Status code

Status Codes

• MS::kSuccess The progress window was created and displayed.
• MS::kFailure Progress has already been started.

MStatus MProgressWindow:: endProgress ()

Description

Destroys the progress window and removes it from the screen. This method also unreserves the progress window, making it available for future reservation.

Return Value

• Status code

Status Codes

• MS::kSuccess The progress window was destroyed.
• MS::kFailure Progress has not been started.

This class has no child classes.