Adobe FrameMaker-12 Object Model JS: File

FrameMaker 12.0

Class

File

 Represents a file in the local file system in a platform-independent manner.

QuickLinks

File, changePath, close, copy, createAlias, decode, encode, execute, getRelativeURI, isEncodingAvailable, open, openDialog, openDlg, read, readch, readln, remove, rename, resolve, saveDialog, saveDlg, seek, tell, toSource, toString, write, writeln

Hierarchy

Folder
File

Properties

PropertyTypeAccessDescription
absoluteURIstring readonlyThe full path name for the referenced file in URI notation.
aliasbool readonlyIf true, the object refers to a file system alias or shortcut.
createdDate readonlyThe creation date of the referenced file, or null if the object does not refer to a file on disk.
creatorstring readonlyIn Mac OS, the file creator as a four-character string. In Windows or UNIX, value is "????".
displayNamestring readonlyThe localized name of the referenced file, without the path specification.
encodingstring r/wGets or sets the encoding for subsequent read/write operations.
One of the encoding constants listed in the JavaScript Tools Guide. If the value is not recognized, uses the system default encoding.
A special encoder, BINARY, is used to read binary files. It stores each byte of the file as one Unicode character regardless of any encoding. When writing, the lower byte of each Unicode character is treated as a single byte to write.
eofbool readonlyWhen true, a read attempt caused the current position to be at the end of the file, or the file is not open.
errorstring r/wA string containing a message describing the most recent file system error.
Typically set by the file system, but a script can set it. Setting this value clears any error message and resets the error bit for opened files. Contains the empty string if there is no error.
existsbool readonlyIf true, this object refers to a file or file-system alias that actually exists in the file system.
fsNamestring readonlyThe platform-specific full path name for the referenced file.
fullNamestring readonlyThe full path name for the referenced file in URI notation.
hiddenbool r/wWhen true, the file is not shown in the platform-specific file browser.
If the object references a file-system alias or shortcut, the flag is altered on the alias, not on the original file.
lengthnumber r/wThe size of the file in bytes.
Can be set only for a file that is not open, in which case it truncates or pads the file with 0-bytes to the new length.
lineFeedstring r/wHow line feed characters are written in the file system.
One of the values "Windows", "Macintosh", or "Unix".
modifiedDate readonlyThe date of the referenced file's last modification, or null if the object does not refer to a file on the disk.
namestring readonlyThe file name portion of the absolute URI for the referenced file, without the path specification.
parentFolder readonlyThe Folder object for the folder that contains this file.
pathstring readonlyThe path portion of the absolute URI for the referenced file, without the file name.
readonlybool r/wWhen true, prevents the file from being altered or deleted.
If the referenced file is a file-system alias or shortcut, the flag is altered on the alias, not on the original file.
relativeURIstring readonlyThe path name for the object in URI notation, relative to the current folder.
typestring readonlyThe file type as a four-character string.

• In Mac OS, the Mac OS file type.
• In Windows, "appl" for .EXE files, "shlb" for .DLL files and "TEXT" for any other file.

Class

PropertyTypeAccessDescription
fsstring readonlyThe name of the file system.
This is a class property accessed through the File constructor. Valid values are "Windows", "Macintosh", and "Unix".

Methods

Constructor

File File ([path: string])
Creates and returns a new File object referring to a given file system location.

ParameterTypeDescription
pathstringThe full or partial path name of the file, in platform-specific or URI format.
The value stored in the object is the absolute path. The file that the path refers to does not need to exist.If the path refers to an existing folder:
• The File function returns a Folder object instead of a File object.
• The new operator returns a File object for a nonexisting file with the same name. (Optional)

Examplenew File(path)

Class

string decode (uri: string)
Decodes a UTF-8 encoded string as required by RFC 2396, and returns the decoded string.
See also String.decodeURI().

ParameterTypeDescription
uristringThe UTF-8 encoded string to decode.

string encode (name: string)
Encodes a string as required by RFC 2396, and returns the encoded string.
All special characters are encoded in UTF-8 and stored as escaped characters starting with the percent sign followed by two hexadecimal digits. For example, the string "my file" is encoded as "my%20file".
Special characters are those with a numeric value greater than 127, except the following: / - _ . ! ~ * ' ( )
See also encodeURI().

ParameterTypeDescription
namestringThe string to encode.

bool isEncodingAvailable (name: string)
Reports whether a given encoding is available.

ParameterTypeDescription
namestringThe encoding name.
Typical values are "ASCII", "binary", or "UTF-8". For a complete list of supported encodings, see the JavaScript Tools Guide.

File openDialog (prompt: string[, filter: any=null][, multiSelect: bool=false])
Opens a dialog so the user can select one or more files to open.
Opens the built-in platform-specific file-browsing dialog in which a user can select an existing file or multiple files, and creates new File objects to represent the selected files.
• If the user clicks OK, returns a File object for the selected file, or an array of objects if multiple files are selected.
• If the user cancels, returns null.

