Fun with FileIO
May 12, 1999
by Fred Bals
Fred & The Electric Gold-Fish Bowl
More than a few years ago I was sitting with a client reviewing the prototype of an animation loop we had created for their COMDEX trade show booth. The loop displayed a classic `65 Shelby-Cobra GT350 zooming on-screen, then screaming off with a screech of tires as a notebook PC followed in the same fashion. The idea being, of course, that the PC they were introducing was faster than anything then known. I think it had all of a 75 MHz processor.
"Nice," said my client as he watched the loop. "You know, we're bringing a replica of one of those cars to our booth and giving it away. It's worth over 30 grand."
"Wow," I said. "How are you to give it away?"
"Oh, probably the usual gold-fish bowl," he answered.
Not knowing much about trade shows at the time, I had to have him explain that they were going to choose the feedback forms of four people per day over the course of the show. On the last day, the 12 lucky people would have their names dropped into a goldfish bowl. A name would be pulled from the bowl, and they'd have their winner.
I chewed on that for a day or so, then called my client. "Given that this is such a major promotion you want to make as big as splash as you can," I said. "I think we should come up with something that ties into the notebook introduction and is more exciting than a gold-fish bowl."
And we did. I had my development team create another animation (this was so long ago we were doing it in 3.1 on the Mac, porting it over to Windows 3.0, and running it through the Director Player for Windows). This movie had the Shelby zooming on to the screen too, but then it waited there, faintly trembling, with the rumble of its engine throbbing in the background. There was a large on-screen button, based on the Cobra logo, displayed under the car.
"So here we are," I told the client as I showed it to him on one of their new notebook systems. "It's the last day of the show, and your finalists are ready to go." I brought out a helmet we had purchased and offered it to him. "Pick a disk."
We had created special disk labels for twelve 3.5-inch floppies, displaying the Cobra logo. The disks were identical. The client chose a disk from the helmet, and I distributed some of the disks to other people in the room.
"Try it," I said.
One after another, they inserted their disks into the notebook's floppy drive and clicked on the Cobra button. The first few players heard the car's rumble grow into a thunderous roar as it seemed to prepare to leap from the screen. But at the last moment the car began to shake like an ill-fed dog, the engine noise expired with a sickly wheeze, and the word, "Sorry" appeared on the screen. A few moments later, the screen reverted back to the original animation sequence, and the next person would try.
I had reserved one of the disks for myself, and after allowing a few people to go ahead I said, "I'll try now." Again the car's engine roared, but this time it screamed off the screen, leaving a blazing trail behind, which formed the words, "You win!"
The client loved it, we ran it for real at COMDEX, and the crowd loved it, especially the person who won the Shelby-Cobra replica. In fact, the promotion was so successful that the client purchased more replica cars and we ended up doing it four more times over the course of two years. I ended up traveling from Vegas to Chicago to Atlanta and New York, and learned more about trade shows than I ever wanted to know. And we did it all thanks to FileIO.
Talking `Bout My FileIO
If you're familiar with FileIO, you probably already figured out what we did. It did take a conceptual leap on my part to realize that a text file could be read in from anywhere that FileIO could access -- including a floppy drive. But once I grasped that, the rest was a stroll in the park.
While I seem to use Buddy API and AlphaMania for every project these days, the venerable FileIO still remains my favorite Xtra. Let's look at the basics of my Shelby-Cobra Give-Away program. Then for those who haven't used FileIO before, I'll give a brief overview of its capabilities. Finally, I want to talk about some different ways you can put FileIO to use, possibly in ways that will be a surprise to you.
As I've said, the Lingo for the Shelby-Cobra program was very basic. Essentially, there was a "go to the frame" after the opening animation. Upon the user's click on the "Cobra button" , the program executed the following code (Note that I've amended the old FileIO XObject code for the current FileIO Xtra) ...
on mouseUp
set fileXtra = new(xtra "FileIO")
openFile(fileXtra, "a:\getme.txt",1)
set readInText = readFile(fileXtra)
closeFile(fileXtra)
if readInText = "xyz" then
go to frame "winner"
else
go to frame "loser"
end if
end
Since we were responsible for the give-away of a substantial prize, we added various checking and failure Lingo to make the program as bulletproof as possible, but that's the heart of the code.
For those not familiar with FileIO, Line 1 instantiates the Xtra, Line 2 opens a text file located on the system's "A:" drive. The "1" parameter following the "a:\getme.txt" string tells FileIO to open the file in "read-only" mode (valid modes are 0 = read/write, 1 = read, and 2 = write).
Line 3 reads the contents of the text file into a variable called, "readInText." Line 4 closes the Xtra (always an important step to remember when using FileIO). The "if" statement compares the content of readInText with a defined string. If readInText equals that string then we have our winner.
One of the many things I enjoy about working with Director is figuring out how to apply solutions like this to different projects. We took the same concept and created a slot machine game for another client's trade show booth at yet another COMDEX (held appropriately in Las Vegas). Booth visitors went to various PCs, stuck in a floppy that had been given to them at the start of their tour and, dependent upon the results displayed by our on-screen Jackpot machine, could win hats, T-shirts, or a $3,000 PC system. Of course, the underlying reason for the Jackpot Tour was to expose potential customers to as many marketing messages as we could jam in.
We even used FileIO to write and read text files from as many as 10 separate Director projectors running on different PCs over a LAN. Based on the information they read in, the Director movies would display various images or text information. For example, in a "game show" program that we created, contestants would "buzz in" by clicking an on-screen button displayed on their PC. The program wrote out a file, which was read in by another Director movie on another system, which displayed the name of the first contestant to have successfully buzzed in.
FileIO-The Basics
For an in-depth look at using FileIO, I commend Bruce Epstein's invaluable books, "Lingo in a Nutshell" and "Director in a Nutshell", to your attention. If you haven't bought them, follow the links and buy them now. I've deliberately focused this article on interesting things you can do with FileIO rather than repeat information that can be found easily in those two books and elsewhere. But, here's a very brief overview of FileIO for those who have never used it.
In essence, FileIO is used in Director to read and write text files. I suspect the original FileIO XObject was created by Macromedia (known in those days of yore as "MacroMind") primarily to save and retrieve game information in Director movies. This, obviously, is a significant need in a tool that was being marketed as the ultimate for game creation, since users need the capability to pick up a new game session at the point where they left off, to display high scores, and so on. But until Director 4, there was no "saveMovie" command that allowed changes in movies to be retained over multiple sessions.
Even so, this command doesn't work with protected movies. FileIO was, and in many cases, still is the best option if you need to save dynamic information in Director movies. Games as different as "The Journeyman Project" and "Total Distortion" used the FileIO strategy in order to save out and read in player preferences, and to track the player's progress through the game.
FileIO has been bundled with Director almost as long as there's been a Director. If you're using Director 6, you should be using Version 1.0.3 of the Xtra, which came as part of the Director 6 install CD. If you're one of those hardy souls braving Director 7, you're using FileIO for Director 7.0.0.r198 (Dec 1 1998). You can check the version of the Xtra through the Message window with the command:
put version (xtra "FileIO")
As usual with Macromedia, the documentation for FileIO could charitably be described as "sketchy" and again I recommend third-party books such as Bruce Epstein's "Nutshell" duo for better documentation. But if you want to see what Macromedia has to say about FileIO, then use the command:
put mMessagelist (xtra "FileIO")
in the Message window and a list of the FileIO commands will display. You can create, delete, open, close, write to, and read from text files, including complete content or specific characters, words, lines, or strings. You can display a dialogue box so the user can choose a specific file. And you can do such tricky things as only allowing certain file types to display in the dialogue box, such as .DXR, .DCR or .DIR files.
Using FileIO to Create a "Smart Stub" Projector
Since I've said that FileIO's raison d'être is to read and write text files, why would you want to use it to create a dialogue box that would only display available Director movies? One reason would be to create a so-called "stub" projector; that is, a Director executable used for the specific purpose of launching another movie.
Basic stubs are created with the "go to movie <blah>" command usually hard-coded in with a specific movie's name. Another strategy is use Director's dreaded "Where is ..." dialogue through a "go to movie 'the movie you want to open'" command, which will cause a dialogue reading, "Where is the movie you want to open?" to display . But FileIO gives you the capability of creating a "smart stub" that allows the user to decide what movie s/he wants to open without always seeing that nagging message.
Let's look at how we'd set this up for Shockwave. We need to create some code that will tell FileIO we want the user to only see DCRs when a dialogue is displayed:
on onlyShock thisInstance -- limit the file dialog display to just Shockwave files set fileType = "Shockwave Movie,*.DCR" setFilterMask(thisInstance,fileType) end
Then we create a button and add this code to its script:
on mouseUp
global myFile
onlyShock(myFile)
set fileChoice = displayOpen(myFile)
if fileChoice > "" then
put fileChoice into field "File Path"
saveMovie
go to movie fileChoice
end if
end
Working down through the code, Line 2 calls the onlyShock routine, which says we only want Shockwave files to display using the setFilterMask command. Line 3 creates a variable called fileChoice, and uses the FileIO command displayOpen to open the dialogue. The user picks a DCR (or, if not, nothing is returned), and that selection is stored in the fileChoice variable. Line 5 puts the contents of fileChoice into a field called "File Path." Line 6 saves the changed movie. Line 7 instructs the movie to go to the DCR named in fileChoice.
We've now created the code for a "stub" projector. However, rather than a basic stub, with the ability to only go to a specific movie, or an annoying stub that nags the user to find a movie each time it's launched, our "smart stub" can store user selections. If we and added this Lingo to a startMovie handler ...
on startMovie
if not the shiftDown then
put line 1 of field "File Path" into defaultFile
go to movie defaultFile
exit
else
go to "setup"
end if
end
... we'd have a complete "smart stub" projector. Our smart stub will automatically go to the file named in the field "File Path" or, if the user holds the Shift Key down when launching the smart stub, will display a frame where the user can select and store a new movie to launch. With slight amendments to the code, the smart stub could be used to launch DIRs or DXRs as well as Shocked DCR movies.
Using FileIO to Control a Movie
As I mentioned earlier my company, Quantic Communications, has used FileIO in Director movies for such varied things as trade-show drawings and games. In most cases, however, our work was limited to using FileIO for comparison purposes (if the readInText = "this string", then doSomething) or simply to display things such as player names, scores, and results. However, combined with the Lingo "do" command, FileIO can become a much more powerful tool capable of modifying or updating Director movies on the fly.
The "do" command allows you to execute Lingo commands stored as strings. For example, use a text editor such as Notepad or SimpleText to create a text file containing these two lines:
set the stageColor to 255 alert "This is an alert"
Save the file as "alert.txt". Create a Director movie with the following code in a button or startMovie handler:
set fileXtra = new(xtra "FileIO") openFile(fileXtra, the pathName & "alert.txt",1) set readInText = readFile(fileXtra) closeFile(fileXtra) do (readInText)
As you can see, the Lingo contained in the text file is executed through the "do" command.
Although this is a trivial example, the potential of the "do" command is as limitless as Lingo itself. Any command or group of commands can be executed through a "do" statement, and any of those commands can be external to the Director movie and read in as necessary with FileIO, or, for that matter, through getNetText if the file is stored on the Internet.
A detailed discussion of the potential of the "do" command combined with FileIO, getNetText, or Shockwave's "externalEvent" command is outside the scope of this article. For those intrigued by the idea, I recommend Peter Small's "Avatarnets" [http://www.avatarnets.com] Web site and listserve, as well as his excellent book, "Magical A-Life Avatars". As you'll find, Peter's interests span far beyond the "do" command, but his work is the best current practical application of using external text files to control Director movies that I'm aware of.
Creating Web Pages with FileIO
The client we created the Shelby-Cobra program for "moved on to new challenges," as they like to say in the business world, when the company he worked for was taken over last year. But during his tenure we did a number of interesting projects together, including a final job where Quantic built a program using FileIO that created customized Web pages on the fly.
Another trade show, another show booth. The client was promoting intranet solutions this time around, and needed an audience attractor that would tie in to the Web theme.
"We're going to be running a demo intranet site that people will be able to access during the show," he said.
"Hmm," I said.
Quantic had recently purchased a Connectix QuickCam for a project that never got off the ground. I had been playing with the QuickCam ever since, and was trying to find some practical application for it so we could recoup our investment. Starting with MasterApp, and then using BuddyAPI, I had just finished writing a Director program that would launch the QuickCam software and allow the user to take a picture of him/herself. I figured it'd be a neat trick for a trade show but still hadn't figured out how the user would get the picture. I could save it off to disk, but the user would still need something to view it. Projectors were too hefty for floppy disks.
While messing around with the QuickCam software options I noticed that photos could be saved out as JPEGs. "That'd be the way to go," I thought. "Everybody has a browser." You could even set up a Web page with the person's name, email address, and so on along with the photo, so they'd get more than just a picture.
"I wish I could figure out a way to get Director to create a Web page," I thought. "After all, HTML is only text."
Only text? About this time the metaphorical light-bulb bloomed over my head. I ran a couple of quick tests and then called the client.
"How about a program where people can enter their name, email, comments on the show or booth, whatever you like, take a photo of themselves, create a personalized Web page, and post it up on your show intranet all in the space of a couple of minutes?" I asked.
It took some more convincing, and we added a few more fillips, but after the client saw a proof-of-concept demo, he bought the idea and it was a hit at the show. And again, FileIO was the key that made this work.
The most basic of Web pages is simply the following text saved as a file with an "HTM" or "HTML" extension:
<html> <head> <title> </title> </head> <body> </body> </html>
If we were to put this in a field in a Director movie, call it "HTML" and then use the following command:
set textFile = new(xtra "fileio") set mainHTMLFile = the pathName & "test.htm" createFile(textFile, mainHTMLFile) openFile(textFile, mainHTMLFile,2) writeString(textFile, field "HTML") closeFile(textFile) gotonetPage the pathName & "test.htm"
we would have created an external text file called "test.htm" containing the text of the HTML field. The last line of the routine launches our default browser and displays "test.htm", which will be quite boring since it has no content at this point.
If you know HTML, it's easy to spruce up the page with a title, links to graphics and images, text content, tables, hyperlinks, JavaScript, or anything that can be used in a Web page. And you can even have users add their own information to the page. For example, you could create fields in the Director movie where the user could type in information such as their name, interests, and so on. Then it's a trivial task to take that dynamic information and blend it into the HTML, resulting in a file that might look something like:
<html> <head> <title>My Web Page</title> </head> <body>Hello! My name is Fred. <p> I'm interested in World Peace and helping old people.</body> </html>
With a little more work, you can even take the user's email address as input, add the correct "mailto:" HREF, and create a working email link.
The finished version of the program Quantic created for our client included all those features, plus the capability for booth visitors to take a picture of themselves with the QuickCam, which was saved out as a JPEG file. The path to the JPEG was incorporated into the HTML, and, when opened with a browser, the visitor's photo would display as part of their unique Web page. Over the course of the show, we updated the intranet hourly with visitor pages.
Visitors created their own Web page in seconds, and an hour or so later, could go to the show's intranet site from any show system and see their very own Web page including their photo. It probably wasn't all that exciting for the technically oriented, but to a business audience where HTML was no more understandable than ancient Greek, it was a show favorite.
FileIO is a wondrous Xtra, especially when you start thinking past it's normal use of simply writing out and reading in text files for player or game information. FileIO's read/write capabilities are only the beginning. What you can do with FileIO is really only limited to your imagination.
Copyright 1997-2024, Director Online. Article content copyright by respective authors.