Most developers are quick to realize that a Macintosh file, whether application or not, could easily be an advertisement for Double Mint Gum. Yes, its two, two, two files in one. As Inside Macintosh is quick to point out, Every file has a resource fork and a data fork (either of which may be empty). The resource fork of an application contains not only the resources used by the application but also the application code itself. The data fork of an application can contain anything an application wants to store there. Big deal. Even most novices know that when an application creates a document, it places the data into the data fork of a file. Pretty basic stuff, even a bit dull and boring for most MacTutor readers.

But lets step beyond the obvious for a moment, and concentrate on the quote can contain anything an application wants to store there. If we can put anything in there, how about data that only the application could access. No reading in other files, but just operating on the information found within its data fork. Think of it as a stand alone document. Perhaps a word processor that generates a file when double clicked will run itself. Or a chart program that makes files you could modem to a business associate without him needing the creator application. Something a little like Glue, where you have the ability to view an applications output without needing the application. Runtime versions of data bases incorporate these features. Even Microsoft is rumored to be considering a version of Excel that will create stand alone spreadsheets.

Pretty neat stuff, but probably too tricky for the average programmer, right? Wrong. The secret lies within effectively using the resource and data forks.

Stand Alone Document Theory

The reasons for developing such stand alone documents are quite obvious; the ability to disseminate information without the need of a mother application to access it; being able to address larger audiences with your output since not everyone needs the creator; not needing sophisticated knowledge of an application to use the information found in a document. All of these points and more make it worthwhile to consider incorporating the ability to generate stand alone documents in your applications.

In thinking about such a project, there are several things to consider. The first is the functionality you want the document to have. More than likely youre not going to want the stand alone file to do everything the original application does. Therefore, youll need to include some secondary code that will simply display, scroll, print, or do whatever.

But where does one put the code and resources actually needed to run the document? If there is one set of CODE resources that run the main application and another set that will run the stand alone document, wont they conflict and cause problems? Two theories can be used in developing stand alone document generators. The first espouses putting all the required resources into a template file. The generator then simply copies the template, gives the copied file a new name, and inserts the desired information into the data fork. This is the technique used in the stand alone text generator Take A Letter. The second method is cleaner, eliminating the need for template files. The generator program actually contains the code needed to run a stand alone document, although it may masquerade as another resource. The generator creates a new file, copies in the resources, renames them, fills the data fork, and sets the files attributes to be an application.

Stand Alone Document Practice

Enough theory, and on to the practice. What will be demonstrated is how to construct a stand alone document generator that works with MacPaint format documents. Three sources are included here. The first (PaintDisplay.c) is code for a program that loads a Paint file stored in its data fork and then shows the upper left hard corner of the bit mapped image. The second listing (PostCard.c) is for an application called PostCard that builds a stand alone Paint document. (The code from PaintDisplay will be inserted into this document generator.) And finally, PostCard.r is the RMaker file. Although the sources are in Lightspeed C, the techniques should be general enough to apply to a different variation of C or even another language. (Lightspeed info: Both projects (PaintDisplay proj and PostCard proj) should include MacTraps plus their own respective source files and be set to build applications. PostCards creator type should be PCRD.)

The first step is to compile PaintDisplay.c. This source contains a standard algorithm for displaying an image from a MacPaint format file. It initializes everything, opens up its data fork, grabs bytes, puts up a window, displays the left corner of the Paint document, and waits for a mouse click to quit. All in one breath. Dont try to run it quite yet though. If you do, it will be looking in its own data fork for something that isnt there yet, and your curiosity will be rewarded with a bomb.

The only real item in the code that needs discussing, is how one goes about accessing the data fork. To quote from the source:

The first step is to determine what volume the application is on with a GetVol() call. Next, use GetAppParms() to return the name of the current application. Now pass the applications name and the volume reference number to FSOpen(). It will oblige by opening up your applications data fork.

Resource Rascality

Once youve compiled PaintDisplay, the next task is to use RMaker on the PostCard.r file. This file contains the resources for the menus, dialogs, bundles, icons, etc. for the PostCard application. It also has the necessary resources to be used in creating the stand alone document.

An often overlooked feature of RMaker is the ability to copy specific resources from one file to another during the compile stage. By using the .R command you could load, lets say, a font from an existing file into the resource file youre currently compiling. The format is:

Type FONT = GNRL* the new resource type (FONT)
,8 * the new resource ID
.R * the RMaker directive
Fonts FONT 12 * the file Fonts and the resource
* (FONT 12) to copy into the new resource

RMaker is pretty lax as to letting you get away with things in certain areas. This feature proves beneficial when building program generating applications. As mentioned before, the biggest problem in writing an application that builds another, is where to stick the code that will be spawned off. Obviously you cant have a program with two CODE 0 resources, at least without the potential for serious problems.

