Folder

Folder objects are created with the Folder command. Ils contiennent des références à des dossiers qui peuvent exister réellement ou non sur le disque. 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.

Exemple

L'exemple suivant crée un dossier "JohnSmith" :

Form.curfolder:=Folder(fk database folder)
Form.curfolder:=Folder("C:\\Users\\JohnSmith\\";fk platform path)

Chemins d'accès

Folder objects support several pathnames, including filesystems or posix syntax. Supported pathnames are detailed in the Pathnames page.

Objet Folder

.copyTo( destinationFolder : 4D.Folder { ; newName : Text } { ; 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 : Text { ; aliasType : Integer } ) : 4D.File creates an alias (macOS) or a shortcut (Windows)
.creationDate : Date the creation date of the folder
.creationTime : Time the creation time of the folder
.delete( { option : Integer } ) deletes the folder
.exists : Boolean true if the folder exists on disk
.extension : Text returns the extension of the folder name (if any)
.file( path : Text ) : 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 : Text ) : 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 : Text returns the full name of the folder, including its extension (if any)
.getIcon( { size : Integer } ) : Picture returns the icon of the folder
.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 : Text 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 : Text the POSIX path of the folder
.platformPath : Text the path of the folder expressed with the current platform syntax
.moveTo( destinationFolder : 4D.Folder { ; newName : Text } ) : 4D.Folder moves or renames the Folder object (source folder) into the specified destinationFolder
.rename( newName : Text ) : 4D.Folder renames the folder with the name you passed in newName and returns the renamed Folder object

Folder

Historique

Release	Modifications
19 R8	Support of fk home folder
17 R5	Ajout

Folder ( path : Text { ; pathType : Integer }{ ; * } ) : 4D.Folder
Folder ( folderConstant : Integer { ; * } ) : 4D.Folder

Paramètres	Type		Description
path	Text	->	Chemin du dossier
folderConstant	Integer	->	Constante de dossier 4D
pathType	Integer	->	fk posix path (default) or fk platform path
-		->	* pour retourner le dossier de la base hôte
Résultat	4D.Folder	<-	Nouvel objet dossier

Description

The Folder command creates and returns a new object of the 4D.Folder type. La commande accepte deux syntaxes :

Folder ( path { ; pathType } { ; * } )

In the path parameter, pass a folder path string. Vous pouvez utiliser une chaine personnalisée ou un "filesystem" (ex : "/DATA").

Only absolute pathnames are supported with the Folder command.

Par défaut, 4D attend un chemin exprimé avec la syntaxe POSIX. If you work with platform pathnames (Windows or macOS), you must declare it using the pathType parameter. Les constantes suivantes sont disponibles :

Constante	Valeur	Commentaire
fk platform path	1	Chemin exprimé dans une syntaxe spécifique à la plate-forme (obligatoire en cas de chemin de plate-forme)
fk posix path	0	Chemin exprimé avec la syntaxe POSIX (par défaut)

Folder ( folderConstant { ; * } )

In the folderConstant parameter, pass a 4D built-in or system folder, using one of the following constants:

Constante	Valeur	Commentaire
fk applications folder	116
fk data folder	9	Filesystem associé : "/DATA"
fk database folder	4	Filesystem associé : "/PACKAGE"
fk desktop folder	115
fk documents folder	117	Dossier Documents de l'utilisateur
fk home folder	118	Current home folder of the user (usually /Users/<username>/)
fk licenses folder	1	Dossier contenant les fichiers de licence 4D de la machine
fk logs folder	7	Filesystem associé : "/LOGS"
fk mobileApps folder	10
fk remote database folder	3	Dossier de la base de données 4D créé sur chaque machine 4D distante
fk resources folder	6	Filesystem associé : "/RESOURCES"
fk system folder	100
fk user preferences folder	0	Dossier 4D qui stocke les fichiers de préférences de l'utilisateur dans le dossier personnel de l'utilisateur
fk web root folder	8	Dossier racine web courant du projet : "/PACKAGE/chemin" si son emplacement se trouve dans le package, sinon chemin complet

If the command is called from a component, pass the optional parameter to get the path of the host database. Otherwise, if you omit the parameter, a null object is always returned.

On Windows, in merged clients, the location of built-in folders is modified if the ShareLocalResourcesOnWindowsClient BuildApp key is used.

4D.Folder.new()

Historique

Release	Modifications
18 R6	Ajout

4D.Folder.new ( path : Text { ; pathType : Integer }{ ; * } ) : 4D.Folder
4D.Folder.new ( folderConstant : Integer { ; * } ) : 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 of 4D.Folder.new().

.copyTo()

Historique

Release	Modifications
17 R5	Ajout

.copyTo( destinationFolder : 4D.Folder { ; newName : Text } { ; overwrite : Integer } ) : 4D.Folder

