Droplet
Developer Kit 3.0.3
UserLand Software, Inc.
©
copyright 1992, 1993, UserLand Software, Inc.
UserLand
Software is the developer of the UserLand Frontier scripting system. The
company is located at 555 Bryant #237, Palo Alto, CA 94301. 415-326-7791, 415-326-7793(fax).
UserLand, Frontier, Frontier Runtime and Frontier Extras are trademarks of
UserLand Software, Inc. Other product names may be trademarks or registered
trademarks of their owners.
Email:
userland.dts@applelink.apple.com. If youŐre an AppleLink user, check out the
UserLand Discussion Board under the Third Parties icon. CompuServe users enter
GO USERLAND at any ! prompt. On America On-Line, enter the keyword USERLAND.
Comments,
questions and suggestions are welcome!
Background
The
Droplet Developer Kit includes all the scripts and docs you need to create your
own droplets -- double-clickable applications that have an embedded script that
is run once for each file, folder or disk icon thatŐs dragged onto the app.
A
droplet is a hybrid, part application and part script. Users can drag and drop
Finder icons onto droplets. The script contained within the application is run
once for each of the icons dragged onto the application. Sample droplets are
available from UserLandŐs CompuServe, AppleLink and America On-Line support
boards.
How to Install
1. Be sure
Frontier is running.
2. Double-click
on the Installer script.
Using a Droplet
When
you drag and drop a set of file, folder or disk icons onto the droplet icon, a
window appears.
HereŐs
what each of the three buttons in the droplet's window does:
1. Run
Click on this button to run the embedded script once for
each file dragged onto the droplet icon. If you double-click on the droplet
icon (no files dragged) the Run button is disabled.
2. Edit
Brings Frontier to the front and opens a window that
contains the embedded script and information about the droplet. Also launches
the Droplet Developer suite.
After making changes to the droplet, choose the Export to
AppÉ command from the Droplet menu.
The Edit button is disabled if Runtime is running, not
Frontier.
3. Quit
Click on this button to exit the droplet without running
the embedded script.
For Your Users
1. To use your
droplet, they must have either Frontier or Frontier Runtime.
2. They must be
running System 7, since the drag-and-drop feature isnŐt available on earlier
versions of the Macintosh operating system.
3. They must
have a traps.OHIO table installed in their object database. Runtime comes with
traps.OHIO pre-installed, future versions of Frontier will too.
To develop your own droplet
1. Copy and
paste one of the sub-tables in the suites.droplet.tables table. Open it, and
modify the contents. Provide a Finder comment, version number, write some help
text, and of course fill in the script. HereŐs a screen shot of the table for
the Get File Info droplet:

2. To export the
droplet script and its related information, be sure that the table window from
step 1 is frontmost, and select the Export To AppÉ command from the Droplet
menu.
How droplet scripts work
You
might want to open up the script in the Get File Info table as an example
illustrating the general principles outlined here. HereŐs a screen shot of that
script:

