Frontier SDK

A collection of toolkits, sample programs, C source code and documentation.

UserLand Software to help C and Pascal developers work with the interapplication communication capabilities of the Macintosh operating system and to take advantage of scripting software such as UserLand Frontier and Apple's AppleScript.

Included are libraries and sample programs that show you how to:

• Support the menu sharing protocol; (Menu Sharing Toolkit)

• Add scriptable Apple Events to an existing application; (IAC Tools)

• Create a new application with IAC capabilities; (Applet Toolkit)

• Write a drag-and-drop script, or "droplet"; (Droplet Developer Kit)

• Send an IAC message to Frontier to run a short script. (Frontier Do-Script)

• Write a code extension to run in Frontier; (XCMDS & UCMDS)

• Exchange outline-structured lists between applications. (Outline Sharing Toolkit)

UserLand Software distributes Frontier SDK at no charge, with no royalty or license fee. The package includes full C source code to all libraries and sample programs.

If you've found Apple Events confusing or if it looks like too much work, we encourage you to explore the code in Frontier SDK. Perhaps it will clear up the confusion, or make IAC more approachable. Even if you don't use any of the source code in your development work, it can serve as a collection of solved problems that may fit into your development work at some time in the future.

SDK stands for Software Developer's Kit.

This document provides an overview of how all the components of Frontier SDK tie together.

This is the second beta release of Frontier SDK 4.0. All projects have been converted to Metrowerks C. The Applet Toolkit has been extended to include a complete set of file system and desktop operations. MacBird Runtime support is included in the Applet Toolkit.

Downloading

You can download Frontier SDK 4.0b2 from ftp.scripting.com:

ftp://ftp.scripting.com/userland/sdk4.0b2.sit.hqx

If you have any questions, comments or suggestions, please post them on the Frontier-talk mailing list. Thanks!

All software on this site is subject to our License Agreement which restricts distribution and limits our liability. Please read it before downloading any software from this site. Thanks!

Requires MetroWerks C 7, Frontier 4.0 or greater, System 7.0

Frontier SDK 4.0 requires Macintosh System 7.0 or greater, since it builds on the Apple Event Manager.

All the toolkits and sample code are provided in a form compatible with Metrowerks C, release 7 or greater.

Frontier 4.0 or greater is required for testing with all the toolkits except IAC Tools. The latest release of Frontier is version 4.2.3 shipped on 4/20/97; 5:33:58 PM.

If you include this code in your product, the features it supports will only be functional on Macintoshes running System 7.0 or greater. Some toolkits require or take advantage of the Macintosh Component Manager, available in System 7.1 or with QuickTime.

No License Fee or Royalty

There is no license fee or royalty due on the use of any of the code in Frontier SDK. You may convert the code to run in other development environments. You may include the code in any shipping product. You may modify the code to fix bugs or extend its capabilities.

However, you must maintain our copyright notice on each file you use. You may not distribute modified versions of any of these programs in source or executable form without the written permission of UserLand Software. The intent behind this restriction is to maintain standards, not in any way to limit the ways this code can be used.

Testing & Refinement

If you follow the examples and documentation in Frontier SDK your product should work for Frontier script writers. But the ultimate test of compatibility will be trying out your interapplication capabilities using Frontier.

Add wires to your program thoughtfully. Think about scripts that people will want to write to customize and automate your software. Keep your scripting interface as simple as possible.

Most important: become a script writer yourself. It's like anything else in software, if you don't use it, it won't be right.

Frontier Install Files

When you're satisfied with your scripting interface, export a Frontier install file and make it available for script writers, either by including it with your software, or uploading it to one of UserLand's on-line services.

We've included an install file for each of the sample applications in the SDK. When you double-click on these files, Frontier copies resources from the file into the Frontier.root object database file. Each install file contains a table of glue scripts and a shared menu bar.

It's very easy to create a Frontier install file. See the Frontier Install File Creator folder in the Extras folder, for step-by-step instructions on creating a Frontier install file for your application.

Menu Sharing Toolkit

Menu Sharing allows Frontier script writers to add menus and sub-menus that run scripts to your application's menu bar.

Most of the sample programs included in Frontier SDK also support menu sharing; MenuSharer is the simplest sample app.

Important: In Frontier SDK 3.0, there is a small change to the API and a dramatic boost in performance and menu sharing is more transparent to script users. If you are using the 2.0 Menu Sharing Toolkit, please refer to the Change Notes section in the Menu Sharing Toolkit readme file about upgrading to 3.0. Don't worry, it's easy!

IAC Tools

The C source files in this folder provide a simplified API for sending and receiving Apple Events. A lot of the power of the Apple Event Manager is hidden by this API. But we've found that many applications of IAC don't require all the power of the Apple Event Manager.

Many of the libraries in Frontier SDK build on IAC Tools.

Applet Toolkit

The Applet Toolkit makes it simple to build new double-clickable Macintosh applications that have strong support for Apple Events and menu sharing.

If you're developing a new application specifically to be integrated with other software, the Applet Toolkit is perfect. UserLand's DocServer application is implemented using the Applet Toolkit, as are new utilities in development at UserLand. Two sample applications are provided. Minimal Applet is a simple multi-window text editor, BarChart is a color charting program.

Because the Applet Toolkit is an application framework, certain Apple Event messages can be sent to all programs based on the Applet Toolkit. Examples are app.openWindow, app.getText and app.setFont. For a complete list, jump to system.verbs.builtins.app in Frontier.root. These verbs are also documented in DocServer.

UCMDs & XCMDs

Frontier supports two kinds of code extensions: UCMDs and XCMDs.

