BYU Home pageBRIGHAM YOUNG UNIVERSITY
  Office of Digital Humanities
Back     BYU LiveCode Lessons Gateway

Computers & the Humanities 210

Working with External Files

When dealing with any type of application development, particularly on a large scale, it often becomes necessary to work with data contained in files other than the current stack. Doing so effectively and efficiently is a challenge, but it also increases the elegance with which your application executes itself.

Objectives

By the end of this reading you should know the following:

  1. What is a file path?
  2. Recognize the differences in file paths (most notably in drive names) between Windows and Mac OS X/Unix operating systems.
  3. Know the difference between an absolute path and a relative path.
  4. Understand the purpose of the defaultFolder property.
  5. Know how to set the defaultFolder property.
  6. Memorize the short LiveCode scripting routine that changes the defaultFolder to the folder your stack is in.

The primary reason for working with external files is to decrease the actual memory required by your application. If the data for your resources are contained in discrete files external to the actual application, then the application itself will run more quickly and smoothly as it will not be bogged down by an inordinate amount of data. Another reason for having external files is to allow access to such files by multiple applications. These will each be covered in turn.

Referencing External Files

Absolute File Paths

In order to work successfully with external files, you must understand file paths, which are basically descriptions of the exact location of a particular file. Such paths are created by beginning at the top of the computer's file system—designated by a letter in Windows and a slash in Mac OS X and Unix systems, and then moving down the file structure, naming every folder that encloses the file, in descending order, until the file is reached.

For example,

  c:/Documents and Settings/localuser/My Documents/Schmetterling.gif

is a Windows-style file path pointing to:

an image file "Schmetterling.gif"

located within a folder entitled "My Documents"

that is located in a folder called "localuser"

that is located in a folder called "Documents and Settings"

that resides on the disk drive that has been labeled "c:\"

In this particular case, this path is an absolute path pointing to an image. The term "absolute" is used because as long as the data remains in that exact location, then it is accessible, without variation, using that path.

The syntax of absolute paths varies from platform to platform. Windows computers uses the notation above, with the drive letter first, followed by the folder names, then the file. Be aware that LiveCode, when dealing with Windows paths, uses a '/' instead of the more common '\' that Windows machines usually employ. This is to keep the folder delimiter consistent from platform to platform, as Macintosh OS X and Unix machines use a '/'. Both Mac OS X and other Unix operating systems designate the "root volume", or boot drive, with a '/'; all other files and folders on the root volume are relative to the '/'. Thus, on Mac OS X systems you do not need to supply a name or letter for the boot drive; the slash essentially takes the place of that name. Adapting the above file path example to Mac OS X, would yield something like this:

  /Users/localuser/Documents/Schmetterling.gif.

Unix and Linux file paths will look very similar to Mac OS X file paths.

Relative File Paths

Absolute paths have several inherent limitations. Most notably, if you create a program on one machine, the absolute paths will most likely be different on another one (due to different folder names, different user logins, different platforms, and so forth). To overcome such limitations, LiveCode provides properties that allow us to access, manipulate and work with absolute paths, thus turning them into relative paths. The defaultFolder is a property that applies to the entire LiveCode environment. Such properties are called global properties. The defaultFolder property contains the path to the folder that LiveCode will look at when you don't specify a full file path. In the authoring environment, upon launching LiveCode, this path always starts out pointing to the folder containing the LiveCode program. If you have created an application as a standalone object, then it points to the folder containing the application. You can obtain this path using statements such as:

get the defaultFolder
put the defaultFolder into mainPath

You can also set this property to a path you choose:

set the defaultFolder to "c:/Documents and Settings/localuser/My Documents/RussianProject/" --(Windows format)
set the defaultFolder to "/Users/myuser/Documents/RussianProject/" --(Mac OSX/Unix format)

You can use the defaultFolder property to access resources outside of the stack. Folder names can be added or subtracted to the path according to need. This is especially useful when you are not sure of the precise location where your application will be deployed. The use of relative paths allows greater flexibility and minimizes the possibilty of broken resource links that can happen with absolute paths.