ParameterTypeDescription
promptstringThe prompt text, displayed if the dialog allows a prompt.
filter any A filter that limits the types of files displayed in the dialog. (default: null)

• In Windows, a filter expression such as "Javascript files:*.jsx;All files:*.*".
• In Mac OS, a filter function that takes a File instance and returns true if the file should be included in the display, false if it should not. (Optional)
multiSelectboolWhen true, the user can select multiple files and the return value is an array. (default: false) (Optional)

File saveDialog (prompt: string[, filter: any=null])
Opens a dialog so the user can select a file name to save to.
Opens the built-in platform-specific file-browsing dialog in which a user can select an existing file location to which to save information, and creates a new File object to represent the selected file location.
• If the user clicks OK, returns a File object for the selected file location.
• If the user cancels, returns null.

ParameterTypeDescription
promptstringThe prompt text, displayed if the dialog allows a prompt.
filter any In Windows only, a filter that limits the types of files displayed in the dialog. (default: null)
In Windows only, a filter expression such as "Javascript files:*.jsx;All files:*.*". Not used In Mac OS. (Optional)

Instances

bool changePath (path: string)
Changes the path specification of the referenced file.

ParameterTypeDescription
pathstringA string containing the new path, absolute or relative to the current folder.

Examplefile.changePath ("..");

bool close ()
Closes this open file.
Returns true if the file was closed successfully, false if an I/O error occurred.

ExampleaFile.close()

bool copy (target: string | File)
Copies this object's referenced file to the specified target location.
Resolves any aliases to find the source file. If a file exists at the target location, it is overwritten. Returns true if the copy was successful.

ParameterTypeDescription
targetstring | FileA string with the URI path to the target location, or a File object that references the target location.

ExampleaFile.copy(target)

void createAlias (path: string)
Makes this file a file-system alias or shortcut to the specified file.
The referenced file for this object must not yet exist on disk. Returns true if the operation was successful.

ParameterTypeDescription
pathstringA string containing the path of the target file.

bool execute ()
Executes or opens this file using the appropriate application, as if it had been double-clicked in a file browser.
You can use this method to run scripts, launch applications, and so on.
Returns true immediately if the application launch was successful.

string getRelativeURI (basePath: string)
Retrieves and returns the path for this file, relative to the specified base path, in URI notation.
If no base path is supplied, the URI is relative to the path of the current folder. Returns a string containing the relative URI.

ParameterTypeDescription
basePathstringA base path in URI notation.

ExampleaFile.getRelativeURI(basePath)

bool open (mode: string[, type: string][, creator: string])
Opens the referenced file for subsequent read/write operations. The method resolves any aliases to find the file.
Returns true if the file was opened successfully.
The method attempts to detect the encoding of the open file. It reads a few bytes at the current location and tries to detect the Byte Order Mark character 0xFFFE. If found, the current position is advanced behind the detected character and the encoding property is set to one of the strings UCS-2BE, UCS-2LE, UCS4-BE, UCS-4LE, or UTF-8. If the marker character is not found, it checks for zero bytes at the current location and makes an assumption about one of the above formats (except UTF-8). If everything fails, the encoding property is set to the system encoding.
IMPORTANT: Be careful about opening a file more than once. The operating system usually permits you to do so, but if you start writing to the file using two different File objects, you can destroy your data.

ParameterTypeDescription
modestringThe read-write mode, a single-character string.
One of these characters:
• r (read) Opens for reading. If the file does not exist or cannot be found, the call fails.
• w (write) Opens a file for writing. If the file exists, its contents are destroyed. If the file does not exist, creates a new, empty file.
• e (edit) Opens an existing file for reading and writing.
• a (append) Opens an existing file for reading and writing, and moves the current position to the end of the file.
typestringIn Mac OS, the type of a newly created file, a 4-character string. Ignored in Windows and UNIX. (Optional)
creatorstringIn Mac OS, the creator of a newly created file, a 4-character string. Ignored in Windows and UNIX. (Optional)

ExampleaFile.open(mode, type, creator)

File openDlg (prompt: string[, filter: any=null][, multiSelect: bool=false])
Opens the built-in platform-specific file-browsing dialog, in which the user can select an existing file or files, and creates new File objects to represent the selected files.
Differs from the class method openDialog() in that it presets the current folder to this File object's parent folder and the current file to this object's associated file.
• If the user clicks OK, returns a File or Folder object for the selected file or folder, or an array of objects.
• If the user cancels, returns null.

ParameterTypeDescription
promptstringA string containing the prompt text, if the dialog allows a prompt.
filter any A filter that limits the types of files displayed in the dialog. (default: null)

• In Windows, a filter expression such as "Javascript files:*.jsx;All files:*.*".
• In Mac OS, a filter function that takes a File instance and returns true if the file should be included in the display, false if it should not. (Optional)
multiSelectboolWhen true, the user can select multiple files and the return value is an array. (default: false) (Optional)

