Folder

Folder objects are created with the Folder command. Contêm referências a pastas que podem ou não existir efectivamente no disco. 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.

Exemplo

O exemplo seguinte cria uma pasta "JohnSmith":

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

Pathnames

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

Objecto 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

História

Release	Mudanças
19 R8	Support of fk home folder
17 R5	Adicionado

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

Parâmetro	Tipo		Descrição
path	Text	->	Folder path
folderConstant	Integer	->	Constante Pasta 4D
pathType	Integer	->	fk posix path (default) or fk platform path
-		->	* para devolver a pasta da base de dados do anfitrião
Resultados	4D. Folder	<-	Novo Objeto Folder

Descrição

The Folder command creates and returns a new object of the 4D.Folder type. O comando aceita duas sintaxes:

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

In the path parameter, pass a folder path string. Pode utilizar uma string personalizada ou um sistema de arquivos (por exemplo, "/DATA").

Only absolute pathnames are supported with the Folder command.

Como padrão, 4D espera um caminho expresso com a sintaxe POSIX. If you work with platform pathnames (Windows or macOS), you must declare it using the pathType parameter. Estão disponíveis as seguintes constantes:

Parâmetros	Valor	Comentário
fk platform path	1	Caminho expresso com uma sintaxe específica da plataforma (obrigatória em caso de caminho de plataforma)
fk posix path	0	Caminho expresso com a sintaxe POSIX (por padrão)

Folder ( folderConstant { ; * } )

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

Parâmetros	Valor	Comentário
fk applications folder	116
fk data folder	9	Sistema de ficheiros associado: "/DATA"
fk database folder	4	Sistema de arquivos associado: "/PACKAGE"
fk desktop folder	115
fk documents folder	117	Pasta de documentos do utilizador
fk home folder	118	Current home folder of the user (usually /Users/<username>/)
fk licenses folder	1	Pasta contendo os arquivos de licença 4D da máquina
fk logs folder	7	Sistema de arquivos associado: "/LOGS"
fk mobileApps folder	10
fk remote database folder	3	Pasta de base de dados 4D criada em cada máquina 4D remota
fk resources folder	6	Sistema de arquivos associado: "/DATA"
fk system folder	100
fk user preferences folder	0	4D folder that stores user preference files within the \<userName> directory.
fk web root folder	8	Pasta raiz atual da Web da base de dados: se estiver dentro do pacote "/PACKAGE/percurso", caso contrário, caminho completo

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

História

Release	Mudanças
18 R6	Adicionado

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

Descrição

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

História

Release	Mudanças
17 R5	Adicionado

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

Parâmetro	Tipo		Descrição
destinationFolder	4D. Folder	->	Pasta de destino
newName	Text	->	Nome para a copia
overwrite	Integer	->	fk overwrite to replace existing elements
Resultados	4D. Folder	<-	Pasta ou arquivo copiado

Descrição

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

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

Como padrão, a pasta é copiada com o nome da pasta original. If you want to rename the copy, pass the new name in the newName parameter. O novo nome deve cumprir com as regras de nomenclatura (por exemplo, não deve conter caracteres como ":", "/", etc.), do contrário se devolve um erro.

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

Parâmetros	Valor	Comentário
fk overwrite	4	Sobrescrever os elementos existentes, se houver

Valor retornado

The copied Folder object.

Exemplo

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

História

Release	Mudanças
17 R5	Adicionado

.create() : Boolean

Parâmetro	Tipo		Descrição
Resultados	Parâmetros	<-	True se a pasta foi criada com sucesso, false caso contrário

Descrição

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. Se a pasta já existir no disco, a função não faz nada (não é atirado nenhum erro) e retorna falso.

Valor retornado

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

Exemplo 1

Criar uma pasta vazia na pasta da base de dados:

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

Exemplo 2

Criação da pasta "/Arquivos2019/Janeiro/" na pasta da base de dados:

$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()

História

Release	Mudanças
17 R5	Adicionado

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

Parâmetro	Tipo		Descrição
destinationFolder	4D. Folder	->	Pasta de destino para o pseudónimo ou atalho
aliasName	Text	->	Nome do pseudónimo ou atalho
aliasType	Integer	->	Tipo de ligação do pseudónimo
Resultados	4D. File	<-	Alias ou referência de atalho