The value of the defaultFolder is underscored by the fact that files of all types located within this folder can be accessed or referred to from within a stack’s object scripts without the need to specify the entire file path. The name of the file itself is sufficient.

A Handy Handler

Most of the time it is not a good idea to recommend memorizing LiveCode scripting routines. However, this routine is an exception because it is so useful. The following three lines of code will change the defaultFolder to the folder that contains the current stack. They can be inserted into any handler where you want to change the defaultFolder. Very often it is used in an openStack handler, for example. (Note that the stack must already have been saved to disk for this to work.)


  set the itemDelimiter to "/"
  get the effective fileName of this stack
  set the defaultFolder to item 1 to -2 of it

Don't worry if you don't understand everything perfectly yet. Just memorize it and enjoy the power it gives you!

Images

As mentioned before, image data can reside in the stack or outside the stack in an external file. A small number of images requiring small amounts of data are acceptable as parts of the stack. However, if the need arises for a large number of images with higher resolution, you may be better off placing them in an appropriately named resource folder created in conjunction with your stack.

If we are working in a fixed environment and know that the resources will be located in an absolute location (such as on a remote server, or on the particular hard drive), then we can establish our images with absolute paths (it would be best to have all the picture files in the same folder, for the sake of organization). With this setup, the application can be placed in different locations, and as long as the path to the picture files is accessible, the images will be displayed properly.

More commonly, however, when we create an application we cannot be sure where it will be deployed. In this case "hard-coded" absolute file paths are useless. In this situation it is best to place all picture files in a single folder and bundle them with the application. Instead of creating an absolute path, we would need to set the link of each image to something similar to Picts/Schmetterling.jpg where "Picts" is a folder located in the default folder.

Audio and Video

The process for accessing audio and video files as external files is so similar for each type that we will treat them together. The access to these files is achieved through the use of player objects. Players are control objects just like buttons and fields. Consequently they share some common properties (such as name, visible, location, etc.), as well as possessing some properties unique to their object type.

As with images, if we know the application will be deployed in a static environment, then we can create the links to the audio and video files as absolute paths. Again, it is best to organize the media into appropriate folders.

Creating relative paths to audio and video files is just like creating them for image files. If the files are all located within the same folder as the LiveCode application, then referring to the files by their name alone will suffice. However, if they are in another folder, we would have to set the defaultFolder to an appropriate file path, then we could set the link for each file to an appropriate relative path, such as Videos/Bonjour.mov or Sounds/AuRevoir.wav, where "Videos" and "Sounds" are folders within the default folder.

Text

LiveCode can read and write to external text files. The easiest way to accomplish this is through the URL keyword. A URL is a container, like a variable or a field, but a URL container always refers to files outside of the LiveCode environment. The other necessary keyword when using URL containers is file. Here are some examples of proper syntax for this:

Reading a file, using a full file path:
put URL "file:/c:/Documents and Settings/localuser/MyDocuments/RussianStack/DatesTimes" into field "whichTime" --(Windows format)
put URL "file:/Users/username/Documents/RussianStack/DatesTimes" into field "whichTime" --(Mac OS X/Unix format)

Reading a file, using a relative file path:
get URL "file:results.txt"
put URL "file:results.txt" into theResults

Writing to an external file:
put userResult into URL "file:Datafiles/feedback.txt
put field "finalAns" after URL "file:/d:/Tutorials/Datafiles/Results" --(Windows format, different drive)
put field "finalAns" into URL "file:/Volumes/Tutorials/Datafiles/Results" --(Mac OS X format, non-boot drive)

As with other external files, you can either write out the entire path to the location for the text tile, or you can create a relative path as indicated earlier for other object types (e.g., Datafiles/prefs.txt.) With that path you can either put the contents of the file into another container, or you can write the contents of a container to a text file. The keywords into, before, and after work as they do with putting text into other containers. Just as with creating variables, if the external file you are writing data to does not exist, then LiveCode will create it automatically.

Conclusion

The key to successfully working with external files is to ensure that you have a correct knowledge of file paths and use them appropriately as the conditions require. This will allow you to create streamlined complex applications.


Back     BYU LiveCode Lessons Gateway
Maintained by Devin Asay.
Copyright © 2005 Brigham Young University