Progress

The Progress object lets you display and control a standard Directory Opus progress indicator dialog. This object can be obtained from the Command.progress property. The basic steps for using a Progress object are:

  1. Initialize the fundamental properties.
  2. Call the Init method to create the dialog (this creates it but does not show it to the user).
  3. When ready, call the Show method to make the dialog visible. 
  4. Call the appropriate methods to initialize the state of the progress bars (by setting the total number of files, total byte size, etc).
  5. As your operation progresses, advance the progress bars using methods like StepFiles and StepBytes.
  6. If appropriate, poll the state of the Abort and other control buttons using GetAbortState.
  7. Call the Hide method and destroy the object when your operation is finished.

 

Property Name

Return Type

Description

abort

bool

Set to True if the Abort button should be available, or False to disable it.

bytes

bool

Set to True if the dialog should show progress in bytes rather than whole files.

delay

bool 

Set to True if the dialog should delay before appearing after the Show method is called. The delay is configured by the user in Preferences.

full

bool

Set to True to enable a "full size" progress indicator with two separate progress bars (one for files and one for bytes).

owned

bool

Set to True if the dialog should be owned by its parent window (the parent is given when the dialog is created via the Init method).

pause

bool

Set to True if the Pause button should be available.

skip

bool

Set to True if the Skip button should be available.

 

Method Name

Arguments

Return Type

Description

AddFiles

<int:count>
<FileSize:bytes>

none

Adds the specified number of files to the operation total. The bytes argument is optional - in a "full size" progress indicator this lets you add to the total byte size of the operation.

ClearAbortState

none

none

Clears the state of the three "control" buttons (Abort / Pause / Skip).

FinishFile

none

none

Finish the current file. If the byte size of the current file has been set the total progress will be advanced by any remaining bytes.

GetAbortState

none

string

Polls the state of the three "control" buttons. This returns a string that indicates which if any of the three buttons have been clicked by the user. The button states are represented by the following letters in the returned string:

a - Abort
p - Pause
s - Skip

To clear the state of the three buttons, call the ClearAbortState method.

Hide

none

none

Hides the progress indicator dialog. The dialog object itself remains valid, and can be redisplayed with the Show method if desired.

HideFileByteCounts

<bool:show>

none

Hides or shows the "XX bytes / YY bytes" string in the progress dialog. You can use this to hide the string if the progress does not indicate a number of bytes (e.g. when it indicates a percentage). Pass True for the show argument to show the string and False to hide it.

Init

<Tab:parent>
or <Lister:parent>
<string:title>

none

Initializes the dialog. This method causes the actual dialog to be created, although it will not be displayed until the Show method is called. The fundamental properties shown above must be set before this method is called - once the dialog has been created they can not be altered.

The parent parameter can be either a Tab or a Lister - this controls which window the dialog is centered over, and if the owned property is set to True which window it is owned by (always appears on top of). If no parent is provided the dialog will not be associated with any particular window.

The title parameter specifies the window title of the dialog.

InitFileSize

none

none

Resets the byte count for the current file to zero.

Restart

none

none

Resets the total completed file and byte counts to zero.

SetBytesProgress

<FileSize:bytes>

none

Sets the total completed byte count.

SetFileSize

<FileSize:bytes>

none

Sets the size of the current file.

SetFiles

<int:count>

none

Sets the total number of files.

SetFilesProgress

<int:count>

none

Sets the total completed file count.

SetFromTo

<string:header>
<string:from>
<string:to>

none

Sets the text in the dialog that indicates the source and destination of an operation. The header argument refers to the string that normally says From: - this allows you to change it in case that term is not applicable to your action. The from argument is the source path, and the to argument (if there is one) is the destination path. Note that if you specify a destination path this always has a To: header appended to it.

SetName

<string:name>

none

Sets the name of the current file.

SetPercentProgress

<int:percent>

none

Sets the current progress as a percentage (from 0 to 100).

SetStatus

<string:status>

none

Sets the text displayed in the status line at the top of the dialog.

SetTitle

<string:title>

none

Sets the title of the dialog.

SetType

<string:type>

none

Sets the type of the current item - either file or dir.

Show

none

none

Displays the progress indicator dialog. Call this once you have created the dialog using the Init method.

SkipFile

<bool:complete>

none

Skips over the current file. Set the complete argument to True to have the file counted as "complete", or False to count it as "skipped".

StepBytes

<FileSize:bytes>

none

Step the byte progress indicator the specified number of bytes.

StepFiles

<int:count>

none

Step the file progress indicator the specified number of files.