Where can I download it?

If you are as impatient like me, don't want to read lengthly explanations on why and what, then you can immediately click the download-links below to get the xtra(s):

Mac package (sit 5)

Win package (zip)

What does it do?

- Save most of Lingo's datatypes directly to disk without conversion to strings
- Read most of Lingo's datatypes that were previously saved back in
- Writes strings to disk with proper encoding for both Macintosh and Windows

Is that cool?

You bet. For certain datatypes you can use FileIO and Lingo's string conversion, but not only will that be much slower, you also can't have "NULL" characters in your strings, can't save "media of member" or "picture of member", can't easily convert <void> and strings in lists (because of the quotes) and it will also take you a LOT more Lingo.

Here's an example that uses FileIO to save a list with some values:

  outputList = [1234, #symbol, 1.002, [1, 2, 3], rect(4, 5, 6, 7)]
  filePathName = the moviePath & "testFileIO"

  fileObj = new(xtra "fileIO")
  if not objectP(fileObj) then return -1
  fileObj.openFile(filePathName, 1)
  err = fileObj.status()
  if not (err) then fileObj.delete()
  else if (err and not (err = -37)) then return err
  fileObj.createFile( filePathName )
  err = fileObj.status() if (err) then return err

  fileObj.openFile(filePathName, 2)
  err = fileObj.status()
  if (err) then return err

  fileObj.writeString( string(outputList))
  fileObj.closeFile()

Here's some code that achieves the same, but now with PiMZ PropSave Xtra:

  outputList = [1234, #symbol, 1.002, [1, 2, 3], rect(4, 5, 6, 7)]
  filePathName = the moviePath & "testFileIO"
  savePropsToDisk(filePathName, outputList)

Which datatypes are supported?

   #void
   #integer
   #symbol
   #string
   #picture
   #float
   #list
   #point
   #rect
   #propList
   #member
   #castLib
   #sprite
   #soundSprite
   #color
   #date
   #media*

* See "What does it NOT do paragraph" for additional info.

Which aren't?

For obvious reasons, these datatypes cannot be written to disk:

   #xtra
   #instance
   #object
   #script

What does it NOT do?

- Properly byteswap the media of #field and button members (pushbutton, radiobutton, checkbox). This is actually a limitation of Director, probably not discovered earlier. Basically this means that if you write a #field member's media to disk on the Mac and read it back in on Windows, set the media of a member to that media value the resulting member will be messed up. So better avoid that!

How much do you want for it?

Nothing. It's free! Although it has cost more work than I initially thought, I can't charge you guys for it, but I also can't keep it from you. I'm not very charmed by commercial xtras that just patch some OS- or API functionality, and that's just what this xtra does. However, if you feel in a generous mood and want to support my xtra-writing efforts, please buy the OSControl Xtra

Oh yeah, one more thing...

By special request, for completeness, here's the entire reference:

To save your stuff (this could be a single lingo value like an integer or a string, but also a list containing all sorts of different values including lists), just use this global handler:

    savePropsToDisk( string fileName, any value, <options> )

Optionally, you can supply an additional parameter: a propList containing one or more of the following entries:

    #creator: string with four-letter creator (Macintosh only)
    #type: string with four-letter file type (Macintosh only)
    #prefsFolder: true (on Macintosh this is "HD:System Folder:Preferences", on Windows: "C:\WINDOWS\SYSTEM\")

(example: savePropsToDisk( "prefsFile", myList, [ #creator: "PiMZ", #type: "pref", #prefsFolder: true] )).

To get your stuff back, just use the returned value of this global handler:

    loadPropsFromDisk( string fileName, <options> )

Optionally, you can supply an additional parameter: a propList containing the followining entry:

    #prefsFolder: true (on Macintosh this is "HD:System Folder:Preferences", on Windows: "C:\WINDOWS\SYSTEM\")

Example: myList = loadPropsFromDisk( "prefsFile", [#prefsFolder: true] ). Make sure to check for errors.

NOTE: Unlike other file functions in Director, PropSave requires you to specify the path to the file and will fail if you only supply the file's name (You can use the at sign ("@") to specify the moviepath).

Of course I've tried to make this xtra as fool-proof as possible, but still errors may occur (the file was left open by another application, you mistyped the filename or path... whatever). In these cases, both handlers will return an error code (integer). Make sure to check that what the handlers return is what you expect (your previously written data from "loadPropsFromDisk" and a zero (no error) from "savePropsToDisk"). If the result is an error code, you can get a (albeit minimal) description of the error by calling:

    propSaveGetError( integer errorCode )

Enjoy!


home | back to xtras