Progress Object Plugin

Actions

Progress.GetCurrentPos
Progress.GetRange
Progress.GetText
Progress.SetCurrentPos
Progress.SetRange
Progress.SetStep
Progress.SetText
Progress.StepIt

number Progress.GetCurrentPos (string ObjectName);

Description:

Returns the current position of the progress meter within the progress bar.

ObjectName:

(string) The name of the progress object.

Returns:

(number) The current position of the progress meter within the progress bar. If an error occurs -1 is returned.

Example:

-- Store the current position in nCurrentPos
nCurrentPos = Progress.GetCurrentPos("Status");

-- Check to see if any errors occurred calling the Progress.GetCurrentPos action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
    Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

table Progress.GetRange (string ObjectName);

Description:

Returns a table containing the range of the progress bar.

ObjectName:

(string) The name of the progress object.

Returns:

(table) A table containing the range of the progress bar, indexed by values "Begin" and "End". These values can be accessed using the form mytable.Begin and mytable.End. If an error occurs, nil is returned.

Example:

-- Store the current position in nCurrentPos
nCurrentPos = Progress.GetCurrentPos("Status");

-- Store the range in a table: tRange
-- Indexed by tRange.Begin and tRange.End
tRange = Progress.GetRange("Status");

-- Check to see if any errors occurred calling the Progress.GetRange action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
    Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Calculate the percent complete:
nPercentComplete = ((nCurrentPos - tRange.Begin) / (tRange.End - tRange.Begin)) * 100;

string Progress.GetText (string ObjectName);

Description:

Returns the text currently displayed on the progress object.

ObjectName:

(string) The name of the progress object.

Returns:

(string) The text currently displayed on the progress object. If no text is displayed or an error occurs, an empty string ("") is returned.

Example:

-- Get the current text from the Progress Bar
sCurrentText = Progress.GetText("Status");

-- Check to see if any errors occurred calling the Progress.GetText action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
    Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Print the current text to the debug window
Debug.Print("Progress Text: " .. sCurrentText .. "\r\n");

Progress.SetCurrentPos (string ObjectName, number Pos);

Description:

Sets the position of the progress meter within the progress bar.

ObjectName:

(string) The name of the progress object.

Pos:

(number) The position you want to set.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Get the current position
nCurrentPos = Progress.GetCurrentPos("Status");

-- Increment the current position
Progress.SetCurrentPos("Status", nCurrentPos + 1);

-- Check to see if any errors occurred calling the Progress.SetCurrentPosition action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
    Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Progress.SetRange (string ObjectName, number Begin, number End);

Description:

Sets the range of the progress bar.

ObjectName:

(string) The name of the progress object.

Begin:

(number) The beginning of the range.

End:

(number) The ending of the range.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Set the progress range from 0 to 100
Progress.SetRange("Status", 0, 100);

-- Check to see if any errors occurred calling the Progress.SetRange action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
    Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Progress.SetStep (string ObjectName, number Step);

Description:

Sets the step value that will be used whenever Progress.StepIt() is called.

ObjectName:

(string) The name of the progress object.

Step:

(number) The step value to use.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Set the step value to 10
Progress.SetStep("Status", 10);

-- Check to see if any errors occurred calling the Process.SetStep action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
    Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Progress.SetText (string ObjectName, string Text);

Description:

Sets the text currently displayed on the progress object.

ObjectName:

(string) The name of the progress object.

Text:

(string) The text you want to display on the progress object.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Store the current position in nCurrentPos
nCurrentPos = Progress.GetCurrentPos("Status");

-- Store the range in a table: tRange
-- Indexed by tRange.Begin and tRange.End
tRange = Progress.GetRange("Status");

-- Calculate the percent complete:
nPercentComplete = ((nCurrentPos - tRange.Begin) / (tRange.End - tRange.Begin)) * 100;

-- Set the current text to reflect the percent complete
Progress.SetText("Status", nPercentComplete .. "%");

-- Check to see if any errors occurred calling the Progress.SetText action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
    Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Progress.StepIt (string ObjectName);

Description:

Increments the current progress by the step amount specified in the Progress.SetStep() action.

ObjectName:

(string) The name of the progress object.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Set the progress bar range from 0 to 50
Progress.SetRange("Status", 0, 50);

-- Set the current position to 0 (the beginning)
Progress.SetCurrentPos("Status", 0);

-- Set the step size to 10
Progress.SetStep("Status", 10);

-- nLoopControl is used to control the loop below
nLoopControl = 5;

-- Do the following as long as nLoopControl is greater than 0
-- In this case, this loop will be performed 5 times
while nLoopControl > 0 do
    -- Increment the current progress   
    Progress.StepIt("Status");
    
    -- Check to see if any errors occurred calling the Progress.StepIt action.
    -- If any error occurred, display the error message.
    error = Application.GetLastError();
    if (error ~= 0) then
        Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
    end
    
    -- Subtract 1 from nLoopControl
    nLoopControl = nLoopControl - 1;
end