Quick Reference

Preparatory Tasks

Task Notes
Create a new empty stack (or open the DT Template stack).
Copy and paste your custom control onto the card. NOTE: Any other objects you need for your control will go on this card as well.
If your custom control is not already in a group object; group it.

Minimum Necessary to Create a (Prescripted) DropTool

Task Notes
Set the name of the custom control group object to "<dropToolType>"
Set the name of the stack to "<dropToolType>"

Additional Tasks Based on DropTool Requirements

Question Task if Answer is "Yes" Notes
Does your control
use a behavior
?
Make sure that there is a button named "<dropToolType> Behavior" DropTools supports these name variations (with or without a space after <dropToolType>):
  • "<dropToolType> Behavior"
  • "<dropToolType> Behaviour"
  • "<dropToolType> Class"
Does your control
require a library
to be brought into use?
Include your library as a substack called "<dropToolType> Library" If you need to install substacks into your library, you can include them as substacks of the DropTool stack and set the
uDTLibrarySubstacks
of the DropTool stack to the list of library substacks you want to install.
Does your control
contain any icons/images
or need any other objects to operate properly?
Put all of your resources into a group on the card named "<dropToolType> Resources"
Do you want your own
custom icon
for your control in the DropTools Palette?
Import or copy and image onto the card and name it "<dropToolType> Icon" If you don't have your own icon, one will be made automatically using a snapshot of the custom control group.
Does your DropTool only work in a specific version (or higher) of the DropTools Palette? Trap the DropTools_Loaded handler, and then execute DropTools_VersionCheck with the minimum supported version number for your DropTool. (See below for more info.) The icon of your DropTool will be disabled until the DropTools Palette has been sufficiently upgraded.

Messages You Can Trap

Message When it Occurs/Notes
DropTools_Loaded

Sent as soon as your DropTool is loaded into the DropTools Palette.

You might use this to run a private "check for updates" routine, or perhaps do a version check by executing DropTools_VersionCheck (see below).

DropTools_PreDragDrop destStackName

Sent to card 1 of the stack "<dropToolType>" as soon as your drop the control onto the target stack, but before any other actions are taken (such as copying objects, installing libraries, etc.).

destStackName is the short name of the stack that the DropTool control was dropped onto.

This can be used to run a script on a drag and drop, but without installing anything. (The "Secure With DTPasskey" DropTool implements this.)

NOTE: If you trap this message, the default behavior is to abort the rest of the drag-drop process. If you want the rest of the process to take place, you need to pass the DropTools_PreDragDrop message.

DropTools_DragDrop instanceID, destStackName

Sent to card 1 of the stack "<dropToolType>" right after the control has been dropped onto the target stack.

instanceID is the long id to the instance of the DropTool control that was just dropped onto the target stack.

destStackName is the short name of the stack that the DropTool control was dropped onto.

DropTools_DragDrop

Sent to the instance of the dropped control, right after it has been dropped (and after the previous DropTools_DragDrop message above).

This allows you to take an instance-specific post-drop action, such as initializing the control.

Control Instance Properties You Can Check

Property What It Holds
uDTType

Holds the DropTool 'type' of the instance (stsImageWell, PromptField, etc.).

uDTResourceCard

This holds the long ID to the card that holds any resources for the control instance.

This is normally a card in a substack of the target stack named "DropTools_<milliseconds>", but may point to a Custom Install Location instead.

Optional Features You Can Implement

Feature Task Notes
Display an Inspector palette for your control Include a substack named "<dropToolType> Inspector" Your Inspector will receive a revSelectedObjectChanged message whenever the user selects an object. Check the
uDTType
of the selected object to see if it is "<dropToolType>", and if so update your palette accordingly.
Display an "About Box" stack Include a substack named "About <dropToolType>" Your About box can contain anything you like; consider including help, documentation, or other support information.
Display an answer dialog with simple "About" information Set (at a minimum) the
uRIP["creator"]
property of your DropTool stack. You can include more information by setting one or more of the following additional "RIP" properties:
  • uRIP["version"]
  • uRIP["copyright"]
  • uRIP["name"]
  • uRIP["description"]
  • uRIP["homeURL"]
This is used if there is no "About Box" substack.

DropTools API Info

Code Purpose/Notes
Environment Info
DropTools_DTFolder() Gets the path to the DropTools folder (this is the one set in the DropTools Palette preferences window).
DropTools_DTPath(dropToolType) Get the path to a specific DropTool stack in the DropTools folder. The dropToolType is the name of the DropTool, e.g. "stsImagewell".
Manage Stack Windows/Memory
DropTools_OpenCentered
DropTools_CloseCentered
Opens modal dialog boxes in the center of the screen.

Since modal dialogs (like "answer") open centered on the defaultStack, it is likely that with your DropTool it will show up in either odd places or over the DropTools Palette itself.

DropTools uses this non-intrusive workaround by temporarily opening and focusing on an invisible stack and then closing it after your modal is closed. Here's how to use it:

    DropTools_OpenCentered
    answer "This is a test" -- the call to your modal
    DropTools_CloseCentered

NOTE: Make sure to call DropTools_CloseCentered otherwise you'll have an invisible stack left open in the mainstacks list.
stsSetPref "dropToolType_loc",
  newLoc
Manages the location of the Inspector Palette.

This is normally not necessary, as the DropTools Palette does this automatically for you every time the palette is moved (the moveStack message is trapped in a backscript, and stored as a preference).

However, should you need to artificially set the location, you can notify the DropTools Palette to store the new location with this API call.

Example for stsImageWell Inspector:
    stsSetPref "stsImageWell_loc","100,100"
DropTools_PurgeStack stackName Purges your DropTool from memory.

DropTools does a good job in trying to open, use, close, and purge DropTool stacks to keep them out of the mainstacks list. However sometimes you will need to purge your own DropTool from memory; this is really only necessary if your DropTool does any "send in time" messages or opens other stacks.

You can purge everything manually if you want, but if you'd rather just tell DropTools to do it for you, make this call along with the short name of the stack you want to purge.
Manage Preferences
DropTools_SetPref pref,value
DropTools_GetPref(pref)
The DropTools Palette will automatically append the name of your DropTool to the stored preference, so it is specific to your DropTool type.

If you want to store a pref for a specfic instance of your DropTool, put some unique identifier in the pref parameter.
Other API Calls
DropTools_VersionCheck
  dropToolType,versionToCheck
This can be executed if you want your DropTool to check to see if the DropTools Palette in use has a version number high enough to support your DropTool's needs. This usually is used when new features have been added to the DropTools Palette and your DropTool depends on those features.

After you provide your dropToolType and the minimum version of the DropTools Palette that supports your features in versionToCheck, a check will be made and if the version is not recent enough, the user will be offered the opportunity to check for an update.

If you execute this call and the DropTools Palette is not recent enough to support the required version, the icon for the DropTool will be disabled in the DropTools Palette until it has been updated to a proper version, and the string "older" will be returned in the result (in case you want to take some other action). If the version of the DropTools Palette can support your DropTool's version requirement, the result will be empty.
DropTools_TruncID(identifier) This function is very useful and works to replace the pathname from a 'long id' with the short stack name in order to make the reference portable, regardless of what system the user is on.

Example:

  put the long id of btn 1
  --> button id 1001 of card id 1002 of stack "/Users/ken/Test/myCoolStack.rev"

  put DropTools_TruncID(the long id of btn 1)
  --> button id 1001 of card id 1002 of stack "myCoolStack"
 
© 2015 Sons of Thunder Software, Inc.