CopyXFilesProgress

Description:

baCopyXFilesProgress copies multiple files, while displaying a progress dialog.

Platforms:

Windows and Macintosh

Usage:

Result = baCopyXFilesProgress( SourceDir , DestDir , FileSpec, Overwrite, Title, ButtonText, Flags )

Arguments:

String, string, string, string, string, string, integer.
SourceDir is the folder to copy from.
DestDir is the folder to copy to.
FileSpec determines what files are copied.
Overwrite determines how the copy is done. Can be:

"Always"

always copies the file

"IfNewer"

copies the file if SourceFile is newer than DestFile

"IfNotExist"

copies only if DestFile does not already exist
Title is the title of the dialog box.
ButtonText is the text to use in the Cancel button.
Flags changes the behaviour of the dialog, see Notes for details.

Returns:

Integer.
Returns 0 if the file was copied successfully, otherwise one of these:

Invalid Source file name

Invalid Dest file name

Error reading the Source file

Error writing the Dest file

Couldn't create directory for Dest file

Dest file exists

Dest file is newer that Source file

No files matched the specified type

User cancelled the copy

Examples:

Director:
OK = baCopyXFilesProgress( "c:\data" , "d:\backup" , "*.dat", "IfNewer", "Backing up files... ", "Cancel", 0 )

Authorware:
OK := baCopyXFilesProgress( "c:\\data" , "d:\\backup" , "*.dat", "IfNewer" , "Backing up files... ", "Cancel", 0 )
 

Notes:

By default, this function will not overwrite an existing file if that file is marked as read-only. However, by adding "+" to the "Always" and "IfNewer" options (eg "Always+" or "IfNewer+"), the files will be overwritten if they are read-only.

The return value will not be 0 if any file is not copied. For example, if you specify
baCopyXFilesProgress( "c:\data" , "d:\backup" , "*.*" , "IfNewer", ....... )
and any of the files in c:\data are newer than the ones in d:\backup, the return result will be 7 (Dest file is newer than Source). A result of 0 will be returned only if none of the files in c:\data is newer than d:\backup.

On Windows, the FileSpec argument follows normal DOS wildcard rules. A * means match any character in the file name.  So *.* copies all files; *.bmp copies all files with a .bmp extension; T*.* copies all files starting with the letter T.

On Macintosh, the FileSpec is either a four character type code eg "TEXT" or an extension eg ".txt". Only one type or extension can be specified. Use an empty string or "*.*" to match all files.

A return value of 6 (Dest file exists) can only be returned when Overwrite is "IfNotExist".

A return value of 7 (Dest file is newer than Source file) can only be returned when Overwrite is "IfNewer". The other return values can be returned for all Overwrite options.

The "IfNewer" option operates as follows: if both files have internal version numbers, then these numbers are used for comparison, otherwise the dates of the two files are used for comparison.

 Seven Flags are defined:

CP_NOCANCEL

1

does not show the Cancel button

CP_NOFILENAME

2 does not display the file names while copying

CP_STOPONERROR

4 stop copying if an error occurs

CP_NODIALOG

8 does not show the dialog box

CP_CALLBACK

 16  nable the copy callback handler

CP_ANIMATE

 32  shows system file copying animation

CP_SIZEUPDATE

 64  updates the callback handler by size

You can add any of these flags together to customize the dialog box.

To implement the callback handler, use the CP_CALLBACK flag. Typically you would also use the CP_NODIALOG flag and implement your own dialog box. If you use this flag then you need to add a handler called 'baCopyProgressUpdate'. This handler needs to be a movie script.

This handler will have two arguments passed into it - the percentage copied so far and the current file being copied. The handler will be called whenever the percentage copied has increased by one, or a new file is being copied. If you specify the CP_SIZEUPDATE, then your handler will be called whenever approximately 64k of data has been copied, rather than by percentage.

To stop copying, you can return 1 in your handler; return 0 or no return to continue copying. An example handler is listed below - the update functions would be used to update your own progress dialog.

on baCopyProgressUpdate percentage, filename
    updateProgressBar percentage
    updateStatus fileName
    if keyPressed( " " ) then -- if user presses space bar, stop copying
         return 1
    end if
end

The callback handler is only available on Director.

 

See also:

baCopyFile
baCopyXFiles
baXCopy
baCopyFileProgress
baXCopyProgress