baCopyFileProgress copies a file, while displaying a progress dialog.


Windows and Macintosh


Result = baCopyFileProgress( SourceFile , DestFile , Overwrite, Title, ButtonText, Flags )


String, string, string, string, string, integer.
SourceFile is the file to copy.
DestFile is the name to copy it to.
Overwrite determines how the copy is done. Can be:


always copies the file


copies the file if SourceFile is newer than DestFile


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 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


OK = baCopyFileProgress( "c:\data\student.dat" , "c:\data\backup\student.dat" , "IfNewer", "Backing up files... ", "Cancel", 0 )

OK := baCopyFileProgress( "c:\\data\\student.dat" , "c:\\data\\backup\\student.dat" , "IfNewer" , "Backing up files... ", "Cancel", 0 )


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:



does not show the Cancel button


2 does not display the file names while copying


4 stop copying if an error occurs


8 does not show the dialog box


 16  nable the copy callback handler


 32  shows system file copying animation


 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

The callback handler is only available on Director.


See also: