HOWTO: Use the Animated Copy Functions in Windows 95/98

ID: Q151799


The information in this article applies to:


SUMMARY

The Windows API provides the ability to perform a copy, move, rename, or delete operation on a file system object using the SHFileOperation API function exported by Shell32.dll. This article shows how to copy a list of files into a named folder while displaying a dialog box with a copy animation and an animated scroll bar displayed to show the progress of the copy operation. The article also shows how to create a sample project that demonstrates how the use of this API function.


MORE INFORMATION

The SHFileOperation function provides the ability to move, rename, or delete file system objects based on the flags passed to the function. The function requires the address of the SHFILEOPSSTRUCT structure. This structure contains the following members:

NOTE: The 32-bit version of Visual Basic aligns structures at double-word boundaries, but some API functions, such as the SHFileOperation, expect the data to arrive as byte-aligned. If you pass the SHFILEOPSTRUCT structure without taking this double-word boundary into consideration, the fAnyOperationsAborted, hNameMappings, and the lpszProgressTitle members of the structure will not be passed correctly. If you want the copy dialog box to contain a custom message string as defined by the lpszProgressTitle member, use a byte array to work around this limitation. The use of a byte array is demonstrated in the sample project.

The next section shows you how to create a sample project that demonstrates how to use the SHFileOperation function to copy the Visual Basic executable file and a Help file to a test folder. The sample project also shows you how to display a custom message string in the dialog box that displays the progress information.

