| ShellFileOperation( | op, | | source, | | dest, | | flags | ) |
|
Wrapper for the SHFileOperation shell function.
Parameters
| op | Type of operation, see Operations |
| source | list of source items, with each path separated by a “|”. |
| dest | a list of destination items. If the FOF_MULTIDESTFILES flag is set, the number of source and dest items should be the same. Otherwise, dest should be a single path into which all source items will go. Like source, separate multiple paths with a “|”. For FO_DELETE, you can leave this blank. |
| flags | a list of flags, again delimited by “|”s. See the Flags section for a list of available flags + their descriptions. It is fine to list one flag multiple times (it won’t do anything). |
Return Value
The return value depends on what build of AHK you are using. If you are using the normal “vanilla” build, you will just get a number. For users with object support, you’ll get an object.
Returned Number
The aborted flag from SHFileOperation (1 = an operation was aborted, 0 = nothing was aborted)
Returned Object (with the following members)
| aborted | same as the return value for vanilla AHK |
| error | the error code returned by SHFileOperation (0 = no error) |
| num_mappings | the number of mappings returned by SHFileOperation |
| mappings | an object containing all the mappings returned by SHFileOperation, where [key,value] corresponds to [old_path,new_path] |
Numbers vs Strings
If you really want to, you can give ShellFileOperation numbers rather than strings. For multiple flags, you’d have to bitwise-or them together. In the following snippet of code, both lines are equivalent (though one of them is easier to read...)
ShellFileOperation( "FO_Move","C:\file.txt", "G:\file.txt","FOF_SIMPLEPROGRESS|FOF_WANTMAPPINGHANDLE" )
ShellFileOperation( 0x1,"C:\file.txt", "G:\file.txt",0x100|0x20 )
Mappings
If the FOF_WANTMAPPINGHANDLE flag is given, SHFileOperation will return a set of mappings to describe any renaming that took place. For example...
| 1 | You try to move “C:\file.txt” to “G:\file.txt”, but “G:\file.txt” already exists. |
| 2 | You choose to rename (“keep both files”, as the error UI will say) |
| 3 | The returned mapping object will contain the key-value pair (“G:\file.txt”,”G:\file (2).txt”) |
ret := ShellFileOperation( "FO_Move","C:\file.txt", "G:\file.txt","FOF_SIMPLEPROGRESS|FOF_WANTMAPPINGHANDLE" )
MsgBox % ret.mappings["C:\file.txt"] ; will display G:\file (2).txt in this example
Tricking SHFileOperation
Mappings are useful, but what happens if the user cancels a single file copy? Unfortunately, SHFileOperation was not designed to provide such feedback. The abort flag will only tell you that some operation was aborted, leaving you to figure it out for yourself. However, I’ve discovered a way to trick SHFileOperation into reporting everything that was moved...
| For Folders | use a trailing slash. SHFileOperation will feel compeled to automatically rename the folder so as to remove the trailing slash, thus tricking it into including the operation in mappings. |
| For Files | use a trailing space. Again, SHFileOperation will remove the trailing slash automatically and place it into mappings. Unfortunately, there is a small problem with this trick. Any actual renames (due to conflicts) will get butchered. The ShFileOperation UI will offer to rename the file to, say “file (2).txt”, but will actually end up renaming it to “file.txt (2)”. However, this is a very easy problem to fix. In FileContainer, I use a postprocessing routine that picks out the butchered renames and manually fixes them. |
I may eventually include this functionallity directly in ShellFileOperation.