string read ([chars: number])
Reads the contents of the file, starting at the current position.
Returns a string that contains up to the specified number of characters. If a number of characters is not supplied, reads from the current position to the end of the file. If the file is encoded, multiple bytes might be read to create single Unicode characters.

ParameterTypeDescription
charsnumberAn integer specifying the number of characters to read. (Optional)

ExampleaFile.read(chars)

string readch ()
Reads a single text character from the file at the current position.
Line feeds are recognized as CR, LF, CRLF or LFCR pairs. If the file is encoded, multiple bytes might be read to create a single Unicode character. Returns a string that contains the character.

ExampleaFile.readch()

string readln ()
Reads a single line of text from the file at the current position.
Line feeds are recognized as CR, LF, CRLF or LFCR pairs.. If the file is encoded, multiple bytes might be read to create single Unicode characters. Returns a string that contains the text.

ExampleaFile.readln()

bool remove ()
Deletes the file associated with this object from disk immediately, without moving it to the system trash.
Does not resolve aliases; instead, deletes the referenced alias or shortcut file itself. Returns true if the file was successfully removed.
• IMPORTANT: Cannot be undone. It is recommended that you prompt the user for permission before deleting.

bool rename (newName: string)
Renames the associated file.
Does not resolve aliases, but renames the referenced alias or shortcut file itself. Returns true if the file was successfully renamed.

ParameterTypeDescription
newNamestringThe new file name, with no path information.

ExampleaFile.rename(newName)

File resolve ()
Attempts to resolve the file-system alias or shortcut that this object refers to.
If successful, creates and returns a new File object that points to the resolved file system element. Returns null if this object does not refer to an alias, or if the alias could not be resolved.

File saveDlg (prompt: string[, filter: any=null])
Opens the built-in platform-specific file-browsing dialog, in which the user can select an existing file location to which to save information, and creates a new File object to represent the selected file.
Differs from the class method saveDialog() in that it presets the current folder to this File object's parent folder and the file to this object's associated file.
• If the user clicks OK, returns a File object for the selected file.
• If the user cancels, returns null.

ParameterTypeDescription
promptstringA string containing the prompt text, if the dialog allows a prompt.
filter any In Windows only, a filter that limits the types of files displayed in the dialog. (default: null)
In Windows only, a filter expression such as "Javascript files:*.jsx;All files:*.*". Not used In Mac OS. (Optional)

bool seek (pos: number[, mode: number=0])
Seeks to a given position in the file.
The new position cannot be less than 0 or greater than the current file size. Returns true if the position was changed.

ParameterTypeDescription
posnumber The new current position in the file as an offset in bytes from the start, current position, or end, depending on the mode.
modenumber (range: 0 - 2)The seek mode. (default: 0)
One of:
• 0: Seek to absolute position, where pos=0 is the first byte of the file. This is the default.
• 1: Seek relative to the current position.
• 2. Seek backward from the end of the file. (Optional)

ExampleaFile.seek(pos, mode)

number tell ()
Retrieves the current position as a byte offset from the start of the file.
Returns a number, the position index.

ExampleaFile.tell()

string toSource ()
Creates and returns a serialized string representation of this object.
Pass the resulting string to eval() to recreate the object.

string toString ()
Converts this object to a string.

bool write (text: string)
Writes the specified text to the file at the current position.
You can supply multiple text values; the strings are concatenated to form a single string.
For encoded files, writing a single Unicode character may write multiple bytes. Returns true if the write was successful.
IMPORTANT: Be careful not to write to a file that is open in another application or object, as this can overwrite existing data.

ParameterTypeDescription
textstringA text string to be written.

ExampleaFile.write(text, ...)

bool writeln (text: string)
Writes a string to the file at the current position and appends a line-feed sequence.
You can supply multiple text values. The strings are concatenated into a single string, which is written in the file followed by one line-feed sequence, of the style specified by this object's linefeed property.
For encoded files, writing a single Unicode character may write multiple bytes. Returns true if the write was successful.
IMPORTANT: Be careful not to write to a file that is open in another application or object, as this can overwrite existing data.

ParameterTypeDescription
textstringA text string to be written.

ExampleaFile.writeln(text, ...)

Element of

Reflection.sampleFile

ReflectionInfo.sampleFile

Used in:

any $.evalFile (file: File[, timeout: number=10000])

bool File.copy (target: string | File)

void FlashPlayer.loadMovie (file: File)

Return

File File.File ([path: string])

File File.openDialog (prompt: string[, filter: any=null][, multiSelect: bool=false])

File File.openDlg (prompt: string[, filter: any=null][, multiSelect: bool=false])

File File.resolve ()

File File.saveDialog (prompt: string[, filter: any=null])

File File.saveDlg (prompt: string[, filter: any=null])

Jongware, 18-Jan-2015 v1.0Contents :: Index