Step-by-Step Example

  1. Start a new Standard EXE project in Visual Basic. Form1 is created by default.


  2. Add the two check boxes and one CommandButton to the Form1 form.


  3. Copy the following code to the Code window of the Form1 form:
    
       Option Explicit
    
             Private Const FO_COPY = &H2&   'Copies the files specified
                                            'in the pFrom member to the
                                            'location specified in the
                                            'pTo member.
    
             Private Const FO_DELETE = &H3& 'Deletes the files specified
                                            'in pFrom (pTo is ignored.)
    
             Private Const FO_MOVE = &H1&   'Moves the files specified
                                            'in pFrom to the location
                                            'specified in pTo.
    
             Private Const FO_RENAME = &H4& 'Renames the files
                                            'specified in pFrom.
    
             Private Const FOF_ALLOWUNDO = &H40&   'Preserve Undo information.
    
             Private Const FOF_CONFIRMMOUSE = &H2& 'Not currently implemented.
    
             Private Const FOF_CREATEPROGRESSDLG = &H0& 'handle to the parent
                                                        'window for the
                                                        'progress dialog box.
    
             Private Const FOF_FILESONLY = &H80&        'Perform the operation
                                                        'on files only if a
                                                        'wildcard file name
                                                        '(*.*) is specified.
    
             Private Const FOF_MULTIDESTFILES = &H1&    'The pTo member
                                                        'specifies multiple
                                                        'destination files (one
                                                        'for each source file)
                                                        'rather than one
                                                        'directory where all
                                                        'source files are
                                                        'to be deposited.
    
             Private Const FOF_NOCONFIRMATION = &H10&   'Respond with Yes to
                                                        'All for any dialog box
                                                        'that is displayed.
    
             Private Const FOF_NOCONFIRMMKDIR = &H200&  'Does not confirm the
                                                        'creation of a new
                                                        'directory if the
                                                        'operation requires one
                                                        'to be created.
    
             Private Const FOF_RENAMEONCOLLISION = &H8& 'Give the file being
                                                        'operated on a new name
                                                        'in a move, copy, or
                                                        'rename operation if a
                                                        'file with the target
                                                        'name already exists.
    
             Private Const FOF_SILENT = &H4&            'Does not display a
                                                        'progress dialog box.
    
             Private Const FOF_SIMPLEPROGRESS = &H100&  'Displays a progress
                                                        'dialog box but does
                                                        'not show the
                                                        'file names.
    
             Private Const FOF_WANTMAPPINGHANDLE = &H20&
                                       'If FOF_RENAMEONCOLLISION is specified,
                                       'the hNameMappings member will be filled
                                       'in if any files were renamed.
    
             ' The SHFILOPSTRUCT is not double-word aligned. If no steps are
             ' taken, the last 3 variables will not be passed correctly. This
             ' has no impact unless the progress title needs to be changed.
    
             Private Type SHFILEOPSTRUCT
                hwnd As Long
                wFunc As Long
                pFrom As String
                pTo As String
                fFlags As Integer
                fAnyOperationsAborted As Long
                hNameMappings As Long
                lpszProgressTitle As String
             End Type
    
             Private Declare Sub CopyMemory Lib "KERNEL32" _
                   Alias "RtlMoveMemory" _
                   (hpvDest As Any, _
                   hpvSource As Any, _
                   ByVal cbCopy As Long)
    
             Private Declare Function SHFileOperation Lib "Shell32.dll" _
                   Alias "SHFileOperationA" _
                   (lpFileOp As Any) As Long
    
             Private Sub Form_Load()
                Check1.Caption = "Copy All Files in VB Directory"
                Check2.Caption = "Display Custom Message"
                Command1.Caption = "Copy Files"
             End Sub
    
             Private Sub Command1_Click()
                Dim result As Long
                Dim lenFileop As Long
                Dim foBuf() As Byte
                Dim fileop As SHFILEOPSTRUCT
    
                lenFileop = LenB(fileop)    ' double word alignment increase
                ReDim foBuf(1 To lenFileop) ' the size of the structure.
    
                With fileop
                   .hwnd = Me.hwnd
    
                   .wFunc = FO_COPY
    
                   ' The files to copy separated by Nulls and terminated by two
                   ' nulls
                   If Check1.Value = vbChecked Then
                      .pFrom = "C:\Program Files\DevStudio\VB\*.*"  _
                           & vbNullChar
                           & vbNullChar
                      .fFlags = FOF_SIMPLEPROGRESS Or FOF_FILESONLY
                   Else
                      .pFrom = "C:\PROGRAM FILES\DEVSTUDIO\VB\VB5.EXE" _
                               & vbNullChar _
                               & "C:\PROGRAM FILES\DEVSTUDIO\VB\README.HLP" _
                               & vbNullChar _
                               & vbNullChar
                   End If
    
                   .pTo = "C:\testfolder\" & vbNullChar & vbNullChar
    
                   If Check2.Value = vbChecked Then
                      .fFlags = FOF_SIMPLEPROGRESS Or FOF_NOCONFIRMATION Or _
                                FOF_NOCONFIRMMKDIR
                      .lpszProgressTitle = "Your custom dialog string " & _
                                           "appears here." & vbNullChar _
                                                           & vbNullChar
                   End If
                End With
    
                ' Now we need to copy the structure into a byte array
                Call CopyMemory(foBuf(1), fileop, lenFileop)
    
                ' Next we move the last 12 bytes by 2 to byte align the data
                Call CopyMemory(foBuf(19), foBuf(21), 12)
                result = SHFileOperation(foBuf(1))
    
                If result <> 0 Then  ' Operation failed
                   MsgBox Err.LastDllError 'Show the error returned from
                                           'the API.
                   Else
                   If fileop.fAnyOperationsAborted <> 0 Then
                      MsgBox "Operation Failed"
                   End If
                End If
             End Sub
     


  4. On the Run menu, click Start or press the F5 key to start the program. Click Copy Files to start the copy process. To copy all the files in the Visual Basic program directory, check Copy All Files in VB Directory. To show where a custom message will display in the dialog box that shows the copy progress, check Display Custom Message.

    NOTE: On faster machines the dialog may not be displayed because the copy Operation completes before the dialog is shown. Select the Copy All Files option to guarantee that the dialog will be displayed.



REFERENCES

SHFileOperation and SHFILEOPSTRUCT in the Platform SDK product documentation

Err Object topic in the Microsoft Visual Basic Language Reference

Additional query words: kbVBp400 kbVBp500 kbVBp600 kbDSupport kbdsd kbVBp KBWIN32SDK KBAPI kbAPI


Keywords          : 
Version           : 
Platform          : WINDOWS 
Issue type        : kbhowto 

Last Reviewed: May 13, 1999