wxJavaScript

back to io 

wxFileName

^{generated from ../src/mod_io/filename.cpp}

wxFileName encapsulates a file name. This class serves two purposes: first, it provides the functions to split the file names into components and to recombine these components in the full file name which can then be passed to the OS file functions (and wxWindows functions wrapping them). Second, it includes the functions for working with the files itself.

Remark: To change the file data you should use wxFile class instead. wxFileName provides functions for working with the file attributes.

Remark: Some of the properties of wxFileName causes IO processing. For example: accessTime will execute an IO API to retrieve the last access time of the file. This can result in performance issues when you use this property frequently. The best solution for this is to put the property in a variable and use that variable instead of the property:

   // Do this
   var fileName = new wxFileName("test.txt");
   var acc = fileName.accessTime;
   // From now on use var acc instead of fileName.accessTime
  

Constants

wxPathFormat

Name	Description
NATIVE
UNIX
MAC
DOS
VMS
BEOS
WIN
OS2

wxPathFormat is ported as a separate JavaScript object. Many wxFileName methods accept the path format argument which is wxPathFormat.NATIVE by default meaning to use the path format native for the current platform.

The path format affects the operation of wxFileName functions in several ways: first and foremost, it defines the path separator character to use, but it also affects other things such as whether the path has the drive part or not.

wxPathGet

Name	Description
VOLUME	Return the path with the volume (does nothing for the filename formats without volumes)
SEPARATOR	Return the path with the trailing separator, if this flag is not given there will be no separator at the end of the path.

wxPathGet is ported as a separate JavaScript object.

wxPathMkdir

Name	Description
FULL	Try to create each directory in the path and also don't return an error if the target directory already exists.

wxPathMkDir is ported as a separate JavaScript object.

wxPathNormalize

Name	Description
ENV_VARS	Replace env vars with their values
DOTS	Squeeze all .. and . and prepend cwd
TILDE	Unix only: replace ~ and ~user
CASE	Case insensitive => tolower
ABSOLUTE	Make the path absolute
LONG	Make the path the long form
SHORTCUT	Resolve if it is a shortcut (Windows only)
ALL

wxPathNormalize is ported as a separate JavaScript object. The kind of normalization to do with the file name: these values can be or'd together to perform several operations at once in normalize.

Class Properties

Name	Type	Description
cwd	String	Get/Set the current working directory.
homeDir	String	Get/Set the home directory.
pathSeparator	String	Returns the usually used path separator for the native platform. For all platforms but DOS and Windows there is only one path separator anyhow, but for DOS and Windows there are two of them.
pathSeparators	String	Gets the path separator of the native platform
volumeSeparator	String	Gets the string separating the volume from the path for the native format.

Class Methods

createTempFileName

createTempFileName(Prefix, 
                   File = null) : String
 

Name	Type	Default	Description
Prefix	String
File	wxFile	null	Object which wil get the file pointer to the temp file.

Returns a temporary file name starting with the given prefix. If the prefix is an absolute path, the temporary file is created in this directory, otherwise it is created in the default system directory for the temporary files or in the current directory.

If the function succeeds, the temporary file is actually created. When File is not omitted, this file will be opened using the name of the temporary file. When possible, this is done in an atomic way ensuring that no race condition occurs between the temporary file name generation and opening it which could often lead to security compromise on the multiuser systems. If file is omitted, the file is only created, but not opened.

Under Unix, the temporary file will have read and write permissions for the owner only to minimize the security problems.

dirExists

dirExists(Dir) : Boolean
 

Name	Type	Default	Description
Dir	String

Returns true when the directory exists.

dirName

dirName(Dir) : wxFileName
 

Name	Type	Default	Description
Dir	String

Creates a new wxFileName object based on the given directory.

fileExists

fileExists(File) : Boolean
 

Name	Type	Default	Description
File	String

Returns true when the file exists.

fileName

fileName(File) : wxFileName
 

Name	Type	Default	Description
File	String