This
script is simpler than most droplet scripts, but it illustrates the key points.
The
script is run once for every file, folder or disk thatŐs dragged onto the
dropletŐs icon. The first time the script runs, a boolean,
system.droplet.startup, is set true. This allows you to do any initialization
you might need to do.
The
name of the file you are being asked to process is in system.droplet.path. You
can use the file.isFolder verb to determine if it is a file or a folder, or use
file.isVolume to see if a disk icon has been dragged onto your droplet. From
there, you can do anything a Frontier script can do -- which is quite a lot!
After
all the dragged icons have been processed, your script is called one more time
with system.droplet.closedown set true and system.droplet.path set to the empty
string. You can clean up after your script, deleting any temporary files or
objects you created or closing windows or beeping the speakerÉ whatever.
After you are finished closing down, return.
Droplet 3.0.3 -- 7/27/94 dmb
Univeral Headers,
PowerPC
The source to the Droplet Master application can now
be built using AppleŐs Universal Headers under Symantec C/C++ 7.0 or Metrowerks
C/C++ 1.0 68K or PPC. This toolkit continues to use the 68K-only version of the
Master application, but if desired a native or Ňfat binaryÓ master could be
used. The performance of the droplet application itself it not thought to be a
significant factor in overall droplet performance.
Droplet 3.0
Supports
component menu sharing
All droplets created with this version will do their
menu sharing thru the component interface if Frontier 3.0 is running and the
Component Manager is installed.
Smarter exporting
Exporting got even smarter! Now it remembers the
folder you last exported your droplets to, and defaults to that folder. Saves
braincells for debugging.
ShipIt droplet
included in package
I think this is such a generally useful droplet, that
it should be included in the package. Drop a file or folder onto the ShipIt
icon to create a StuffIt archive of it in a fixed or shared folder. We use it
to get folders ready for uploading. But it would also be very useful in
publishing or service bureau applications. Or for moving stuff via Appletalk
Remote Access. Copy the droplet and give it a new name -- each copy has its own
settings -- so they can each create archives in a different folder.
SuperBoomerang
problem
We've uncovered a problem with SuperBoomerang and
component menu sharing. If you try choosing the Set Folder command from
ShipIt's Options menu, and you have SuperBoomerang installed, you'll probably
crash. The solution for now is to drag the SB Control Panel out of the Control
Panels folder, or don't choose that command from the Options menu in the ShipIt
droplet.
Edit causes the
app to quit
When you click on the Edit button in non-faceless
droplets, after the table opens in Frontier, the droplet application quits.
This makes it possible to re-export out to the same droplet, without getting a
file-is-busy error.
Droplet 2.1b3 -- 10/31/93 DW
Disabled buttons
Mike Alexander of Ann Arbor, MI writes on America
On-Line: "The code you use to disable a button in a dialog doesn't work
real well. For example, if you click on a disabled button, it hilights, but
doesn't do anything". Mike provided us with some C code, which we
integrated into droplet.c in the THINK C Source folder and it's part of the
master in the droplet suite. Thanks Mike!
Retained menubars
Before 2.1b3, if you ran a droplet that has a
menubar, and then ran a droplet that has no menubar, you'd see the old menubar
in the bar-less droplet. Added a little extra code to
system.verbs.traps.OHIO.init to fix this one.
Remembering
facelessness
On importing a droplet
from a file, we now look for string resource 129, if it's there, we set the
droplet's "faceless" boolean to true if the string contains
"faceless" otherwise we set faceless to false.
Droplet 2.1b2 -- 10/4/93 DW
Overzealous error
checking
2.1b1 would complain about a memory error on loading
a droplet that has no embedded menubar. An embedded menu isn't required, so
this message now only appears if it couldn't load the embedded script or
helptext.
Importing/exporting
honor embedded DLOG/DITLs
Isn't it a pain in the butt to have to go into a
resource editor if you want to convert a droplet with an embedded dialog from
one version of the Droplet Master to a new one? I thought so... On importing,
if there's a DLOG/DITL with ID 25000, we copy it into the droplet table. On
exporting, we write these two resources, if present, into the new droplet
application. Used this to test the Edit File Info droplet, included in this
release. It works...
When to use a
faceless dropletÉ
Don't go faceless unless you're sure that the user
consents to the service you're going to provide. If it's harmless (e.g.
displaying the number of files in a folder) or if you're the only user, there's
no danger in making it faceless [In the latter case, you know who to blame!]
But if you're doing a droplet for general distribution and especially if it
modifies or deletes files, please give the user a chance to try it out without
risking any of their data.
Droplet 2.1b1 -- 10/1/93 DW
Faceless droplets
If you include a boolean named "faceless"
in your droplet table and set its value to true, when the droplet runs, no
window opens. The droplet script runs immediately with no further user
interaction.
Running out of
memory
In previous versions if the droplet script was too
large to load into memory, the droplet would fail silently. In 2.1, if there's
an error loading a resource, a dialog box appears suggesting that you increase
the amount of memory used by the droplet. Also increased the default memory
allocation to 125K to make the error less likely.
One less step in
exporting
The Droplet Master program is now stored in the
droplet table, so you no longer have to manually create a copy of the program
and then save the droplet table to the copy. It's all done in one step in 2.1.
Droplet 2.0b9 -- 9/9/92 DW
Surprise!
Droplets get a lot betterÉ
Lots of changes detailed below. The net effect,
droplets are friendlier, more colorful and much more powerful things.
Window opens
before script runs
When you launch a droplet, a window opens that shows
the name of the droplet and the embedded help text. Three buttons allow you to
either run the droplet against the files you dragged and dropped, edit the
droplet script and menu bar, or quit the droplet application.
Note: as a result of this change, the role played by
your helptext has changed substantially. You should revisit your droplet and
reformat the text so it looks good in this new window.
For details, see ŇUsing a DropletÓ above.
Droplets support
menu sharing
You can now embed a menu bar in the droplet. The
droplet application will copy it into the right place in the object database
(usually system.menubars.DRPa). The commands in this menubar can be used to
configure the droplet. If you donŐt want a shared menu, donŐt include a menubar
object in your dropletŐs table.
Droplet suite
enhanced to support new features
It exports a menubar if one is present, and imports
one if it finds one in a file youŐre importing. The sample table was missing.
Some of the scripts were reorganized to make them more useful.
system.verbs.traps.OHIO
enhanced
Added the ŇeditÓ script, which imports from the
current droplet, and opens a window. Modified the readme wp text. We left
system.verbs.traps.OHIO in even though itŐs never called from a 2.0b9 droplet.
You may run an older version droplet.
Droplet 2.0b8 -- 9/3/92 DW
Error reporting
from droplet embedded scripts
If the script embedded in a droplet has a syntax or
runtime error or calls the built-in scriptError routine, the message is now
displayed in a dialog box by Droplet Master and all its progeny.
This should help in debugging droplets, and if
scriptError is used thoughtfully, help make them easier to use too.
New distinctive
icon for droplets
WeŐre getting serious feedback that the droplet icon
is hard to drop stuff onto because it has ŇdeadÓ areas. LetŐs try to tweak it
up so theyŐre easier to hit.

