<destination> is the HFS pathname for the dest file
<restype> is the resource type, such as XCMD, and is always 4 chars
<resource> is the resource name, such as "ResCopy" for this XCMD
The ResCopy command returns a string to HyperTalk to let you know what actually happened when the command was called.
To see what happened, use HyperTalk's Result property. You can say "GET THE RESULT" or "PUT THE RESULT IN IT" to get the result code. The code will be either "OK" or "ERR" followed by a number.
ERR1 means the wrong number of parameters were passed.
ERR2 means the source file couldn't be opened.
ERR3 means a new destination file couldn't be created.
ERR4 means the resource to be copied wasn't found in the source.
OK1 means the resource was copied OK to an existing file.
OK2 means a new destination file or resource fork was created.
OK3 means an existing resource was replaced by the copied one.
----------------
James L. Paul Text
The ability to add external commands and functions to HyperTalk is the result of excellent foresight. However, not everyone knows how to create their own XCMDs and XFCNs. As a programmer, I saw the advantages that these external commands and functions could provide. Lately, it's been brought to my attention frequently that many people are having problems understanding how to use XCMDs and XFCNs with HyperCard. Most of this problem seems to be with the concept of resources and with the use of ResEdit. Giving people the ability to use XCMDs and XFCNs without ANY ResEdit knowledge is what is required. I think I have found an ideal method.
I considered many different methods of copying resources from one stack to another. As a programmer, I've always depended on various utilities, such as ResEdit. Naturally, these utilities are not geared for non-programmers. Yes, I know many people can copy and paste resources with ResEdit, but what about those who can't?
I decided that what people really need is a way to move resources around with a HyperCard user interface. I thought to myself: "Now, if only I could make it as easy as pasting a button!" So, that's what I did.
With the use of my ResCopy XCMD and some HyperTalk scripting, I have developed a method that literally makes copying any named resource from one stack to another as easy as pasting a button. That's exactly what the user does, with my method. He copies a button, pastes it into another stack, then clicks on it.
After clicking on the button, the button automatically is deleted, and the resources have been copied into the stack. This is easy to do, from both a programming view, and a user's view.
It's my hope that XCMD and XFCN developers will adopt my method, making the use of external commands and functions simple, easy, and desireable. I reserve all commercial rights to my XCMDs, but this one, my ResCopy XCMD, I hope will be used by anyone who wants to add this ability to their stack.
If you have written any XCMDs or XFCNs, and don't have a method like this to make it easy for the users, I hope you will take the time to consider my method. I feel that users will benefit greatly by the effort.
In addition to moving XCMD and XFCN resources, my ResCopy command will copy ANY named resource. This means it can be used for sound resources, icons, or anything else that you may wish to have moved to another stack by the user.
The real power of this method isn't in the ResCopy XCMD itself, but in the HyperTalk scripting. I use two scripts, one of them modifies the other. I use the stack script to modify a card button script. This card button is the button that the user can copy and paste into another stack to move the resources.
Each time the stack is opened, the stack script makes sure that the button script has the current complete pathname of the stack. This stack, of course, is the one with the resources you want users to be able to copy.
When the user copies the card button from the "About..." card and pastes it into another stack, the button script still knows exactly where it's original stack is, because it has the complete pathname.
The button won't do anything unless the user has pasted it into another stack, since we don't want to copy the resources over themselves. After the user has pasted the button into another stack, he can click on it. This starts the magic.
First, the button gets the name of the stack it's in. Now it knows two pathnames. It has the pathname of it's own stack, the one with the resources to be moved. It also has the pathname of the current stack, the one it needs to paste the resources into. Now that it knows both the source and the destination, it proceeds to copy.
Of course, the button is now running in the user's stack, which doesn't have the ResCopy XCMD, since that is in the original stack.
This problem is solved by jumping back into the original stack, where we have the resources. First, the screen and message box are locked, so that the user isn't confused by the messy stack-changing that's coming up.
It's no problem to jump back to the original stack, since the button script knows exactly where it is by it's pathname.
After the jump is made to the original stack, the ResCopy command can be used, since it's the resource fork of the stack.
We won't jump back to the user's stack until we're done copying.
Next, the button script calls my ResCopy XCMD to copy each resource that I want the user to have. Here is where the XCMD takes over...
ResCopy opens the source file by it's pathname. If there's no problem opening it, it assumes that everything is fine.
ResCopy then tries to open the destination file by it's pathname. If there's an error, it assumes it's because the file doesn't have a resource fork. Stacks aren't created with resource forks. If this happens, then ResCopy creates a resource fork in the stack. In fact, it's possible to use ResCopy in this way to create a new resource file, by not giving it the name of an existing file.
Now, at this point, both files are open, and ready for copying.
Now that both resource forks are open, ResCopy uses the type and name parameters passed to it when it's called from HyperTalk.
ResCopy attempt to get the resource with the type and name specified. If there is a problem and it can't, ResCopy quits and returns to HyperCard, and reports the error.
More likely, ResCopy gets the resource successfully, and turns it's attention to the destination file, the stack we want to paste the resource into.
First, ResCopy looks for a resource in the stack with the same name. If there is one, it removes it, so that there won't be two resources with the same name after the pasting is done.
Next, ResCopy gets a unique ID number, so that it doesn't disturb any existing resources. Now the resource is added, with a new ID number. This won't affect anything, since HyperTalk uses resource names instead of ID's when dealing with XCMD and XFCN resources.
Now that the resource has been successfully added, both files are closed, and ResCopy returns control to the HyperTalk button script.
The button script calls ResCopy like this for each resource to be pasted into the user's stack. After each resource has been copied, the button script then returns to the destination stack.
After returning to the user's stack, which now has the resources pasted into it, the button uses the menubar to delete itself, and then unlocks the screen and message box.
As you can see, the user doesn't have to do anything, except copy the button into a stack and click on it. After a few seconds, the button disappears, and nothing seems changed. But now, the resources are in the resource fork of the stack, and can be used.
Of course, the user needs to be told what needs to be done and why. I feel, however, that this method is far superior to using ResEdit for the users. Many times I have tried to explain to a user how to use ResEdit in one way or another. Using this method instead eliminates much confusion, and allows users to move XCMDs and XFCNs the HyperCard way: by pasting buttons.
This method has, I believe, enough attractive features to make it a great way to standardize somewhat the way we move resources from stack to stack.
With this method, users can rename the stack at any time, or move it from folder to folder, without causing any problems. Since the pathnames are updated each time the stack is opened, a valid pathname will always be used.
The user doesn't lose any flexibility by using this method. As long as the two key scripts aren't changed, the method should work. One potential problem would be if a user Cut the button, rather than Copying. This would leave him without the button to use later. Users should be warned about this, and be told explicitly to Copy, not Cut.
As I have mentioned, it is my hope that many XCMD and XFCN developers will adopt a method similar to this. This is how moving commands from stack to stack should be done: easy for the user.
This method has, I believe, enough attractive features to make it a great way to standardize somewhat the way we move resources from stack to stack.
With this method, users can rename the stack at any time, or move it from folder to folder, without causing any problems. Since the pathnames are updated each time the stack is opened, a valid pathname will always be used.
The user doesn't lose any flexibility by using this method. As long as the two key scripts aren't changed, the method should work. One potential problem would be if a user Cut the button, rather than Copying. This would leave him without the button to use later. Users should be warned about this, and be told explicitly to Copy, not Cut.
This stack contains a button that used the method described to move my ResCopy resource into another stack.
Please look at the stack script and the button script, and use them as examples for your own stacks.
There are, of course, NO fees for using any of this stack, my ResCopy XCMD, or any of the ideas here. I want people to use this stack as food for thought, and as an example of how to make things easier for users in the HyperCard world.
I've intentionally kept this stack simple, and intend it only as an example to other XCMD and XFCN developers. For an example of this method in actual use, see my stack called "Talk To Me", which uses three XCMDs and uses Macintalk to speak. Users can copy the talking commands with this method, and
use them in their own stacks.
This stack contains version 1.2 of the ResCopy command. This is the second version of this stack to be released. The XCMD itself has been improved and is more solid. A potentially serious bug has been fixed, also. Thanks to the people who pointed things out to me, and have offered suggestions.
ResCopy now will not cause HyperCard to lose track of resources in the current stack after it is run.