In both models, you use a C or Pascal compiler to create a code resource, and then copy the code resource into Frontier's object database. Once the code is in the database, your scripts can call them, send parameters, and receive returned values, just as if they were verbs built into the UserTalk language.

XCMDs are HyperCard 1.0-compatible code extensions. UCMDs are compiled Apple Event handlers. Each approach has advantages. See the readme file in the UCMDS & XCMDS folder for details.

Included in the UCMDs & XCMDs folder are 4 sample XCMDs and 3 sample UCMDs.

Outline Sharing Toolkit

Outline sharing allows programs to exchange lists and lists-of-lists as part of Apple Event messages. Hierarchic lists come up all the time when designing software. Until outline sharing there was no standard way for applications to easily communicate and manage large hierarchic structures.

The Outline Sharing Toolkit also suggests how to approach toolkits for other data types that can be transported using the Apple Events protocol.

OutlineSharer is the sample application for outline sharing. UserLand's Bullet application, a color outline browser, builds on the Outline Sharing Toolkit. It's available as a separate download.

MenuSharer Program

This demo application shows you how to add menu sharing to your application. It's the reference app for the the tutorial in the Menu Sharing Toolkit folder. MenuSharer also illustrates how to add Apple Event handlers to your application.

BarChart

This is a simple demo application for the Applet Toolkit. It doesn't implement as many of the callbacks as Minimal Applet. It's different in that it uses color, and it's a graphics application, and therefore implements some of the callbacks that aren't implemented in Minimal Applet.

Minimal Applet

This is the main demo application for the Applet Toolkit. It's a multi-window TextEdit-based editor. It is also used as an example in the RFrontier Install File CreatorS sub-folder in the Extras folder.

Apple Events 101

Basic introduction to Apple Events programming using Think C. Two sample programs in source code: Client and Server. Client sends a series of Apple Events to Server. They are minimal programs, makes it easy to see how the Apple Events work.

OutlineSharer

This is a demo application for the Outline Sharing Toolkit. It implements four outline-related Apple Events. A Frontier install file is provided for OutlineSharer. In the OutlineSharer.examples table there are several scripts which test out the Apple Events implemented in OutlineSharer.

Trig

This is a demo application for use of the IAC Tools library and system event handlers.

Frontier Do-Script

This is the simplest of the sample programs. It implements a routine called FrontierDoScript that shoots an IAC message at Frontier asking it to run a short script, and returns a string representation of the value of the script.

This program does not use the IAC Tools library. For a version of FrontierDoScript that builds on top of the IAC Tools library, check out appletfrontier.c in the Applet Toolkit folder.

New in Frontier 3.0 -- we include sample code that shows how to drive Frontier using the new Macintosh Component Manager, available in System 7.1 or QuickTime. It's much faster than the Apple Event method.

Customizing Think C...

A case study in customizing Think C with Frontier scripts. It takes you thru the development process of a single script, starting with a first proof-of-concept version, all the way to a very useful and complete script that saves us time every day.

Frontier Install File Creator

You've added Apple Event support to your application. You've installed the Menu Sharing Toolkit. You're almost ready to ship.

But how are script writers going to learn about your Apple Event support?

This document is part cookbook, part style guide. If you follow it carefully, Frontier script writers will love you.

Droplet Developer Kit

The Droplet Developer Kit includes all the scripts and docs you need to create your own droplets PP 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. It's small, theyUre easy to write, and lots of fun to run.

addCopyright script

We needed a script that adds a copyright notice at the top of each file in a folder structure filled with Think C source code files. Since it is a very small script and seems generally useful to developers who are script writers, we included it in the SDK package.

List of SDK Files folder

This folder contains a script that builds a Frontier outline of the folder structure of the Frontier SDK folder. It can be very useful for gaining an overview of the organization of the toolkits, sample code and extras.

Quick Small Backup folder

Over time, I've evolved this script that conveniently backs up a Think C source code project. I put a copy of this script in each source code folder. Whenever I want a quick, small backup, I run this script. It requires a little setup. You need StuffIt 3.0 to get compressed archives. The payoff is easy backups with low cost in disk space. See the readme file in this folder for more info. DW

Who Should Use What?

If you're adding Apple Event support to an already-existing application, check out the IAC Tools folder. You may find that the examples in iac.c make the lightbulb go off about the Apple Event Manager.

If you already have Apple Event support, please create a Frontier install file for your application. Install files are a by-product of testing your IAC wires with Frontier. It's a simple process to create your install file. Check out Frontier Install File Creator in the Extras folder.

Menu Sharing is very low overhead and easy to implement; and your users and script writers will appreciate it.

If you're writing a new application, consider using the Applet Toolkit. It factors out of a lot of the common code that all multi-window Macintosh applications must implement. And it gives you menu sharing with Frontier for free. And it implements a set of Apple Event messages automatically, and makes it easy for you to add more.

New Stuff

We're working on new versions of SDK pieces, as they come out I'll link them into this page.

• Menu Sharing Toolkit 4.1 -- A new version of our most popular toolkit.

• How to Create Frontier Install Files -- walks you thru the process of creating a Frontier install file for your app.

• Outline Sharing Toolkit -- makes it possible to write fast C code that does special processing of Frontier outlines.

• MacBird Plug-ins -- MacBird, which is part of Frontier 4.1, is a UI designer and runtime for colorful "cards" containing Frontier scripts. Even better, it's got a plug-in architecture for new object types. This page tells you how to do it.

---

© Copyright 1996-97 UserLand Software. This page was last built on 5/7/97; 1:35:42 PM. It was originally posted on 6/1/96; 6:21:13 PM. Internet service provided by Conxion.