TechNote (Archived)

Using the searchPath in Director

Question:
How do I use the searchPath in Director?

Answer:
The searchPath is an ordered list of directories or folders to look in when trying to locate files. You can manipulate the searchPath like any other list..

This statement assigns two folders to the searchPath in Windows:

set the searchPath =["c:\myFolder","d:\aFolder"]

This statement assigns two folders to the searchPath in Macintosh:

set the searchPath =["myDrive:myFolder","myCDROM:aFolder"]

The searchPath should contain a list of absolute pathnames, and should be set up separately for each platform. On Windows 3.1, use DOS pathnames and on the Macintosh, use Macintosh pathnames. (32-bit projectors support long filenames)

Relative Pathnames
Relative pathnames are Lingo strings that begin with a @ operator, followed by a sequence of folder names, such as "@:MyFile" or"@/directory/fname". (In Director, you can use / or \ as path delimiters.) Simple filenames with no path information, such as"Movie1.DIR", are treated as relative pathnames. Relative pathnames are not specific to Windows. They are useful for authoring movies which are independent of their location, as well as for movies that are cross platform.

Absolute Pathnames
Absolute Pathnames are Lingo strings that contain all path information from the root of a device down to the named file. The moviePath function returns an absolute pathname of the currently loaded movie, in the format of the platform where the movie is currently running.

This is a sample absolute path name in Windows:

"c:\director\movies\mymovie.dir"

This is a sample absolute path name on the Macintosh:

"External Disk:Director:Movies:mymovie"

You can use an absolute pathname anywhere you use a relative pathname, but the path name is cross-platform. To create a cross-platform title, use relative pathnames wherever possible.

Resolving Pathnames
A number of factors influence how Director resolves a path name.

	Whether an extension is supplied for the filename
	Whether the Lingo variable the searchCurrentFolder is set to TRUE
	Whether the searchPath contains any entries
	Whether the pathname is relative or absolute

When a pathname is resolved, we always know the context, so we can make some assumptions about the type of file we are looking for. For instance, sound playFile can only take sound files, like 'AIFF' or *.wav files. If we know what type of file we are looking for, we can add common extensions, in order to aid cross-platform development. If a file cannot be located and it has no extension, it is searched for with all extensions applicable to its type.

	Windows	Macintosh
Director Movie	* .dir	* .dir
	* .dxr	* .dxr
	* .cst	* .cst
	* .	* .
Bitmap	* .pic	* .pic
	* .pct	* .pct
	* .bmp
	* .dib
	* .jpg
	* .pcd
	* .gif
Digital Video	* .avi
	* .mov	* .mov
Sound	* .aif	* .aif
	* .wav

Normally, the file in a folder or directory relative to the movie that is trying to locate it. This is controlled by the setting of the searchCurrentFolder. When set to TRUE, which is the default setting, the file is looked for relative to the folder or directory which contains the Director movie. By setting this variable to FALSE, you can skip this step.

If the file cannot be found (after trying possible extensions if one is not supplied), the file is looked for relative to each entry in the searchPath. Each entry in the list is tried in sequence, appending possible extensions each time, until a file is found or until the end of the list is reached.

If the searchCurrentFolder is FALSE and the searchPath is empty, the file will not be looked for anywhere.

This is all true for relative pathnames. Absolute pathnames are treated somewhat differently. Files are looked for in the specified location first, but can still have an extension added. If the file is not found, the filename is separated from the rest of the path, and this filename is treated as a simple relative pathname, following all the step outlined above.

Linked Castmembers
Director records linked castmembers are recorded by storing an absolute pathname to the linked file. When a movie refers to the linked file to a relative path is constructed between the movie and the linked castmember. This relative path is resolved as described above. If a relative path cannot be constructed, for instance if the movie and linked file were originally on separate devices, then the complete absolute path to the linked file is resolved, including stripping all path information leaving just the filename.

Note: On startup, a projector attempts to resolve the paths of linked castmembers before any lingo is executed).

Commands that use relative pathnames

These commands use relative pathnames:

 set the fileName of member set the fileName of castlib set the fileName of window go to movie importFileInto open window openResFile openXlib play movie sound playFile 

Commands that don't use relative pathnames

These commands don't use relative pathnames:

 getNthFileNameInFolder open saveMovie saveCastlib the traceLogFile XObjects, including FileIO Xtras (that are outside the Xtras folder) 

TechNote revision history:
7/14/98 - Corrected typos in first two syntax examples. -P.D.

Search Support

---