Folder
Folder
objects are created with the folder
command. They contain references to folders that may or may not actually exist on disk. For example, when you execute the folder
command to create a new folder, a valid folder
object is created but nothing is actually stored on disk until you call the folder.create()
function.
Example
The following example creates a "JohnSmith" folder object:
var curfolder : 4D.Folder
curfolder = folder("/PACKAGE/JohnSmith")
Pathnames
folder
objects support several pathnames, including filesystems
or posix
syntax. Supported pathnames are detailed in the Pathnames page.
Functions and properties
.copyTo( destinationFolder : 4D.Folder { , newName : string } { , overwrite : integer } ) : 4D.Folder copies the Folder object into the specified destinationFolder |
.create() : boolean creates a folder on disk according to the properties of the folder object |
.createAlias( destinationFolder : 4D.Folder , aliasName : string ) : 4D.File creates a symbolic link |
.delete( { option : integer } ) deletes the folder |
.exists : boolean true if the folder exists on disk |
.extension : string returns the extension of the folder name (if any) |
.file( path : string ) : 4D.File a File object inside the Folder object and returns its reference |
.files( { options : integer } ) : collection a collection of File objects contained in the folder |
.folder( path : string ) : 4D.Folder creates a folder object inside the parent folder object and returns its reference |
.folders( { options : integer } ) : collection returns a collection of folder objects contained in the parent folder |
.fullName : string returns the full name of the folder, including its extension (if any) |
.hidden : boolean true if the folder is set as "hidden" at the system level |
.isAlias : boolean always false for a Folder object |
.isFile : boolean always false for a folder |
.isFolder : boolean always true for a folder |
.isPackage : boolean true if the folder is a package on macOS (and exists on disk) |
.modificationDate : date the date of the folder's last modification |
.modificationTime : time the time of the folder's last modification |
.name : string the name of the folder, without extension (if any) |
.original : 4D.Folder the same Folder object as the folder |
.parent : 4D.Folder the parent folder object of the folder |
.path : string the POSIX path of the folder |
.moveTo( destinationFolder : 4D.Folder { , newName : string } ) : 4D.Folder moves or renames the folder object (source folder) into the specified destinationFolder |
.rename( newName : string ) : 4D.Folder renames the folder with the name you passed in newName and returns the renamed folder object |
4D.Folder.new()
4D.Folder.new ( path : string ) : 4D.Folder
Description
The 4D.Folder.new()
function creates and returns a new object of the 4D.Folder
type. It is identical to the folder
command (shortcut).
It is recommended to use the
folder
shortcut command instead of4D.Folder.new()
.
.copyTo()
.copyTo( destinationFolder : 4D.Folder { , newName : string } { , overwrite : integer } ) : 4D.Folder
Parameter | Type | Description | |
---|---|---|---|
destinationFolder | 4D.Folder | → | Destination folder |
newName | string | → | Name for the copy |
overwrite | integer | → | fk overwrite to replace existing elements |
Result | 4D.Folder | ← | Copied file or folder |
Description
The .copyTo()
function copies the Folder
object into the specified destinationFolder.
The destinationFolder must exist on disk, otherwise an error is generated.
By default, the folder is copied with the name of the original folder. If you want to rename the copy, pass the new name in the newName parameter. The new name must comply with naming rules (e.g., it must not contain characters such as ":", "/", etc.), otherwise an error is returned.
If a folder with the same name already exists in the destinationFolder, by default Qodly generates an error. You can pass the kOverwrite
constant in the overwrite parameter to ignore and overwrite the existing file
Constant | Value | Comment |
---|---|---|
kOverwrite | 4 | Overwrite existing elements, if any |
Returned value
The copied Folder
object.
Example
You want to copy a Pictures folder from the resources folder to the data folder:
var userImages, copiedImages : 4D.Folder
userImages = folder("/SOURCES/Shared/Pictures/")
copiedImages = userImages.copyTo(folder("/DATA"),kOverwrite)
.create()
.create() : boolean
Parameter | Type | Description | |
---|---|---|---|
Result | boolean | ← | true if the folder was created successfully, false otherwise |
Description
The .create()
function creates a folder on disk according to the properties of the folder
object.
If necessary, the function creates the folder hierachy as described in the platformPath or path properties. If the folder already exists on disk, the function does nothing (no error is thrown) and returns false.
Returned value
- true if the folder is created successfully,
- false if a folder with the same name already exists or if an error occured.
Example 1
Create an empty folder in the database folder:
var created : boolean
created = folder("/PACKAGE/SpecialPrefs").create()
Example 2
Creation of the "/Archives2019/January/" folder in the database folder:
var newFolder : 4D.Folder
var info : string
newFolder = folder("/PACKAGE/Archives2019/January")
if(newFolder.create())
info = "The "+newFolder.name+" folder was created."
else
info = "Impossible to create a "+newFolder.name+" folder."
end
.createAlias()
.createAlias( destinationFolder : 4D.Folder , aliasName : string ) : 4D.File
Parameter | Type | Description | |
---|---|---|---|
destinationFolder | 4D.Folder | → | Destination folder for the alias or shortcut |
aliasName | string | → | Name of the symbolic link |
Result | 4D.File | ← | Alias or shortcut reference |
Description
The .createAlias()
function creates a symbolic link to the folder with the specified aliasName name in the folder designated by the destinationFolder object.
Pass the name of the symbolic link to create in the aliasName parameter.
Returned object
A 4D.File
object with the isAlias
property set to true.
Example
You want to create a symbolic link to an archive folder in your database folder:
var myFolder : 4D.Folder
myFolder = folder("/PACKAGE/Documents/Archives/2019/January")
aliasFile = myFolder.createAlias(folder("/PACKAGE"),"Jan2019")
.delete()
.delete( { option : integer } )
Parameter | Type | Description | |
---|---|---|---|
option | integer | → | folder deletion option |
Description
The .delete()
function deletes the folder.
By default, for security reasons, if you omit the option parameter, .delete( )
only allows empty folders to be deleted. If you want the command to be able to delete folders that are not empty, you must use the option parameter with one of the following constants:
Constant | Value | Comment |
---|---|---|
kDeleteOnlyIfEmpty | 0 | Deletes folder only when it is empty |
kDeleteWithContents | 1 | Deletes folder along with everything it contains |
When kDeleteOnlyIfEmpty
is passed or if you omit the option parameter:
- The folder is only deleted if it is empty, otherwise, the command does nothing and an error -47 is generated.
- If the folder does not exist, the error -120 is generated.
When kDeleteWithContents
is passed:
- The folder, along with all of its contents, is deleted. Warning: Even when this folder and/or its contents are locked or set to read-only, if the current user has suitable access rights, the folder (and contents) is still deleted.
- If this folder, or any of the files it contains, cannot be deleted, deletion is aborted as soon as the first inaccessible element is detected, and error -45 (The file is locked or the pathname is not correct) is returned. In this case, the folder may be only partially deleted. When deletion is aborted, you can use the
lastErrors
command to retrieve the name and path of the offending file. - If the folder does not exist, the command does nothing and no error is returned.
.exists
.exists : boolean
Description
The .exists
property returns true if the folder exists on disk, and false otherwise.
This property is read-only.
.extension
.extension : string
Description
The .extension
property returns the extension of the folder name (if any). An extension always starts with ".". The property returns an empty string if the folder name does not have an extension.
This property is read-only.
.file()
.file( path : string ) : 4D.File
Parameter | Type | Description | |
---|---|---|---|
path | string | → | Relative POSIX file pathname |
Result | 4D.File | ← | File object (null if invalid path) |
Description
The .file()
function creates a File
object inside the Folder
object and returns its reference.
In path, pass a relative POSIX path to designate the file to return. The path will be evaluated from the parent folder as root.
Returned value
A File
object or null if path is invalid.
Example
var myPDF : 4D.File
myPDF = folder("/DATA").file("Pictures/info.pdf")
.files()
.files( { options : integer } ) : collection
Parameter | Type | Description | |
---|---|---|---|
options | integer | → | File list options |
Result | collection | ← | collection of children file objects |
Description
The .files()
function returns a collection of File
objects contained in the folder.
Aliases or symbolic links are not resolved.
By default, if you omit the options parameter, only the files at the first level of the folder are returned in the collection, as well as invisible files or folders. You can modify this by passing, in the options parameter, one or more of the following constants:
Constant | Value | Comment |
---|---|---|
kRecursive | 1 | The collection contains files of the specified folder and its subfolders |
kIgnoreInvisible | 8 | Invisible files are not listed |
Returned value
Collection of file
objects.
Example 1
You want to know if there are invisible files in the project folder:
var all, noInvisible : collection
var info : string
all = folder("/PACKAGE").files()
noInvisible = folder("/PACKAGE").files(kIgnoreInvisible)
if(all.length != noInvisible.length)
info = "Project folder contains hidden files."
end
Example 2
You want to get all files that are not invisible in the Resources folder:
var recursive : collection
recursive = folder("/RESOURCES").files(kRecursive+kIgnoreInvisible)
.folder()
.folder( path : string ) : 4D.Folder
Parameter | Type | Description | |
---|---|---|---|
path | string | → | Relative POSIX file pathname |
Result | 4D.Folder | ← | Created folder object (null if invalid path) |
Description
The .folder()
function creates a folder
object inside the parent folder
object and returns its reference.
In path, pass a relative POSIX path to designate the folder to return. The path will be evaluated from the parent folder as root.
Returned value
A folder
object or null if path is invalid.
Example
var mypicts : 4D.Folder
mypicts = folder("/RESOURCES").folder("Pictures")
.folders()
.folders( { options : integer } ) : collection
Parameter | Type | Description | |
---|---|---|---|
options | integer | → | Folder list options |
Result | collection | ← | Collection of children folder objects |
Description
The .folders()
function returns a collection of folder
objects contained in the parent folder.
By default, if you omit the options parameter, only the folders at the first level of the folder are returned in the collection. You can modify this by passing, in the options parameter, one or more of the following constants:
Constant | Value | Comment |
---|---|---|
kRecursive | 1 | The collection contains folders of the specified folder and its subfolders |
kIgnoreInvisible | 8 | Invisible folders are not listed |
Returned value
collection of folder
objects.
Example
You want the collection of all folders and subfolders of the database folder:
var allFolders : collection
allFolders = folder("/PACKAGE").folders(kRecursive)
.fullName
.fullName : string
Description
The .fullName
property returns the full name of the folder, including its extension (if any).
This property is read-only.
.hidden
.hidden : boolean
Description
The .hidden
property returns true if the folder is set as "hidden" at the system level, and false otherwise.
This property is read-only.
.isAlias
.isAlias : boolean
Description
The .isAlias
property returns always false for a Folder
object.
This property is read-only.
.isFile
.isFile : boolean
Description
The .isFile
property returns always false for a folder.
This property is read-only.
.isFolder
.isFolder : boolean
Description
The .isFolder
property returns always true for a folder.
This property is read-only.
.isPackage
.isPackage : boolean
Description
The .isPackage
property returns true if the folder is a package on macOS (and exists on disk). Otherwise, it returns false.
On Windows, .isPackage
always returns false.
This property is read-only.
.modificationDate
.modificationDate : date
Description
The .modificationDate
property returns the date of the folder's last modification.
This property is read-only.
.modificationTime
.modificationTime : time
Description
The .modificationTime
property returns the time of the folder's last modification (expressed as a number of seconds beginning at 00:00).
This property is read-only.
.moveTo()
.moveTo( destinationFolder : 4D.Folder { , newName : string } ) : 4D.Folder
Parameter | Type | Description | |
---|---|---|---|
destinationFolder | 4D.Folder | → | Destination folder |
newName | string | → | Full name for the moved folder |
Result | 4D.Folder | ← | Moved folder |
Description
The .moveTo()
function moves or renames the folder
object (source folder) into the specified destinationFolder.
The destinationFolder must exist on disk, otherwise an error is generated.
By default, the folder retains its name when moved. If you want to rename the moved folder, pass the new full name in the newName parameter. The new name must comply with naming rules (e.g., it must not contain characters such as ":", "/", etc.), otherwise an error is returned.
Returned object
The moved folder
object.
Example
You want to move and rename a folder:
var tomove, tomove2 : 4D.Folder
tomove = folder("/SOURCES/Shared/Pictures")
tomove2 = tomove.moveTo(folder("/SOURCES/Shared/Archives"),"Pic_Archives")
.name
.name : string
Description
The .name
property returns the name of the folder, without extension (if any).
This property is read-only.
.original
.original : 4D.Folder
Description
The .original
property returns the same Folder object as the folder.
This property is read-only.
This property is available on folders to allow generic code to process folders or files.
.parent
.parent : 4D.Folder
Description
The .parent
property returns the parent folder object of the folder. If the path represents a system path (e.g., "/DATA/"), the system path is returned.
If the folder does not have a parent (root), the null value is returned.
This property is read-only.
.path
.path : string
Description
The .path
property returns the POSIX path of the folder. If the path represents a filesystem (e.g., "/DATA/"), the filesystem is returned.
This property is read-only.
.rename()
.rename( newName : string ) : 4D.Folder
Parameter | Type | Description | |
---|---|---|---|
newName | string | → | New full name for the folder |
Result | 4D.Folder | ← | Renamed folder |
Description
The .rename()
function renames the folder with the name you passed in newName and returns the renamed folder
object.
The newName parameter must comply with naming rules (e.g., it must not contain characters such as ":", "/", etc.), otherwise an error is returned. If a file with the same name already exists, an error is returned.
Returned object
The renamed folder
object.
Example
var toRename : 4D.Folder
toRename = folder("/SOURCES/Shared/Pictures").rename("Images")