Along with this change, we changed the creator ID of
the Droplet Master program to ÔDPLaŐ. The one thing thatŐs certain in this
process, is that there will come a time when weŐll want to upgrade everyoneŐs
droplets without forcing them to run a time-consuming script. This leaves room
for 254 more versions of the Droplet Master program before having to recycle.
Should be good for about 50 years of upgrades, assuming 5 per year.
Droplet Suite
enhancements
Added droplet.convertFile script, Convert FolderÉ
menu command. Makes it easy to upgrade a whole folder of droplets. But you have
to manually move and DLOGs and DITLs that may be embedded in your droplet, or
any other resources not found in the Droplet Master program.
Droplet 2.0b7 -- 8/31/92 DW
No source
code/script changes
The Droplet Developer Kit has been added to Frontier
SDK 2.0 and itŐs version number has been bumped to 2.0 to be consistent with
the other components of the SDK.
Droplet 1.0b5 -- 8/19/92 DW
Auto-launch
Frontier or Runtime
When a 1.0b5 droplet starts up it checks to see if an
application whose creator id is ÔLANDŐ is running. If so, it goes ahead as
pre-b5 versions would.
To locate Frontier/Runtime, it searches the desktop
databases on all mounted volumes. If no program with creator id LAND is found,
it displays a dialog box, explaining what happened, and then quits. If one is
found, itŐs launched as the new frontmost app. The droplet waits for it to show
up in the process list. Then it sends Apple Events to the newly launched
Frontier or Runtime.
As usual the C source code is included in the THINK C
Source folder.
Frontier.isRuntime
was broken
A two-line script and it was wrong! Murphy strikes
again.
The mistake broke the system.verbs.traps.OHIO.help
script. If you 2clicked on your droplet on the desktop no window would zoom
explaining what the droplet was about. It worked fine for Runtime users, but
not for Frontier users.
ItŐs fixed in this release. To install the new
version, open the Frontier.isRuntime folder and 2click on the
Frontier.isRuntime desktop script.
Exporting tweak
In earlier releases, to export to the droplet app,
you had to have the table for the droplet as the frontmost window in Frontier.
That still works, but it also works if you have the suites.droplets.tables
table frontmost with the droplet table highlighted. Some people prefer it this
way.
Droplet 1.0b4 -- 7/24/92 DW
Changes for
Frontier Runtime
Droplets work fine with Runtime with one exception --
when you 2click on a droplet, Frontier displays a wptext window that explains
what the droplet does.
This wonŐt work if Runtime is running the droplet,
since it canŐt open a wptext window. Instead, we want Runtime to create a
TeachText file, move the text into the file and then open it with TeachText.
So, we made a change to all components of the Droplet
Developer Kit to support plain text viewing with TeachText:
1. In
the droplet suite, we export a TEXT resource, id 128 along with the wptx
resource. The text is derived from the wp object you created, so thereŐs no
need to change your table.
2. In
the Droplet Master app, when we send a ÔhelpŐ message to Frontier, we pass the
wptx and we pass the TEXT resource too. The Frontier weŐre talking to might be
Runtime.
3. In
system.verbs.traps.OHIO.help, we call Frontier.isRuntime to see where weŐre
running. If itŐs Runtime, we create a temporary TeachText file in the userŐs
Read Me Files folder, and launch it.
ThatŐs all that changed in 1.0b4.
Droplet 1.0b3 -- 6/6/92 DW
Droplet app sends
full path to the application file to scripts
I wanted to build a droplet that had its own dialog
embedded in it, and ran into a brick wall -- there was no way for the droplet
script to know where the droplet application is.
Now there is -- itŐs at system.droplet.appPath.
Changes were made to:
Droplet
Master -- when it sends the init event to Frontier it not only sends the
script as a parameter to the Apple Event, it also sends a string -- the full
path to the droplet application.
system.verbs.traps.OHIO.init -- receives
the path, and copies it into system.droplet.appPath. To use this new feature,
the user will have to have installed the new version of traps.OHIO. Play it
safe -- ship it with your droplet and tell the user to 2click on it, or do it
in your installer script.
Droplet Master is
a valid droplet
It now has a wptx and scpt resource, theyŐre very
small. It just seemed to make sense that the master should also be a small
droplet. I needed this for testing, it seemed prudent to leave it in the
release. It wonŐt make your droplets any larger, when you Export to App from
the Droplet menu, it will overwrite these placeholders. DonŐt worry. DW
Does your droplet
want a unique item?
According to John W. Baxter in message #3561 at GO
USERLAND on CompuServe:
ŇFor a droplet which really needs a unique icon,
include an icon family with the id -16455 and set the ŇHas Custom IconÓ bit in
the Finder information. ThatŐs the mechanism Finder uses when the user pastes
an icon into an applicationŐs Get Info box. And I just checked... doing this only changes the icon for
the particular droplet to which it is done.Ó
We thought weŐd pass that on. Thanks John W!
Droplet 1.0b2 -- 4/30/92 DW
Droplet suite can
import as well as export
Now when you download a droplet, you can see how it
works, modify it or customize it, and save it back out into the droplet
application. See suites.droplet.readme for details.
Full THINK C
Source included
We have included, for the first time, the THINK C
source for the Droplet Master program. You can see how droplet programs
communicate with Frontier using Apple Events. This project can serve as the
starting point for other Frontier related drag-and-drop projects. You may use
this source code in any project youŐre working on, but please maintain our
copyright notice at the head of the file, and let us know what you come up
with. Thanks!
Droplet 1.0b1 -- 4/18/92 DW
Changed program
ID to OHIO
I think I was having problems with the Desktop
Database, couldnŐt drag stuff onto the Droplet Master program. After staring at
all those resources for quite a while, I decided to try changing the creator ID
of the application to something different. We like four-character state names
as product codenames at UserLand, so I set it to the next-available one: OHIO
and rebuilt the whole thing. Now I can drag stuff onto the DM icon. So off we
go!