Paramètres	Type		Description
dossierDestination	4D.Folder	->	Dossier de destination
nouveauNom	Text	->	Nom de la copie
overwrite	Integer	->	fk overwrite to replace existing elements
Résultat	4D.Folder	<-	Dossier copié

Description

The .copyTo() function copies the Folder object into the specified destinationFolder.

The destinationFolder must exist on disk, otherwise an error is generated.

Par défaut, le dossier est copié avec le nom du dossier original. If you want to rename the copy, pass the new name in the newName parameter. Le nouveau nom doit être conforme aux règles de nommage (ex : il ne doit pas contenir de caractères tels que ":", "/", etc.), sinon une erreur est retournée.

If a folder with the same name already exists in the destinationFolder, by default 4D generates an error. You can pass the fk overwrite constant in the overwrite parameter to ignore and overwrite the existing file

Constante	Valeur	Commentaire
fk overwrite	4	Écrase les éléments existants, le cas échéant

Valeur retournée

The copied Folder object.

Exemple

You want to copy a Pictures folder from the user's Document folder to the Database folder:

var $userImages; $copiedImages : 4D.Folder
$userImages:=Folder(fk documents folder).folder("Pictures")
$copiedImages:=$userImages.copyTo(Folder(fk database folder);fk overwrite)

.create()

Historique

Release	Modifications
17 R5	Ajout

.create() : Boolean

