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[1].

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!

 



[1]In version 2.1, droplets can be faceless. See change notes for version 2.1b1, below, for details.