revJournal - Revolution Tutorials

Saving data in Revolution standalones

OK, so you've made your application, it all works perfectly inside Revolution and now you want to make it into a standalone, so others can use it. Now you find out that standalones cannot save to themselves!

So how can you save the data inside your standalone application. Well it turns out that it isn't so difficult after all, so don't panic :-)

1. Saving sub-stacks
2. Saving template stacks
3. Saving preference files
4. Saving data files

1. Saving sub-stacks

From the File menu, choose "Standalone Application Settings...". Click on the "Stacks" button in the toolbar and you will see you stack file and all its sub-stacks listed. Tick the checkbox that "Move substacks into individual stackfiles".

Stack naming: You will see from the picture that I use a certain style for naming all my stacks. This is because all applications tends to have some of the same stacks e.g. Prefs, Help, About Revolution hates opening more than one stack with the same name, so I choose a prefix for each project and name all the stacks in that project using that prefix. For this example, I used "app".

Close the settings window, save your stack file and choose "Save as Standalone Application..." from the File menu. Your application will be created but the sub-stacks will not be part of the application file, so they can be saved at any time.

In the screen shot above, you can see that I have a single stack file called "appSplash.rev". This contains 6 stacks: the appSplash stack and 5 other sub-stacks. After building the standalone as described, the appSplash stack will not be writable but the other 5 stacks can all be changed and saved as you need.

I built this test application for Windows and Mac OSX and as they produce different file structures it is worth explaining where each standalone keeps its sub-stacks:

• Windows creates a single folder with the exe and the other .rev files in the same folder
• Mac OS X creates an application bundle which looks like a single file but is actually a folder. To see what is inside this folder, control-click on the application and choose "Show Package Contents" from the popup menu. Look in the Contents folder and then in the MacOS folder - you will see your application and the sub-stacks.

You don't have to worry about where the system has put the sub-stacks, the Revolution engine in the standalone knows where to find everything if you leave it where it was.

2. Saving template stacks

Build your standalone into a single application file so that none of the stacks are saveable, but have one of the sub-stacks be a template for the stack you need to save. To save the data, clone this stack and save the copy (with all the data) into an appropriate location e.g. the current user's documents folder.

To do this, you will need a script like the following:

on createDataStack
   clone stack "dataTemplate"
   set the name of stack "Copy of dataTemplate" to "MyAppData"
   set the fileName of stack "MyAppData"to \
      pathToUsersDocumentsFolder &"/MyAppData.rev"
      save stack "MyAppData"
end createDataStack

3. Saving preference files

Revolution gives you an easy method to find out where the preference file should be stored, in both Windows & Mac systems. (For Linux / Unix systems, use the user's home folder to store such files.)

Here is my function (Mac or Windows only) for getting the path to the correct folder to store preferences:

function getPrefsFolderPath
   if the platform = "MacOS" then
     put specialFolderPath("Preferences") into prefsFolder 
  else if the platform = "Win32" then
     put specialFolderPath(26) into prefsFolder
   end if
   if last char of prefsFolder is not "/" then put \
        "/" after prefsFolder
   return prefsFolder
 end getPrefsFolderPath

For Macs, this gives you the current user's Preferences folder. For Windows, it gives the user's Application Data folder. Note: I always like to check to make sure that a folder path always ends in a slash. The script above handles that.

Having worked out the path to your preference file, you need to have routines to read and write the file and store it's data in your application. My preferred method is to have a preferences stack to allow the user to edit settings. When the application starts, it reads the preference file and sets the various objects in the preferences stack. Then when I need to know a setting, I just have to check the relevant object on the preferences stack.

When the user edits the preferences stack and wants to save them, I write the new settings to the preferences file. If they edit and then cancel, I can read the original data back from the prefs file.

4. Saving data files

What ever you choose, you need to allow for the user not being able to write - if writing your file gives an error, tell them and let them select another location. If the user can select a location, you will need to store this as a preference so that you don't have to ask every time.

If you use a sub-folder of your stack, make sure you use relative addressing so that the user can move to a new hard drive, or rename their drive without breaking the links. The easiest way to find a relative address is to use the filename of the stack.

If I get the filename of a stack I am working on at the moment, I get this:

/Users/sarah/Documents/Revolution/DateTime.rev

(I use Mac OS X; if you have a different operating system, you will get a different structure, but the scripts below will still work.)

Now suppose I wanted to save data in a sub-folder of this stack:

put the filename of this stack into tPath
set the itemDelimiter to "/"
put "DateTime folder/" into last item of tPath
if there is not a folder tPath then create folder tPath

This gives me a folder called "/Users/sarah/Documents/Revolution/DateTime folder/". I have the full path to the folder but the only section hard-wired into the script is the actual folder name. It doesn't matter where the application goes, this script can still find where to store the data folder.

To write data to the data folder, you can write either binary files or text files. If your data is plain text, it doesn't make any difference, however if you want to save pictures, sounds or any other non-text data, you will need to save in binary format. The command is the same in either case, with a single word change:

put tTextData into URL ("file:" & tPath & "TextData")

or

put tBinData into URL ("binfile:" & tPath & "BinaryData")

The URL command is a great convenience for those of us accustomed to the open file - read or write - close file cycle needed in other languages. All you need to do is decide whether you need to use binfile or file.

Revolution experts will point immediately to the methods that I have not mentioned here of which the most common would be using an external database such as MySQL or writing preferences to the Windows registry, however this is intended as a guide for getting started rather than a complete list of all possibilities. Hopefully it will prove useful.

Until next time,
Sarah