Paramètres	Type		Description
Résultat	Boolean	<-	Vrai si le dossier a été créé avec succès, sinon Faux

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. Si le dossier existe déjà sur disque, la fonction ne fait rien (aucune erreur n'est générée) et retourne faux.

Valeur retournée

• True if the folder is created successfully;
• False if a folder with the same name already exists or if an error occured.

Exemple 1

Créer un dossier vide dans le dossier principal :

var $created : Boolean
$created:=Folder("/PACKAGE/SpecialPrefs").create()

Exemple 2

Création d'un dossier "/Archives2019/January/" dans le dossier principal :

$newFolder:=Folder("/PACKAGE/Archives2019/January")
If($newFolder.create())
 ALERT("The "+$newFolder.name+" folder was created.")
Else
 ALERT("Impossible to create a "+$newFolder.name+" folder.")
End if

.createAlias()

Historique

Release	Modifications
17 R5	Ajout

.createAlias( destinationFolder : 4D.Folder ; aliasName : Text { ; aliasType : Integer } ) : 4D.File

Paramètres	Type		Description
dossierDestination	4D.Folder	->	Dossier de destination pour l'alias ou le raccourci
aliasName	Text	->	Nom de l'alias ou du raccourci
aliasType	Integer	->	Type de lien de l'alias
Résultat	4D.File	<-	Référence de l'alias ou du raccourci du dossier

Description

The .createAlias() function creates an alias (macOS) or a shortcut (Windows) to the folder with the specified aliasName name in the folder designated by the destinationFolder object.

Pass the name of the alias or shortcut to create in the aliasName parameter.

Par défaut sur macOS, la fonction crée un alias standard. You can also create a symbolic link by using the aliasType parameter. Les constantes suivantes sont disponibles :

Constante	Valeur	Commentaire
fk alias link	0	Lien alias (macOS uniquement)(par défaut)
fk symbolic link	1	Lien symbolique (macOS uniquement)

On Windows, a shortcut (.lnk file) is always created (the aliasType parameter is ignored).

Returned object

A 4D.File object with the isAlias property set to true.

Exemple

Vous souhaitez créer un alias pour un dossier d'archives dans votre dossier principal :

$myFolder:=Folder("C:\\Documents\\Archives\\2019\\January";fk platform path)
$aliasFile:=$myFolder.createAlias(Folder("/PACKAGE");"Jan2019")

.creationDate

Historique

Release	Modifications
17 R5	Ajout

.creationDate : Date

Description

The .creationDate property returns the creation date of the folder.

Cette propriété est en lecture seule.

.creationTime

Historique

Release	Modifications
17 R5	Ajout

.creationTime : Time

Description

The .creationTime property returns the creation time of the folder (expressed as a number of seconds beginning at 00:00).

Cette propriété est en lecture seule.

.delete()

Historique

Release	Modifications
17 R5	Ajout

.delete( { option : Integer } )

Paramètres	Type		Description
option	Integer	->	Option de suppression du dossier

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. Si vous souhaitez que la commande supprime des dossiers qui ne sont pas vides, vous devez utiliser le paramètre option avec l'une des constantes suivantes :

Constante	Valeur	Commentaire
Delete only if empty	0	Supprime le dossier uniquement s'il est vide
Delete with contents	1	Supprime le dossier ainsi que son éventuel contenu

When Delete only if empty is passed or if you omit the option parameter:

• Le dossier n'est supprimé que s'il est vide ; sinon, la commande ne fait rien et une erreur -47 est générée.
• Si le dossier n'existe pas, l'erreur -120 est générée.

When Delete with contents is passed:

• Le dossier, ainsi que tout son contenu, est supprimé. 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.
• Si ce dossier, ou l'un des fichiers qu'il contient, ne peut être supprimé, la suppression est interrompue dès que le premier élément inaccessible est détecté, et une erreur(*) est retournée. Dans ce cas, le dossier ne peut être que partiellement supprimé. When deletion is aborted, you can use the GET LAST ERROR STACK command to retrieve the name and path of the offending file.
• Si le dossier n'existe pas, la commande ne fait rien et aucune erreur n'est retournée. (*) Windows: -54 (Attempt to open locked file for writing) macOS: -45 (The file is locked or the pathname is not correct)

.exists

Historique

Release	Modifications
17 R5	Ajout

.exists : Boolean

Description

The .exists property returns true if the folder exists on disk, and false otherwise.

Cette propriété est en lecture seule.

.extension

Historique

Release	Modifications
17 R5	Ajout

.extension : Text

Description

The .extension property returns the extension of the folder name (if any). Une extension commence toujours par ".". La propriété retourne une chaîne vide si le nom du dossier n'a pas d'extension.

Cette propriété est en lecture seule.

.file()

Historique

Release	Modifications
17 R5	Ajout

.file( path : Text ) : 4D.File

Paramètres	Type		Description
path	Text	->	Chemin POSIX relatif
Résultat	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. Le chemin sera évalué à partir du dossier parent en tant que racine.

Valeur retournée

A File object or null if path is invalid.

Exemple

var $myPDF : 4D.File
$myPDF:=Folder(fk documents folder).file("Pictures/info.pdf")

.files()

Historique

Release	Modifications
17 R5	Ajout

.files( { options : Integer } ) : Collection

Paramètres	Type		Description
options	Integer	->	Options de liste de fichiers
Résultat	Collection	<-	Collection d'objets dossier enfant

Description

The .files() function returns a collection of File objects contained in the folder.

Les alias ou les liens symboliques ne sont pas résolus.

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:

Constante	Valeur	Commentaire
fk recursive	1	La collection contient les fichiers du dossier spécifié ainsi que de ses sous-dossiers
fk ignore invisible	8	Les fichiers invisibles ne sont pas répertoriés

Valeur retournée

Collection of File objects.

Exemple 1

Vous souhaitez savoir s'il y a des fichiers invisibles dans le dossier de la base :

 var $all; $noInvisible : Collection
 $all:=Folder(fk database folder).files()
 $noInvisible:=Folder(fk database folder).files(fk ignore invisible)
 If($all.length#$noInvisible.length)
    ALERT("Database folder contains hidden files.")
 End if

Exemple 2

Vous souhaitez lire tous les fichiers qui ne sont pas invisibles dans le dossier Documents :

 var $recursive : Collection
 $recursive:=Folder(fk documents folder).files(fk recursive+fk ignore invisible)

.folder()

Historique

Release	Modifications
17 R5	Ajout

.folder( path : Text ) : 4D.Folder

Paramètres	Type		Description
path	Text	->	Chemin POSIX relatif
Résultat	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. Le chemin sera évalué à partir du dossier parent en tant que racine.

Valeur retournée

A Folder object or null if path is invalid.

Exemple

 var $mypicts : 4D.Folder
 $mypicts:=Folder(fk documents folder).folder("Pictures")

.folders()

Historique

Release	Modifications
17 R5	Ajout

.folders( { options : Integer } ) : Collection

Paramètres	Type		Description
options	Integer	->	Options de liste des dossiers
Résultat	Collection	<-	Collection d'objets dossier enfant

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:

Constante	Valeur	Commentaire
fk recursive	1	La collection contient les dossiers du dossier spécifié ainsi que de ses sous-dossiers
fk ignore invisible	8	Les dossiers invisibles ne sont pas répertoriés

Valeur retournée

Collection of Folder objects.

Exemple

Vous souhaitez obtenir la collection de tous les dossiers et sous-dossiers du dossier de la base :

 var $allFolders : Collection
 $allFolders:=Folder("/PACKAGE").folders(fk recursive)

.fullName

Historique

Release	Modifications
17 R5	Ajout

.fullName : Text

Description

The .fullName property returns the full name of the folder, including its extension (if any).

Cette propriété est en lecture seule.

.getIcon()

Historique

Release	Modifications
17 R5	Ajout

.getIcon( { size : Integer } ) : Picture

Paramètres	Type		Description
size	Integer	->	Longueur du côté de l'image retournée (pixels)
Résultat	Picture	<-	Icône

Description

The .getIcon() function returns the icon of the folder.

The optional size parameter specifies the dimensions in pixels of the returned icon. Cette valeur représente la longueur latérale du côté du carré contenant l'icône. La taille des icônes est généralement de 32x32 pixels (“grandes icônes”) ou de 16x16 pixels (“petites icônes”). Si vous passez 0 ou si vous omettez ce paramètre, la version "grandes icônes" est retournée.

Si le dossier n'existe pas sur disque, une icône vide est retournée par défaut.

Valeur retournée

Folder icon picture.

.hidden

Historique

Release	Modifications
17 R5	Ajout

.hidden : Boolean

Description

The .hidden property returns true if the folder is set as "hidden" at the system level, and false otherwise.

Cette propriété est en lecture seule.

.isAlias

Historique

Release	Modifications
17 R5	Ajout

.isAlias : Boolean

Description

The .isAlias property returns always false for a Folder object.

Cette propriété est en lecture seule.

.isFile

Historique

Release	Modifications
17 R5	Ajout

.isFile : Boolean

Description

The .isFile property returns always false for a folder.

Cette propriété est en lecture seule.

.isFolder

Historique

Release	Modifications
17 R5	Ajout

.isFolder : Boolean

Description

The .isFolder property returns always true for a folder.

Cette propriété est en lecture seule.

.isPackage

Historique

Release	Modifications
17 R5	Ajout

.isPackage : Boolean

Description

The .isPackage property returns true if the folder is a package on macOS (and exists on disk). Sinon, elle retourne false.

On Windows, .isPackage always returns false.

Cette propriété est en lecture seule.

.modificationDate

Historique

Release	Modifications
17 R5	Ajout

.modificationDate : Date

Description

The .modificationDate property returns the date of the folder's last modification.

Cette propriété est en lecture seule.

.modificationTime

Historique

Release	Modifications
17 R5	Ajout

.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).

Cette propriété est en lecture seule.

.moveTo()

Historique

Release	Modifications
17 R5	Ajout

.moveTo( destinationFolder : 4D.Folder { ; newName : Text } ) : 4D.Folder

Paramètres	Type		Description
dossierDestination	4D.Folder	->	Dossier de destination
nouveauNom	Text	->	Nom complet du dossier déplacé
Résultat	4D.Folder	<-	Dossier déplacé

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.

Par défaut, le dossier garde le même nom lorsqu'il est déplacé. If you want to rename the moved folder, pass the new full name in the newName parameter. Le nouveau nom doit être conforme aux règles de nommage (ex : il ne doit pas contenir de caractères tels que ":", "/", etc.), sinon une erreur est retournée.

Returned object

The moved Folder object.

Exemple

Vous souhaitez déplacer et renommer un dossier :

 var $tomove; $moved : Object
 $docs:=Folder(fk documents folder)
 $tomove:=$docs.folder("Pictures")
 $tomove2:=$tomove.moveTo($docs.folder("Archives");"Pic_Archives")

.name

Historique

Release	Modifications
17 R5	Ajout

.name : Text

Description

The .name property returns the name of the folder, without extension (if any).

Cette propriété est en lecture seule.

.original

Historique

Release	Modifications
17 R5	Ajout

.original : 4D.Folder

Description

The .original property returns the same Folder object as the folder.

Cette propriété est en lecture seule.

Cette propriété est disponible sur les dossiers pour permettre au code générique de traiter les dossiers ou les fichiers.

.parent

Historique

Release	Modifications
17 R5	Ajout

.parent : 4D.Folder

Description

The .parent property returns the parent folder object of the folder. Si le chemin représente un filesystem (ex : "/DATA/"), le filesystem est retourné.

Si le dossier n'a pas de parent (racine), la valeur nulle est retournée.

Cette propriété est en lecture seule.

.path

Historique

Release	Modifications
17 R5	Ajout

.path : Text

Description

The .path property returns the POSIX path of the folder. Si le chemin représente un filesystem (ex : "/DATA/"), le filesystem est retourné.

Cette propriété est en lecture seule.

.platformPath

Historique

Release	Modifications
17 R5	Ajout

.platformPath : Text

Description

The .platformPath property returns the path of the folder expressed with the current platform syntax.

Cette propriété est en lecture seule.

.rename()

Historique

Release	Modifications
17 R5	Ajout

.rename( newName : Text ) : 4D.Folder

Paramètres	Type		Description
nouveauNom	Text	->	Nouveau nom complet du dossier
Résultat	4D.Folder	<-	Dossier renommé

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. S'il existe déjà un fichier portant le même nom, une erreur est retournée.

Returned object

The renamed Folder object.

Exemple

 var $toRename : 4D.Folder
 $toRename:=Folder("/RESOURCES/Pictures").rename("Images")