# Progress

The **Progress** object lets you display and control a standard Directory Opus progress indicator dialog. This object can be obtained from the [**Command**](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.&#x20;
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_      | Before calling **Init**, set to **True** if the _Abort_ button should be available, or **False** to disable it.                                                                                                                     |
| bytes         | _bool_      | Before calling **Init**, set to **True** if the dialog should show progress in bytes rather than whole files.                                                                                                                       |
| delay         | _bool_      | Before calling **Init**, 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_      | Before calling **Init**, set to **True** to enable a "full size" progress indicator with two separate progress bars (one for files and one for bytes).                                                                              |
| owned         | _bool_      | Before calling **Init**, set to **True** if the dialog should be owned by its parent window (the parent is given later, when the dialog is created via the **Init** method).                                                        |
| pause         | _bool_      | Before calling **Init**, set to **True** if the _Pause_ button should be available.                                                                                                                                                 |
| skip          | _bool_      | Before calling **Init**, set to **True** if the _Skip_ button should be available. (This just makes it so the _Skip_ button can be enabled. You must still call **EnableSkip** later to actually enable it; usually once per file.) |

| Method Name        | **Arguments**                                                                                                                                          | Return Type | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AddFiles           | <p>&#x3C;int:count><br>&#x3C;<a href="filesize"><strong>FileSize</strong></a>:bytes></p>                                                               | _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_      | <p>Clears the state of the three "control" buttons (<em>Abort</em> / <em>Pause</em> / <em>Skip</em>) so they no longer register as being clicked when <strong>GetAbortState</strong> is called.<br>If you only want to clear the <em>Skip</em> state, you should normally do that as part of a call to <strong>EnableSkip</strong> instead. That way you avoid accidentally clearing one of the other states if they become set between you calling <strong>GetAbortState</strong> and <strong>ClearAbortState</strong>. In fact, there are very few situations where you should call <strong>ClearAbortState</strong>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| EnableSkip         | <p>*&#x3C;*bool:enable><br>*&#x3C;*bool:delay><br>*&#x3C;*bool:clear></p>                                                                              | _none_      | <p>Enables the progress dialog's <em>Skip</em> button. For <strong>EnableSkip</strong> to work, you must have set the <strong>skip</strong> property to <strong>True</strong> before the progress dialog was created by the <strong>Init</strong> method.<br><strong>enable</strong>: If <strong>True</strong>, the <em>Skip</em> button should be enabled; otherwise, it should be disabled.<br><strong>delay</strong> (optional, <strong>True</strong> by default): If <strong>True</strong>, there will be a short delay before the <em>Skip</em> button is enabled, with it temporarily disabled during the delay; otherwise, the change is instant. See below for why a delay is usually a good idea.<br><strong>clear</strong> (optional, <strong>True</strong> by default): If <strong>True</strong>, any record of the user pushing the <em>Skip</em> will be cleared, such that <strong>GetAbortState</strong> no longer returns <strong>"s"</strong>. You usually want this if the progress dialog just moved to a new item.<br>If you support the <em>Skip</em> button, you should normally call <strong>EnableSkip</strong> once per file, just after you call <strong>SetName</strong> and similar methods. When used that way, you'll usually want <strong>delay</strong> and <strong>clear</strong> to both be <strong>True</strong>, otherwise clicks of the <em>Skip</em> button intended for one file could affect the file(s) that come after it. For example, if a file takes a long time but then finishes just as the user gets tired of waiting and clicks <em>Skip</em>, the delay and cleared state ensure the unwanted click is harmless.</p>                                                                                                                                                                                                                                                                                                             |
| 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      | <p>&#x3C;bool:autoPause><br>&#x3C;string:wanted><br>&#x3C;bool:simple></p>                                                                             | _string_    | <p>Polls the state of the three "control" buttons. This returns a <em>string</em> 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:</p><p><strong>a</strong> - Abort<br><strong>p</strong> - Pause<br><strong>s</strong> - Skip</p><p>If none of the states apply, an empty string is returned.<br><strong>autoPause</strong> (optional, <strong>False</strong> by default): If <strong>True</strong>, pausing is handled for you automatically. Calls to <strong>GetAbortState(True)</strong> block while paused and don't return until unpaused; the "<strong>p</strong>" state is never returned. (Note that clicking <em>Skip</em> or <em>Abort</em> will implicitly unpause the operation.)<br><strong>wanted</strong> (optional): If you only want to check one or two of the states, pass a string with their letters. For example, <strong>GetAbortState(True,"ap")</strong> will test for the <em>Abort</em> and <em>Pause</em> states, but not the <em>Skip</em> one. All states will be checked if the argument is an empty string or not given at all.<br><strong>simple</strong> (optional, <strong>True</strong> by default): If <strong>True</strong>, the result string will have at most one letter, indicating the most important state. If <strong>False</strong>, it is possible for multiple states to be indicated at once. For example if <em>Skip</em> and then <em>Pause</em> are clicked, in that order, without the script clearing the <em>Skip</em> state, then <strong>GetAbortState(False,"",False)</strong> would return "<strong>ps</strong>" while <strong>GetAbortState(False)</strong> would return just "<strong>p</strong>".<br>To clear the state of the three buttons, call the <strong>ClearAbortState</strong> method. To clear just the <em>Skip</em> button's state, use the <strong>EnableSkip</strong> method.</p> |
| 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               | <p>&#x3C;<a href="tab"><strong>Tab</strong></a>:parent><br>or &#x3C;<a href="lister"><strong>Lister</strong></a>:parent></p><p>&#x3C;string:title></p> | _none_      | <p>Initializes the dialog. This method causes the actual dialog to be created, although it will not be displayed until the <strong>Show</strong> 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.<br>The <em>parent</em> parameter can be either a **<a href="tab">Tab</a>**or a <a href="lister"><strong>Lister</strong></a>- this controls which window the dialog is centered over, and if the <strong>owned</strong> property is set to <strong>True</strong> 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.<br>The <em>title</em> parameter specifies the window title of the dialog.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 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**](filesize):bytes>                                                                                                                       | _none_      | Sets the total completed byte count.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| SetFileSize        | <[**FileSize**](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          | <p>&#x3C;string:header><br>&#x3C;string:from><br>&#x3C;string:to></p>                                                                                  | _none_      | <p>Sets the text at the top of the dialog that indicates the source and destination of an operation. The <em>header</em> argument refers to the string that normally says <em>From:</em> - this allows you to change it in case that term is not applicable to your action. The <em>from</em> argument is the source path, and the <em>to</em> argument (if there is one) is the destination path. Note that if you specify a destination path this always has a <em>To:</em> header appended to it.<br>If you omit the <em>to</em> argument entirely (not just passing an empty string), the destination line will become blank, including the <em>To:</em> header. Use that if you want the second line to be used sometimes but not always. If you never want anything on the second line, use the <strong>SetStatus</strong> method instead as it will not add space for the extra line.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 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_      | <p>Sets the text displayed in the status line at the top of the dialog.<br>This sets a single-line status message, while <strong>SetFromTo</strong> can be used to indicate source and destination paths on two lines.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 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**](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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