Creates a new wxFileName object based on the given file.

getCwd

getCwd(Volume = "") : String
 

Name	Type	Default	Description
Volume	String

Retrieves the value of the current working directory on the specified volume. When the volume is omitted, the programs current working directory is returned for the current volume.

getFormat

getFormat(Format = wxPathFormat.NATIVE) : Integer
 

Name	Type	Default	Description
Format	wxPathFormat	wxPathFormat.NATIVE

Returns the canonical path format for this platform.

getPathSeparator

getPathSeparator(Format = wxPathFormat.NATIVE) : String
 

Name	Type	Default	Description
Format	wxPathFormat	wxPathFormat.NATIVE

Returns the usually used path separator for this format. For all formats but wxPathFormat.DOS there is only one path separator anyhow, but for DOS there are two of them and the native one, i.e. the backslash is returned by this method.

getPathSeparators

getPathSeparators(Format = wxPathFormat.NATIVE) : String
 

Name	Type	Default	Description
Format	wxPathFormat	wxPathFormat.NATIVE

Returns the string containing all the path separators for this format. For all formats but wxPathFormat.DOS this string contains only one character but for DOS and Windows both '/' and '\' may be used as separators.

getVolumeSeparator

getVolumeSeparator(Format = wxPathFormat.NATIVE) : String
 

Name	Type	Default	Description
Format	wxPathFormat	wxPathFormat.NATIVE

Returns the string separating the volume from the path for this format.

isCaseSensitive

isCaseSensitive(Format = wxPathFormat.NATIVE) : String
 

Name	Type	Default	Description
Format	wxPathFormat	wxPathFormat.NATIVE

Returns true if filenames for the given format are case-sensitive.

isPathSeparator

isPathSeparator(Sep, 
                Format = wxPathFormat.NATIVE) : Boolean
 

Name	Type	Default	Description
Sep	String		A path separator
Format	wxPathFormat	wxPathFormat.NATIVE

Returns true if the given string (only the first character is checked!) is a separator on the format.

mkdir

mkdir(Dir, 
      Perm = 777, 
      Flags = 0) : Boolean
 

Name	Type	Default	Description
Dir	String		Name of the directory
Perm	Integer	777	Permissions
Flags	wxPathMkdir	0	Default is 0. If the flags contain wxPathMkdir.FULL flag, try to create each directory in the path and also don't return an error if the target directory already exists.

Creates a directory. Returns true on success.

rmdir

rmdir(Dir)
 

Name	Type	Default	Description
Dir	String

Deletes the directory from the file system.

splitPath

splitPath(FullPath, 
          Format = wxPathFormat.NATIVE) : String Array
 

Name	Type	Default	Description
FullPath	String
Format	wxPathFormat	wxPathFormat.NATIVE

This function splits a full file name into components: the volume, path, the base name and the extension.

Remark: In wxWindows the arguments are passed as pointers. Because this is not possible in JavaScript, wxJavaScript returns an array containing the parts of the path.

The following code illustrates how splitPath works in JavaScript. parts[0] contains "C", parts[1] contains "\\", parts[2] contains "Temp" and parts[3] is empty.

    var parts = wxFileName.splitPath("C:\\Temp");
    for(element in parts)
    {
      ...
    }
    

Constructor

wxFileName

wxFileName()
 

wxFileName(FileName)
 

Name	Type	Default	Description
FileName	wxFileName

wxFileName(FullPath, 
           Format = wxPathFormat.NATIVE)
 

Name	Type	Default	Description
FullPath	String		A full path. When it terminates with a pathseparator, a directory path is constructed, otherwise a filename and extension is extracted from it.
Format	wxPathFormat	wxPathFormat.NATIVE

wxFileName(Path, 
           Name, 
           Format = wxPathFormat.NATIVE)
 

Name	Type	Default	Description
Path	String		A directory name
Name	String		A filename
Format	wxPathFormat	wxPathFormat.NATIVE

