Q151799: HOWTO: Use the Animated Copy Functions in Windows 95/98/Me
Article: Q151799
Product(s): Microsoft Visual Basic for Windows
Version(s): 4.0,5.0,6.0
Operating System(s):
Keyword(s): kbAPI kbSDKWin32 kbVBp kbVBp400 kbVBp500 kbVBp600 kbGrpDSVB kbDSupport kbOSWinME
Last Modified: 19-FEB-2002
-------------------------------------------------------------------------------
The information in this article applies to:
- Microsoft Visual Basic Learning Edition for Windows, versions 5.0, 6.0
- Microsoft Visual Basic Professional Edition for Windows, versions 5.0, 6.0
- Microsoft Visual Basic Enterprise Edition for Windows, versions 5.0, 6.0
- Microsoft Visual Basic Standard Edition, 32-bit, for Windows, version 4.0
- Microsoft Visual Basic Professional Edition, 32-bit, for Windows, version 4.0
- Microsoft Visual Basic Enterprise Edition, 32-bit, for Windows, version 4.0
-------------------------------------------------------------------------------
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:
- hwnd - Window handle to the dialog box to display information about the
status of the file operation.
- wFunc - the operation to perform, as defined by one of the following values:
- FO_COPY - Copies the files specified in the pFrom member to the location
specified in the pTo member.
- FO_DELETE - Deletes the files specified in pFrom. (pTo is ignored.)
- FO_MOVE - Moves the files specified in pFrom to the location specified in
pTo.
- FO_RENAME - Renames the files specified in pFrom.
- pFrom - Address of a buffer to specify one or more source file names.
Multiple names must be null-separated. The list of names must be double
null-terminated.
- pTo - Address of a buffer to contain the name of the destination file or
directory. The buffer can contain multiple destination file names if the
fFlags member specifies FOF_MULTIDESTFILES. Multiple names must be
null-separated. The list of names must be double null-terminated.
- fFlags - Flags that control the file operation. This member can be a
combination of the following flags:
- FOF_ALLOWUNDO - Preserve Undo information, if possible.
- FOF_CONFIRMMOUSE - Not currently implemented.
- FOF_FILESONLY - Perform the operation on files only if a wildcard file
name (*.*) is specified.
- FOF_MULTIDESTFILES - The pTo member specifies multiple destination files
(one for each source file) rather than one directory where all source
files are to be deposited.
- FOF_NOCONFIRMATION - Respond with Yes to All for any dialog box that is
displayed.
- FOF_NOCONFIRMMKDIR - Does not confirm the creation of a new directory if
the operation requires one to be created.
- FOF_NOERRORUI - No user interface will be displayed if an error occurs.
- FOF_RENAMEONCOLLISION - 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.
- FOF_SILENT - Does not display a progress dialog box.
- FOF_SIMPLEPROGRESS - Displays a progress dialog box but does not show the
file names.
- FOF_WANTMAPPINGHANDLE - If FOF_RENAMEONCOLLISION is specified, the
hNameMappings member will be filled in if any files were renamed.
- fAnyOperationsAborted - Value that receives TRUE if the user aborted any file
operations before they were completed, or FALSE otherwise.
- hNameMappings - Handle to a file name mapping object that contains an array
of SHNAMEMAPPING structures. Each structure contains the old and new path
names for each file that was moved, copied, or renamed. This member is used
only if the fFlags member includes the FOF_WANTMAPPINGHANDLE flag. The handle
must be freed by using the SHFreeNameMappings function.
- lpszProgressTitle - Address of a string to use as the title of a progress
dialog box. This member is used only if fFlags includes the
FOF_SIMPLEPROGRESS flag.
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 = Environ("windir") & "\*.exe"
.fFlags = FOF_SIMPLEPROGRESS Or FOF_FILESONLY
Else
.pFrom = Environ("windir") & "\Explorer.exe" _
& vbNullChar _
& Environ("windir") & "\WinHelp.exe" _
& 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:
======================================================================
Keywords : kbAPI kbSDKWin32 kbVBp kbVBp400 kbVBp500 kbVBp600 kbGrpDSVB kbDSupport kbOSWinME
Technology : kbVBSearch kbAudDeveloper kbZNotKeyword6 kbZNotKeyword2 kbVB500Search kbVB600Search kbVB500 kbVB600 kbVB400Search kbVB400
Version : :4.0,5.0,6.0
Issue type : kbhowto
=============================================================================
THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.
Copyright Microsoft Corporation 1986-2002.