Descrição

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.

Por padrão em macOS, a função cria um pseudónimo padrão. You can also create a symbolic link by using the aliasType parameter. Estão disponíveis as seguintes constantes:

Parâmetros	Valor	Comentário
fk alias link	0	Alias link (padrão)
fk symbolic link	1	Link simbólico (só em macOS)

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.

Exemplo

Deseja criar um pseudónimo para uma pasta de arquivo na sua pasta de base de dados:

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

.creationDate

História

Release	Mudanças
17 R5	Adicionado

.creationDate : Date

Descrição

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

This property is read-only.

.creationTime

História

Release	Mudanças
17 R5	Adicionado

.creationTime : Time

Descrição

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

This property is read-only.

.delete()

História

Release	Mudanças
17 R5	Adicionado

.delete( { option : Integer } )

Parâmetro	Tipo		Descrição
option	Integer	->	Opção de eliminação de pasta

Descrição

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. Se quiser que o comando possa apagar pastas que não estejam vazias, deve utilizar o parâmetro de opção com uma das seguintes constantes:

Parâmetros	Valor	Comentário
Delete only if empty	0	Elimina a pasta apenas quando está vazia
Delete with contents	1	Apaga a pasta juntamente com tudo o que a mesma contém

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

• A pasta só é apagada se estiver vazia; caso contrário, o comando não faz nada e é gerado um erro -47.
• Se a pasta não existir, o erro -120 é gerado.

When Delete with contents is passed:

• A pasta, juntamente com todo o seu conteúdo, é apagada. 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.
• Se esta pasta, ou qualquer dos arquivos que conter, não puder ser apagada, a eliminação é abortada assim que o primeiro elemento inacessível for detectado, e um erro(*) é devolvido. Neste caso, a pasta pode ser apenas parcialmente apagada. When deletion is aborted, you can use the GET LAST ERROR STACK command to retrieve the name and path of the offending file.
• Se a pasta não existir, o comando não faz nada e nenhum erro é devolvido. (*) Windows: -54 (Attempt to open locked file for writing) macOS: -45 (The file is locked or the pathname is not correct)

.exists

História

Release	Mudanças
17 R5	Adicionado

.exists : Boolean

Descrição

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

This property is read-only.

.extension

História

Release	Mudanças
17 R5	Adicionado

.extension : Text

Descrição

The .extension property returns the extension of the folder name (if any). Uma extensão sempre começa com ".". Uma extensão sempre começa com "." A propriedade devolve uma string vazia se o nome da pasta não tiver extensão.

This property is read-only.

.file()

História

Release	Mudanças
17 R5	Adicionado

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

Parâmetro	Tipo		Descrição
path	Text	->	Rota POSIX relativa
Resultados	4D. File	<-	File object (null if invalid path)

Descrição

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. A rota se avaliará a partir da pasta pai como raíz.

Valor retornado

A File object or null if path is invalid.

Exemplo

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

.files()

História

Release	Mudanças
17 R5	Adicionado

.files( { options : Integer } ) : Collection

Parâmetro	Tipo		Descrição
options	Integer	->	Opções da lista de arquivos
Resultados	Collection	<-	Coleção de objetos de arquivo filho

Descrição

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

Os apelidos ou links simbolicos não são resolvidos.

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:

Parâmetros	Valor	Comentário
fk recursive	1	A coleção contém arquivos da pasta especificada e suas subpastas
fk ignore invisible	8	Arquivos invisíveis não estão listados

Valor retornado

Collection of File objects.

Exemplo 1

Se quiser saber se há arquivos invisíveis na pasta Database:

 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

Exemplo 2

Se quiser obter todos os arquivos que não são invisíveis na pasta Documents:

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

.folder()

História

Release	Mudanças
17 R5	Adicionado

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

Parâmetro	Tipo		Descrição
path	Text	->	Rota POSIX relativa
Resultados	4D. Folder	<-	Created folder object (null if invalid path)

Descrição

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. A rota se avaliará a partir da pasta pai como raíz.

Valor retornado

A Folder object or null if path is invalid.

Exemplo

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

.folders()

História

Release	Mudanças
17 R5	Adicionado

.folders( { options : Integer } ) : Collection

Parâmetro	Tipo		Descrição
options	Integer	->	Opções da lista de pasta
Resultados	Collection	<-	Coleção de objetos de pasta filho