wxFileName(Path, 
           Name, 
           Ext, 
           Format = wxPathFormat.NATIVE)
 

Name	Type	Default	Description
Path	String		A directory name
Name	String		A filename
Ext	String		An extension
Format	wxPathFormat	wxPathFormat.NATIVE

wxFileName(Volume, 
           Path, 
           Name, 
           Ext, 
           Format = wxPathFormat.NATIVE)
 

Name	Type	Default	Description
Volume	String		A volume name
Path	String		A directory name
Name	String		A filename
Ext	String		An extension
Format	wxPathFormat	wxPathFormat.NATIVE

Constructs a new wxFileName object.

Properties

Name	Type	Description
accessTime	Date	Get/Set the last access time
createTime	Date	Get/Set the creation time
dirCount	Integer	Returns the number of directories in the file name.
dirExists	Boolean	Returns true when the directory exists.
dirs	Array	Returns the directories in string array
ext	String	Get/Set the extension
fileExists	Boolean	Returns true when the file exists.
fullName	String	Get/Set the full name (including extension but without directories).
fullPath	String	Returns the full path with name and extension for the native platform.
hasExt	boolean	Returns true when an extension is present.
isDir	boolean	Returns true if this object represents a directory, false otherwise (i.e. if it is a file). This property doesn't test whether the directory or file really exists, you should use dirExists or fileExists for this.
longPath	String	Return the long form of the path (returns identity on non-Windows platforms).
modificationTime	Date	Get/Set the time the file was last modified
ok	Boolean	Returns true if the filename is valid, false if it is not initialized yet. The assignment functions and clear may reset the object to the uninitialized, invalid state.
shortPath	String	Return the short form of the path (returns identity on non-Windows platforms).
times	Array	Get/Set an array with access time, modification time and creation time.
volume	String	Get/Set the volume name for this file name.

Methods

appendDir

appendDir(Dir)
 

Name	Type	Default	Description
Dir	String

Appends a directory component to the path. This component should contain a single directory name level, i.e. not contain any path or volume separators nor should it be empty, otherwise the function does nothing

assign

assign(FileName)
 

Name	Type	Default	Description
FileName	wxFileName

assign(FullPath, 
       Format = wxPathFormat.NATIVE)
 

Name	Type	Default	Description
FullPath	String		A full path. When it terminates with a pathseparator, a directory path is constructed, otherwise a filename and extension is extracted from it.
Format	wxPathFormat	wxPathFormat.NATIVE

assign(Path, 
       Name, 
       Format = wxPathFormat.NATIVE)
 

Name	Type	Default	Description
Path	String		A directory name
Name	String		A filename
Format	wxPathFormat	wxPathFormat.NATIVE

assign(Path, 
       Name, 
       Ext, 
       Format = wxPathFormat.NATIVE)
 

Name	Type	Default	Description
Path	String		A directory name
Name	String		A filename
Ext	String		An extension
Format	wxPathFormat	wxPathFormat.NATIVE

assign(Volume, 
       Path, 
       Name, 
       Ext, 
       Format = wxPathFormat.NATIVE)
 

Name	Type	Default	Description
Volume	String		A volume name
Path	String		A directory name
Name	String		A filename
Ext	String		An extension
Format	wxPathFormat	wxPathFormat.NATIVE

Creates the file name from various combinations of data.

assignCwd

assignCwd(Volume = "")
 

Name	Type	Default	Description
Volume	String

Makes this object refer to the current working directory on the specified volume (or current volume if volume is not specified).

assignDir

assignDir(Dir, 
          Format = wxPathFormat.NATIVE)
 

Name	Type	Default	Description
Dir	String
Format	wxPathFormat	wxPathFormat.NATIVE

Sets this file name object to the given directory name. The name and extension will be empty.

assignHomeDir

assignHomeDir()
 

Sets this file name object to the home directory.

assignTempFileName

assignTempFileName(Prefix, 
                   File = undefined)
 