The solution is to build a new resource type of your choosing, and then through RMaker, stuff the CODE into it. For example:

This is whats happening in PostCard.r. The previously compiled code from PaintDisplay is being read in, and then assigned a new type and identification. The CODE resource is still the same, but its gone into hiding by changing its name. Its as easy as that. When the resource file is compiled, youll have your CODE just sitting there, ready to use, but disguised as something else that wont conflict with the the program that will be using it to create another application.

Taking a peek with ResEdit at the results. FAKE and DUMY are really code resources, but with their new identities, dont conflict with code resources found in the application that will use them.

Two words of advice on using RMaker in such a fashion. The first is, RMaker frowns on using a source file with a space in its name. Therefore, My File will cause you problems but MyFile will not. The second caveat is to be aware of path names. If all of your formats look all right, but RMaker still is complaining, odds are you have an improperly laid out path. Double check it.

Youll notice in the PostCard.r file, more than just CODE resources are being changed. Remember, all compilers are not created equal. Some will generate just two code segments (for under 32k of code, of course): 0 - the jump table, and 1 - the actual code . Others, Lightspeed C for example, will generate more than two code segments and a variety of other resource types where data is stored. Thats what all the CRELs, DATAs, ZEROs, etc. are all about. When you are transferring and converting code resources, be sure you get everything your particular compiler needs for the application to run. At first put everything in, but after a while try some experimenting. At times youll find you dont need all of the data and support resources.

Resource Moving Without ResEdit

The last step in the process is to compile PostCard.c. The compiled resources from PostCard proj.Rsrc are copied in, and the application is ready to run.

From the Macintoshs perspective, heres what happens when the user selects Make a PostCard... from the menu:

The SFPut() routine is called to select a name and location for the new file. CreateResFile() is used to create the named file. Finder attributes are then set, and the resource fork of the new file is opened.

Now the fun stuff. The code determines what the resource reference number of the current application is (in this case PostCard). It then makes use of a programmer defined function called ResTransfer().

ResTransfer() is passed the resource type and ID of the resource to be copied, along with what type of resource and what ID number you want the copy to appear as. GetResource() is used to get a handle to the resource to be copied. UseResFile() is then called with the resource reference file number of the application that will be created. This tells the resource manager to only deal with the resource fork of the new stand alone document.

As per Inside Macintosh, the resource to be copied is detached, and then added to the new application with AddResource(). AddResource() is passed the handle to the resource, along with information concerning type and identification. If for some reason it cant be added, an error handling routine is alerted.

ResTransfer() is called repeatedly for all of the resources needed to be placed in the stand alone document. At first BNDL, FREF, ICN#, etc. are moved in, giving the application its own unique type and icon. Next the FAKE and DUMY resources are copied and then converted back to their original types and IDs.

Once all the resources have been moved and/or changed, UpdateResFile() is used to tell the resource manager the new file needs updating, effectively adding and writing all of the resources. The stand alone documents resource fork is then closed, and UseResFile() is called to revert the current resource fork back to PostCard.

With the resources in place, SFGet() is called to select the Paint format file to be read in. Its data fork is read and then written to the stand alone documents data fork. With no errors reported, the stand alone document has now been created and is ready to run!

Final Thoughts

Needless to say, PostCard aint very fancy. If one was to do it right, scrolling, desk accessory support, more error handling, perhaps even printing and the ability to save a full MacPaint format document out of it should be included in the PaintDisplay code. Did I just hear the basis for a shareware product?

Also keep in mind that PostCard just demonstrates the idea of stand alone documents. Although application generators like it are useful, stand alone documents would really be best created by say a WriteNow or SuperPaint. Ideally, the entire process would be incorporated as a function in an actual, full blown program where the user would simply select a menu item to create the stand alone file.

One potential argument to the idea of stand alone documents is more code overhead in the original program. However, with a little thought and planning this can easily be avoided by segmenting the program so the main application and the one to be generated would share some common code. Even if an extra 15 or 20k went into the final product, users would likely justify the size increase because of the benefits.

As you can see, creating stand alone documents isnt that difficult. The problems with data and resources can easily be overcome, with the end result being things like self running documentation, double clickable desktop presentations, or stand alone spreadsheets. Hopefully in the near future well be seeing more of stand alone documents. But for now, why dont you give your own a try.

Software Updates via MacUpdate

Microsoft Office 2016 16.11 - Popular pr...

Microsoft Office 2016 - Unmistakably Office, designed for Mac.
The new versions of Word, Excel, PowerPoint, Outlook, and OneNote provide the best of both worlds for Mac users - the familiar Office... Read more

Adobe Photoshop CC 2018 19.1.2 - Profess...

Photoshop CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Photoshop customer).
Adobe Photoshop CC 2018, the industry standard... Read more

Adobe Dreamweaver CC 2018 18.1.0.10155 -...

