Public Member Functions
ProgressBar Class Reference

Detailed Description

A progress bar is a control that indicates the progress of a lengthy operation by displaying a colored bar inside a horizontal rectangle. The length of the bar, in relation to the length of the rectangle, corresponds to the percentage of the operation that is complete.

Use UIToolkit::GetProgressBar to create a progress bar. The default minimum and maximum is between 0 and 100 with a step of 1.

Since:
4.0
Example:
Demonstrates the use of the progress bar.
        using namespace XSI;

        Application app;

        UIToolkit kit = app.GetUIToolkit();
        ProgressBar bar = kit.GetProgressBar();

        bar.PutMaximum( 50000 );
        bar.PutStep( 10 );
        bar.PutVisible( true );
        bar.PutCaption( L"Processing" );

        while (!bar.IsCancelPressed() && bar.GetValue() < bar.GetMaximum() )
        {
            CValue newVal(bar.Increment());
            bar.PutStatusText( L"Frame " + newVal.GetAsText() );
        }

#include <xsi_progressbar.h>

Inheritance diagram for ProgressBar:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 ProgressBar ()
 ~ProgressBar ()
 ProgressBar (const CRef &in_ref)
 ProgressBar (const ProgressBar &in_obj)
bool IsA (siClassID in_ClassID) const
siClassID GetClassID () const
ProgressBaroperator= (const ProgressBar &in_obj)
ProgressBaroperator= (const CRef &in_ref)
LONG GetMaximum () const
CStatus PutMaximum (LONG in_val)
LONG GetMinimum () const
CStatus PutMinimum (LONG in_val)
LONG GetStep () const
CStatus PutStep (LONG in_step)
LONG GetValue () const
CStatus PutValue (LONG in_val)
CString GetCaption () const
CStatus PutCaption (const CString &in_str)
CString GetStatusText () const
CStatus PutStatusText (const CString &in_str)
bool GetVisible () const
CStatus PutVisible (bool in_flag)
bool IsCancelPressed () const
LONG Increment (LONG in_val=1)
CStatus PutCancelEnabled (bool in_bEnable)
bool IsCancelEnabled () const

Constructor & Destructor Documentation

Default constructor.

Default destructor.

ProgressBar ( const CRef in_ref)

Constructor.

Parameters:
in_refconstant reference object.
ProgressBar ( const ProgressBar in_obj)

Copy constructor.

Parameters:
in_objconstant class object.

Member Function Documentation

bool IsA ( siClassID  in_ClassID) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:
in_ClassIDclass type.
Returns:
true if the class is compatible, false otherwise.

Reimplemented from CBase.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:
The class type.

Implements CBase.

ProgressBar& operator= ( const ProgressBar in_obj)

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:
in_objconstant class object.
Returns:
The new ProgressBar object.
ProgressBar& operator= ( const CRef in_ref)

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:
in_refconstant class object.
Returns:
The new ProgressBar object.
LONG GetMaximum ( ) const

Returns the upper limit of the progress bar's range. The default value is 100.

Returns:
The upper limit of the progress bar's range.
CStatus PutMaximum ( LONG  in_val)

Sets the upper limit of the progress bar's range.

Parameters:
in_valThe maximum value to be set for the progress bar. Attempting to set the maximum value to be less than the minimum value will result in an "invalid argument" error.
Returns:
CStatus::OK success
CStatus::InvalidArgument Invalid argument.
LONG GetMinimum ( ) const

Returns the lower limit of the progress bar's range. The default value is 0.

Returns:
The lower limit of the progress bar's range.
CStatus PutMinimum ( LONG  in_val)

Sets the lower limit of the progress bar's range.

Parameters:
in_valThe minimum value to be set for the progress bar. Attempting to set the minimum value to be greater than the maximum value will result in an "invalid argument" error.
Returns:
CStatus::OK success
CStatus::InvalidArgument Invalid argument.
LONG GetStep ( ) const

Returns the step value for the progress bar. The default value is 0.

Returns:
The step value for the progress bar.
CStatus PutStep ( LONG  in_step)

Sets the step value, which is the amount the progress bar will be incremented per increment step.

Parameters:
in_stepThe increment amount to be set for an increment step of the progress bar. Attempting to set the step value to be greater than the maximum value or a negative value will result in an "invalid argument" error.
Returns:
CStatus::OK success
CStatus::InvalidArgument Invalid argument.
LONG GetValue ( ) const

Returns the value of the progress bar. The default value is 0.

Returns:
The value of the progress bar.
CStatus PutValue ( LONG  in_val)

Updates the value of the progress bar. If the visibility is set to true the ProgressBar is redrawn to reflect the new position.

Parameters:
in_valAttempting to set the value to be greater than the maximum value will result in an "invalid argument" error.
Returns:
CStatus::OK success
CStatus::InvalidArgument Invalid argument.
CString GetCaption ( ) const

Returns the caption to be displayed during incrementation.

Returns:
The caption to be displayed during incrementation.
CStatus PutCaption ( const CString in_str)

Sets the caption to be displayed as the progress bar increments.

Parameters:
in_strText to display in the caption.
Returns:
CStatus::OK success
CStatus::Fail Failure.
CString GetStatusText ( ) const

Returns the status text to be displayed as the progress bar increments.

Returns:
The status text to be displayed as the progress bar increments.
CStatus PutStatusText ( const CString in_str)

Sets the status text to be displayed during incrementation.

Parameters:
in_strTest to display.
Returns:
CStatus::OK success
CStatus::Fail Failure.
bool GetVisible ( ) const

Returns the visibility state for the progress bar.

Returns:
true if the progress bar is visible or false if hidden.
CStatus PutVisible ( bool  in_flag)

Sets the visibility of the progress bar. Use this property to make the progress bar appear or disappear on the screen.

Parameters:
in_flagDisplay the progress bar if true or hide it if false.
Returns:
CStatus::OK success
CStatus::Fail Failure.
bool IsCancelPressed ( ) const

Returns true if the Cancel button on the progress bar has been clicked.

Returns:
true if the Cancel button on the progress bar has been clicked.
LONG Increment ( LONG  in_val = 1)

Advances the current position for the progress bar control by the specified number of steps. If the visibility is set to true the progress bar is redrawn to reflect the new position.

Parameters:
in_valThe amount to increment the current value.
Returns:
The new incremented value or -1 if the input value is less than zero.
CStatus PutCancelEnabled ( bool  in_bEnable)

Provides control over whether the progress bar will have a working Cancel button or not. By default the Cancel button is enabled. For operations that cannot be stopped part way through it is good UI design to disable the Cancel button.

Tip:
It is necessary to call this function before calling ProgressBar::PutVisible.
Parameters:
in_bEnableTrue to enable the Cancel button
Since:
4.0
bool IsCancelEnabled ( ) const

Returns true when the Cancel button on the progress bar is enabled


The documentation for this class was generated from the following file: