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>):
|
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_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.).
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.
|
|
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:
|
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", |
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
|
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"
|