Office of Digital Humanities
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.
By the end of this reading you should know the following:
the defaultFolder property.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.
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 file 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.
Note: 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/Linux 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 and *nix 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.
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). But LiveCode provides tools for adapting absolute file paths to the current host system. Most common operating systems have standard folders for storing certain types of information. For example, preference files tend to be stored in a specific place; each user has a "home" folder where they can save their files; and there are typical places for storing temporary files. As a cross-platform development tool, LiveCode gives you an easy way to find out where these folders are located on the current host operating system, a function called specialFolderPath().
How does this function work? Let's say, for instance, that you want to save a file to the user's Desktop. Simply use the specialFolderPath() function with the argument "desktop":
put specialFolderPath("desktop") into tFolderPath
put tFolderPath & "/mydocument.txt" into tFilePath
put field "importantStuff" into URL ("file:" & tFilePath)
The specialFolderPath() function returns a file path to the folder appropriate for the current operating system. For example, on Mac OS X specialFolderPath("desktop") might return something like "/Users/myname/Desktop". On Windows it might be something like "C:/Users/myname/Desktop".
There are several common folder identifiers you can plug in to this function, including "home", "preferences", "temporary", and "fonts". Each identifier returns the platform-specific path to the given folder. See the LiveCode dictionary entry for specialFolderPath for a complete list.
One particularly useful folder identifier is "resources". When you call specialFolderPath("resources") you get the file path to the folder your stack is saved in. That makes it simple to build file paths to media assets that are stored in the same folder as your stack.
A note about special folder paths on mobile platforms. The specialFolderPath() function works on iOS and Android, but because file system access is much different on mobile versus desktop platforms, the available folder identifiers for mobile platforms are different, too. Perhaps the most useful folder identifiers for mobile devices are engine, documents, and cache. The resources identifier is also useful in the mobile environment; it is a synonym for engine.
specialFolderPath("engine") – returns the file path to the folder where your app is located in the mobile device's file system. This is most often where you would store media file resources like image and audio files for access by your app.specialFolderPath("resources") – same as "engine".specialFolderPath("documents") – returns the file path to the folder where your app is permitted to save permanent documents.
specialFolderPath("cache") – returns the file path to the folder where your app can save temporary files.What if you want to access files that are in a folder other than one of the special folders accessible through specialFolderPath()? LiveCode provides a way for you to specify where files should be created by default and where commands should look for files when no file path is specified. You can do this with the defaultFolder property. The defaultFolder is a property that applies to the entire LiveCode environment. Such properties are called global properties. If you examine the defaultFolder property immediately after launching LiveCode:
put the defaultFolder into message boxYou will get a result something like this (for Mac/Linux):
/Applications/Or this (for Windows):
C:/Program Files/RunRev/LiveCode
You can change the defaultFolder by setting it to the desired
folder:
set the defaultFolder to "/MyHD/MyProject/textfiles"
Once the defaultFolder is set, any reference to a relative file path will begin at the specified default folder to derive the full file path. Setting the defaultFolder persists only until LiveCode is shut down, so if you want this folder to be used every time you open your stack, you should probably set the defaultFolder in an openStack or openCard handler.
Here is how to set the defaultFolder to
the folder where the currently open stack is saved:
set the defaultFolder to specialFolderPath("resources")
In versions of LiveCode before v. 6.7, the specialFolderPath("resources") option did not exist, so in older versions you would have to do it like this:
get the effective fileName of this stack
set the itemDelimiter to "/"
delete last item of it
set the defaultFolder to it
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.
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.
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)
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.
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.