Name	Type	Default	Description
Prefix	String
File	wxFile	undefined	Object with wil get the file pointer to the temp file.

The function calls createTempFileName to create a temporary file and sets this object to the name of the file. If a temporary file couldn't be created, the object is put into the invalid state. See also wxFile.

The following sample shows how to create a file with a temporary filename:

    var name = new wxFileName();
    var file = new wxFile();
 
    name.assignTempFileName('wxjs', file);
    file.write('This is a test');
    file.close();

    wxMessageBox('Filename: ' + name.fullPath);
   

clear

clear()
 

Reset all components to default, uninitialized state.

getFullPath

getFullPath(Format = wxPathFormat.NATIVE) : String
 

Name	Type	Default	Description
Format	wxPathFormat	wxPathFormat.NATIVE

Returns the full path with name and extension.

getPath

getPath(Flag = wxPathGet.VOLUME, 
        Format = wxPathFormat.NATIVE) : String
 

Name	Type	Default	Description
Flag	wxPathGet	wxPathGet.VOLUME
Format	wxPathFormat	wxPathFormat.NATIVE

Returns the path part of the filename (without the name or extension).

insertDir

insertDir(Pos, 
          Dir)
 

Name	Type	Default	Description
Pos	Integer
Dir	String

Inserts a directory before the zero-based position in the directory list.

isAbsolute

isAbsolute(Format = wxPathFormat.NATIVE) : Boolean
 

Name	Type	Default	Description
Format	wxPathFormat	wxPathFormat.NATIVE

Returns true if this filename is absolute.

isRelative

isRelative(Format = wxPathFormat.NATIVE) : Boolean
 

Name	Type	Default	Description
Format	wxPathFormat	wxPathFormat.NATIVE

Returns true if this filename is not absolute.

makeRelativeTo

makeRelativeTo(Base = "", 
               Format = wxPathFormat.NATIVE) : Boolean
 

Name	Type	Default	Description
Base	String		The directory to use as root. When not given, the current directory is used.
Format	wxPathFormat	wxPathFormat.NATIVE

This function tries to put this file name in a form relative to Base. In other words, it returns the file name which should be used to access this file if the current directory were Base.

Returns true if the file name has been changed, false if we failed to do anything with it (currently this only happens if the file name is on a volume different from the volume specified by Base).

mkdir

mkdir(Perm = 777, 
      Flags = 0) : Boolean
 

Name	Type	Default	Description
Perm	Integer	777	Permission for the directory
Flags	wxPathMkdir	0	Default is 0. If the flags contain wxPathMkdir.FULL flag, try to create each directory in the path and also don't return an error if the target directory already exists.

Creates a directory. Returns true on success.

normalize

normalize(Flags = wxPathNormalize.ALL, 
          Cwd = "", 
          Format = wxPathFormat.NATIVE) : Boolean
 

Name	Type	Default	Description
Flags	wxPathNormalize	wxPathNormalize.ALL
Cwd	String
Format	wxPathFormat	wxPathFormat.NATIVE

Normalize the path: with the default flags value, the path will be made absolute, without any ".." and "." and all environment variables will be expanded in it this may be done using another (than current) value of cwd.

prependDir

prependDir(Dir)
 

Name	Type	Default	Description
Dir	String

Prepends a directory name.

removeDir

removeDir(Pos)
 

Name	Type	Default	Description
Pos	Integer

Removes a directory name.

removeLastDir

removeLastDir()
 

Removes the last directory component from the path.

rmdir

rmdir()
 

Deletes the directory from the file system.

sameAs

sameAs(FileName, 
       Format = wxPathFormat.NATIVE) : Boolean
 

Name	Type	Default	Description
FileName	String
Format	wxPathFormat	wxPathFormat.NATIVE

Compares the filename using the rules of the format.

setCwd

setCwd()
 

Set this to the current directory.

touch

touch()
 

Sets the access and modification times to the current moment.