FolderItem
From REALbasicWiki
| Overall article skill |  ✭ |
A FolderItem represents a file, directory, or volume.
[edit] More on methods
| |||||
|---|---|---|---|---|---|
| Available on |   
| ||||
| General | |||||
| Superclass | Object | ||||
| Interfaces | none | ||||
| Constants | |||||
| |||||
| Methods | |||||
| |||||
| Properties | |||||
| |||||
| Events | |||||
|
none | |||||
|
NOTE: You can get descriptions of the items above from the REALbasic documentation. | |||||
[edit] Function Child(Name as String) as FolderItem
For a directory f, f.Child returns a FolderItem representing an item in the directory f with the name passed to Child. This item may not actually exist.
If the item is an alias, Child resolves the alias before returning the FolderItem. To get the item without alias resolution, use TrueChild.
Child will return nil if f is not a directory, or if the user executing the code lacks permissions sufficient to access the directory.
Child supports some magic values:
- f.Child("") returns a FolderItem representing the directory itself.
- In Mac OS X and Linux f.Child(".") also returns the directory FolderItem, and f.Child("..") returns the parent of f.
Child does not resolve relative paths. For example
return DesktopFolder.Child("path:path")
should return Nil in MacOS because Child treats "path:path" as the name of a file in DesktopFolder, and : is an illegal file name character.
[edit] CopyFileTo
CopyFileTo will raise a NilObjectException if a nil FolderItem reference is passed in the Destination parameter.
[edit] Sub FolderItem()
The FolderItem created by this constructor points to the parent of the application (or application bundle for Mac OS X applications).
[edit] Sub FolderItem(path as String, pathType as Integer = 0)
If the constructor cannot create a FolderItem using the path and path type, it raises an UnsupportedFormatException. Note that PathTypeURL requires a file:// URL, and the URL must be absolute.
[edit] Sub FolderItem(f as FolderItem)
This constructor creates a new FolderItem pointing to the same item as f. If f is nil, the constructor raises a NilObjectException.
[edit] Function TrueChild(Name as String) as FolderItem
When called on a directory, TrueChild returns the FolderItem with the passed name. Unlike Child, it does not follow an alias or symlink. Otherwise, the behavior is the same as Child.
[edit] Sub Delete()
If the FolderItem is a file, Delete() permanently deletes the file or folder. You will get an error when trying this on a folder which is not empty. Note that the file is really deleted and not simply moved to the trash.
| If you want to list the files from a folder and delete some files, you absolutely should read Delete files from a folder. |
[edit] Function GetSaveInfo( relativeTo as FolderItem, Mode as integer = 0) as string
Allows you to store a reference to a file. relativeTo may be nil if you want an absolute reference to the FolderItem.
[edit] MoveFileTo
MoveFileTo will raise a NilObjectException if a nil FolderItem reference is passed to it.
[edit] Properties
[edit] ModificationDate as Date
If the Exists property is false, ModificationDate returns a Date object with TotalSeconds = 0 (Tested in REALbasic 2007r3/Mac OS X, Linux) Assigning Nil to the ModificationDate property is a no-op. (Tested in REALbasic 2007r3/Mac OS X)
[edit] Parent as FolderItem
This read-only property returns the directory containing the FolderItem. The parent of the root directory is nil. REALbasic is, however, not entirely consistent. In Mac OS X, for example, suppose you have a second mounted volume, say a CD. Then Volume(1) returns a FolderItem whose parent is nil. But there is only one root directory, and that is the FolderItem GetFolderItem("/", FolderItem.PathTypeShell). If we call this FolderItem root, then root.Child(Volume(1).Name) returns a FolderItem representing the same item as Volume(1), but whose parent is root.
[edit] Permissions as Integer
In Mac OS X and Linux applications, you can get permissions for files and directories, and set permissions if allowed. Permission values are represented as three-digit octal integers. The first digit controls owner permissions; the second digit controls group permissions; the third digit controls permissions for others. The bits of each digit are interpreted as follows.
- bit 2 (value 4): read permission
- bit 1 (value 2): write permission
- bit 0 (value 1): execute permission
There is also a fourth digit that controls setuid, setgid, and sticky bit permissions. For more information, see the documentation for the Unix command chmod or the Wikipedia article.
To set permissions for a file to read-write access for owner, and read access for everyone else, use the following code.
f.Permissions = &o644
You can only set permissions for a FolderItem that exists.
Note: in Mac OS X 10.4 and later, and on Linux, access control lists may override permissions.
[edit] Tips
[edit] Using the Close method
See Don't Close Stream Objects for more details.
In short: The issue is that if you close a stream (file) you end up with an unusable object, and no way to tell that the object is unusable:
BinaryStream, etc. do not raise any sort of error if you attempt to read or write from a closed stream, nor can you test to see whether the stream is still open. So if you call Close at the wrong time, you will have a hard time tracking down any resulting problems.
Therefore, make sure that you won't access the stream object after closing it, e.g. by setting its reference to nil (as a side effect, if the stream object gets destroyed because there are no more references to it, it will close the file automatically).
[edit] Don't assign MacType and MacCreator until after you've closed the file
You can't set the creator if the file doesn't exist yet, but you also shouldn't be setting it while the file is still open. RB sets the file type and creator of text files for you, but they don't document whether they do this upon opening or closing, so to be safe, just wait till you've closed it to set it yourself.