Dreamweaver CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Dreamweaver customer).
Adobe Dreamweaver CC 2018 allows you to... Read more

Adobe Flash Player 29.0.0.113 - Plug-in...

Adobe Flash Player is a cross-platform, browser-based application runtime that provides uncompromised viewing of expressive applications, content, and videos across browsers and operating systems.... Read more

Drive Genius 5.2.0 - $79.00

Drive Genius features a comprehensive Malware Scan. Automate your malware protection. Protect your investment from any threat. The Malware Scan is part of the automated DrivePulse utility. DrivePulse... Read more

MegaSeg 6.0.6 - Professional DJ and radi...

MegaSeg is a complete solution for pro audio/video DJ mixing, radio automation, and music scheduling with rock-solid performance and an easy-to-use design. Mix with visual waveforms and Magic... Read more

ffWorks 1.0.7 - Convert multimedia files...

ffWorks (was iFFmpeg), focused on simplicity, brings a fresh approach to the use of FFmpeg, allowing you to create ultra-high-quality movies without the need to write a single line of code on the... Read more

Dash 4.1.5 - Instant search and offline...

Dash is an API documentation browser and code snippet manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more

Evernote 7.0.3 - Create searchable notes...

Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more

jAlbum Pro 15.3 - Organize your digital...

jAlbum Pro has all the features you love in jAlbum, but comes with a commercial license. You can create gorgeous custom photo galleries for the Web without writing a line of code!
Beginner-friendly... Read more

Latest Forum Discussions

Around the Empire: What have you missed...

Oh hi nice reader, and thanks for popping in to check out our weekly round-up of all the stuff that you might have missed across the Steel Media network. Yeah, that's right, it's a big ol' network. Obviously 148Apps is the best, but there are some... | Read more »

All the best games on sale for iPhone an...

It might not have been the greatest week for new releases on the App Store, but don't let that get you down, because there are some truly incredible games on sale for iPhone and iPad right now. Seriously, you could buy anything on this list and I... | Read more »

Everything You Need to Know About The Fo...

In just over a week, Epic Games has made a flurry of announcements. First, they revealed that Fortnite—their ultra-popular PUBG competitor—is coming to mobile. This was followed by brief sign-up period for interested beta testers before sending out... | Read more »

The best games that came out for iPhone...

It's not been the best week for games on the App Store. There are a few decent ones here and there, but nothing that's really going to make you throw down what you're doing and run to the nearest WiFi hotspot in order to download it. That's not to... | Read more »

Death Coming (Games)

Death Coming 1.1.1.536
Device: iOS Universal
Category: Games
Price: $1.99, Version: 1.1.1.536 (iTunes)
Description:
--- Background Story ---You Died. Pure and simple, but death was not the end. You have become an agent of Death: a... | Read more »

Hints, tips, and tricks for Empires and...

Empires and Puzzles is a slick match-stuff RPG that mixes in a bunch of city-building aspects to keep things fresh. And it's currently the Game of the Day over on the App Store. So, if you're picking it up for the first time today, we thought it'd... | Read more »

What You Need to Know About Sam Barlow’s...

Sam Barlow’s follow up to Her Story is #WarGames, an interactive video series that reimagines the 1983 film WarGames in a more present day context. It’s not exactly a game, but it’s definitely still interesting. Here are the top things you should... | Read more »

Pixel Plex Guide - How to Build Better T...

Pixel Plex is the latest city builder that has come to the App Store, and it takes a pretty different tact than the ones that came before it. Instead of being in charge of your own city by yourself, you have to work together with other players to... | Read more »

Fortnite Will Be Better Than PUBG on Mob...

Before last week, if you asked me which game I prefer between Fortnite Battle Royale and PlayerUnknown’s Battlegrounds (PUBG), I’d choose the latter just about 100% of the time. Now that we know that both games are primed to hit our mobile screens... | Read more »

Apple is now offering Certified Refurbished 2017 10″ and 12″ iPad Pros for $100-$190 off MSRP, depending on the model. An Apple one-year warranty is included with each model, and shipping is free:
–... Read more

Silver 12″ 1.3GHz MacBook on sale at B&H...

B&H Photo has the 2017 12″ 1.3GHz Silver MacBook on sale for $1399.99 including free shipping plus sales tax for NY & NJ residents only. Their price is $200 off MSRP, and it’s the lowest... Read more

MacTech is a registered trademark of Xplain Corporation. Xplain, "The journal of Apple technology", Apple Expo, Explain It, MacDev, MacDev-1, THINK Reference, NetProfessional, Apple Expo, MacTech Central, MacTech Domains, MacNews, MacForge, and the MacTutorMan are trademarks or service marks of Xplain Corporation. Sprocket is a registered trademark of eSprocket Corporation. Other trademarks and copyrights appearing in this printing or software remain the property of their respective holders. Not responsible for typographical errors.

All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.