Descrição

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:

Parâmetros	Valor	Comentário
fk recursive	1	A coleção contém pastas da pasta especificada e suas subpastas
fk ignore invisible	8	Pastas invisíveis não estão listados

Valor retornado

Collection of Folder objects.

Exemplo

Se quiser a coleção de todas as pastas e subpastas da pasta database:

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

.fullName

História

Release	Mudanças
17 R5	Adicionado

.fullName : Text

Descrição

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

This property is read-only.

.getIcon()

História

Release	Mudanças
17 R5	Adicionado

.getIcon( { size : Integer } ) : Picture

Parâmetro	Tipo		Descrição
size	Integer	->	Longitude de lado da imagem devolvida (píxeles)
Resultados	Imagem	<-	Ícone

Descrição

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

The optional size parameter specifies the dimensions in pixels of the returned icon. Este valor representa em realidade a longitude do lado do quadrado que contém o icone. Icones são geralmente definidos como 32x32 píxels ('icones grandes') ou 16x16 ('icones pequenos'). Se passar 0 ou omitir este parâmetro, se devolve a versão 'icone grande'

Se a pasta não existir no disco, se devolve um icone vazio como padrão.

Valor retornado

Folder icon picture.

.hidden

História

Release	Mudanças
17 R5	Adicionado

.hidden : Boolean

Descrição

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

História

Release	Mudanças
17 R5	Adicionado

.isAlias : Boolean

Descrição

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

This property is read-only.

.isFile

História

Release	Mudanças
17 R5	Adicionado

.isFile : Boolean

Descrição

The .isFile property returns always false for a folder.

This property is read-only.

.isFolder

História

Release	Mudanças
17 R5	Adicionado

.isFolder : Boolean

Descrição

The .isFolder property returns always true for a folder.

This property is read-only.

.isPackage

História

Release	Mudanças
17 R5	Adicionado

.isPackage : Boolean

Descrição

The .isPackage property returns true if the folder is a package on macOS (and exists on disk). .

On Windows, .isPackage always returns false.

This property is read-only.

.modificationDate

História

Release	Mudanças
17 R5	Adicionado

.modificationDate : Date

Descrição

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

This property is read-only.

.modificationTime

História

Release	Mudanças
17 R5	Adicionado

.modificationTime : Time

Descrição

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

História

Release	Mudanças
17 R5	Adicionado

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

Parâmetro	Tipo		Descrição
destinationFolder	4D. Folder	->	Pasta de destino
newName	Text	->	Nome completo para a pasta movida
Resultados	4D. Folder	<-	Pasta movida

Descrição

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.

Por padrão, a pasta mantém o seu nome quando movida. If you want to rename the moved folder, pass the new full name in the newName parameter. O novo nome deve cumprir com as regras de nomenclatura (por exemplo, não deve conter caracteres como ":", "/", etc.), do contrário se devolve um erro.

Returned object

The moved Folder object.

Exemplo

Quer mover-se e renomear uma pasta:

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

.name

História

Release	Mudanças
17 R5	Adicionado

.name : Text

Descrição

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

This property is read-only.

.original

História

Release	Mudanças
17 R5	Adicionado

.original : 4D.Folder

Descrição

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

This property is read-only.

Esta propriedade está disponible nas pastas para permitir que o código genérico processe pastas ou arquivos.

.parent

História

Release	Mudanças
17 R5	Adicionado

.parent : 4D.Folder

Descrição

The .parent property returns the parent folder object of the folder. .

Se a pasta não tiver um pai (raiz), é devolvido o valor nulo.

This property is read-only.

.path

História

Release	Mudanças
17 R5	Adicionado

.path : Text

Descrição

The .path property returns the POSIX path of the folder. .

This property is read-only.

.platformPath

História

Release	Mudanças
17 R5	Adicionado

.platformPath : Text

Descrição

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

This property is read-only.

.rename()

História

Release	Mudanças
17 R5	Adicionado

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

Parâmetro	Tipo		Descrição
newName	Text	->	Novo nome completo para a pasta
Resultados	4D. Folder	<-	Renomeado arquivo

Descrição

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. Se já existir um ficheiro com o mesmo nome, é devolvido um erro.

Returned object

The renamed Folder object.

Exemplo

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