Creating a Library-based DropTool

This is the most flexible form of DropTool: a control that has all of its scripts inside a separate library stack, and has very little (or no) scripts inside itself. It usually requires support resources, such as images.

What is the Advantages/Disadvantages to Using a Library?

On the plus side, you get most of the benefits of using a behavior button, but you also get the benefit that it is in a stack which can be password protected, and brought into and out of use as you need it. If you have multiple controls that share certain functionality, they can all call on the same library stack if you like.

On the minus side, you need to actively "start using" the stack in order to make the scripts available, and you need to be careful about handler naming conventions to make sure that your code doesn't accidentally get run by some other person's handler. There is also a limit of 50 libraries that can be in use at any one time (although I've never seen anyone load that many libraries before).

The DropTool in this example is a behavior-based variation of the prescripted "Next" button example. If you haven't looked at that example yet, you should review it before looking at this example.

It looks like this:	...with this script:	... that uses a library...	...with this script:
	on mouseUp GoNext end mouseUp		command GoNext go next card end GoNext

To make the DropTool, take the same steps as for the prescripted version, plus the extra steps (#5 and #7) shown in bold below:

1. Open the
   DropTool Template.livecode
   stack.
2. Copy and paste the button from your stack onto the DropTool Template stack. (If you hadn't already created it, you can create it from scratch on the first card of the DropTool Template stack.)
3. Since custom controls must be in a group, make sure your button is selected and then group it (adjust the margins of the group if you like).
4. Give your control group the name
   "NextButton"
   (this is its DropTool "type").
5. Set the script of your control to one that calls on the library.
6. Change the name of the stack from "DropTool Template" to
   "NextButton"
   (same as your control). (You can change the title as well if you like.)
7. Add a substack to your stack called "NextButton Library", that has your library script in it.

As with the prescripted version, you can change the values in the custom property set for the stack to correspond to your own "about" information, or delete the custom property set in its entirety if you don't want to provide any "about" info.

You can also make the stack "clean" by deleting the extra About and Inspector substacks and the instructions field on the main card if you like.

Choose and save your stack in the DropTools folder.

Close the stack in LiveCode, and then open the DropTools Palette (or close and reopen it). When you try to drag and drop your control onto a stack, you should get the "Library Required" dialog that will step you through installing and bringing into use the library that your control needs.

Installing Library Substacks

If you need your library to ultimately have substacks when it gets installed for the user, make sure to set the of the main DropTool stack to a return-delimited list of short substack names. So for example if you have your library "MyCoolControl Library" and it needs to ultimately have the substacks "MyCoolControl Config" and "MyCoolControl Updater" after it is installed, you would add three substacks to your "MyCoolControl" DropTool stack:

• MyCoolControl Library
• MyCoolControl Config
• MyCoolControl Updater

You would then set the of your "MyCoolControl" DropTool stack to: MyCoolControl Config
MyCoolControl Updater

When your library is installed, the name of the library changes (the "Library" at the end is turned into "lib" in front), and the substacks are all installed but with underscores in front of them (this is to avoid stack name conflicts). So in the example above, after the "MyCoolControl" has been installed with its libraries, the new library stack file on disk will have:

• A mainstack named "libMyCoolControl"
• A substack named "_MyCoolControl Config"
• A substack named "_MyCoolControl Updater"

Keep this in mind when you address your substacks by name in your code.

Some "FYIs" About Using Libraries

Here are some things to be aware of when using libraries:

1. Although the DropTools Palette does its best to assist the user in bringing the stack into use, the user may forget to add the code, or not include the right path to start using the stack.
2. If you "stop using" a library, that stack is still loaded into memory, even if you never explicitly opened it. You can check this for yourself - start using a stack, then stop using it, then check "the mainstacks"... your stack will still be there. In order to fully purge a library from memory, you need to not only stop using the stack, but "delete" it as well. Since "delete", when performed on a substack will actually delete the substack itself, it's best to use this kind of test before you delete a stack to remove it from memory:

   stop using "MyCoolControl Library"
   if "MyCoolControl Library" is among the lines of the mainstacks then
     delete stack "MyCoolControl Library"
   end if

3. As mentioned above, make sure your handler names in your library follow a custom naming convention to avoid being called accidentally by third-party script handlers.