ProgressBar Class Reference
 
 
 
ProgressBar Class Reference

This reference page is linked to from the following overview topics: Interacting with the User.


#include <xsi_progressbar.h>


Class 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() );
                }
Inheritance diagram for ProgressBar:
CBase

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
ProgressBar operator= (const ProgressBar &in_obj)
ProgressBar operator= (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_ref constant reference object.
ProgressBar ( const ProgressBar in_obj )

Copy constructor.

Parameters:
in_obj constant 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_ClassID class 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_obj constant 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_ref constant 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_val The 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_val The 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_step The 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_val Attempting 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_str Text 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_str Test 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_flag Display 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_val The 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_bEnable True 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: