FolderItem

From Xojo Documentation
Revision as of 18:35, 17 January 2012 by Dbrandt (Talk | contribs)

Jump to: navigation, search

Class (inherits from Object)

FolderItem class objects represent files, applications, or folders. They are created by calling a method such as GetFolderItem or via the Parent or Item properties of other FolderItem objects.


Properties
AbsolutePath ReadOnlyProperty.png IsWriteable ReadOnlyProperty.png Owner
Alias ReadOnlyProperty.png LastErrorCode ReadOnlyProperty.png Parent ReadOnlyProperty.png
Count ReadOnlyProperty.png Length ReadOnlyProperty.png Permissions
CreationDate Locked ResourceForkLength
Directory ReadOnlyProperty.png MacCreator ShellPath ReadOnlyProperty.png
DisplayName ReadOnlyProperty.png MacDirID Type ReadOnlyProperty.png
Exists ReadOnlyProperty.png MacType URLPath ReadOnlyProperty.png
ExtensionVisible MacVRefNum VirtualVolume
Group ModificationDate Visible
IsReadable ReadOnlyProperty.png Name


Methods
Child MacFSRef
CopyFileTo MoveFileTo
CreateAsFolder OpenAsMovie
CreateMovie OpenAsSound
CreateResourceFork OpenAsVectorPicture
CreateVirtualVolume OpenAsVirtualVolume
Delete OpenEditableMovie
GetRelative OpenResourceFork
GetSaveInfo OpenResourceMovie
Item TrueChild
Launch TrueItem


Shared Methods
CreateFromMacFSRef


Constructors

FolderItem.Constructor(path as String, PathType as Integer=PathTypeAbsolute)



Copy Constructor

Constructors

FolderItem.Constructor(f as FolderItem)




Class Constants

PathType

The following class constants can be used to specify the path type as the second parameter in the FolderItem constructor.

Class Constant Description
PathTypeAbsolute An absolute path.
PathTypeShell A shell path. On Windows, this is the short path. On Mac OS X and Linux, this is the POSIX path.
PathTypeURL A URL path. If you use PathTypeURL, the URL must begin with "file:///".

Notes

Specifying Pathnames

Use the Volume function, the Parent property of the FolderItem class, and the Child method of the FolderItem class to specify pathnames. The Volume function returns a reference to any volume on the user's computer. Pass it a number that indicates the desired volume. Zero is the boot volume. You can get the number of volumes with the VolumeCount function. For example, to get a FolderItem for Microsoft Word in the Program Files folder on the boot volume, you can use the following line of code (The line continuation keyword, [[_]], is used to split the line into two printed lines).

Dim f as FolderItem
f= Volume(0).Child("Program Files").Child("Microsoft Office"). _
Child("OFFICE11").Child("WINWORD.EXE")


The GetFolderItem function can be used to get a FolderItem for an item in the current directory (the directory that contains the application or the REAL Studio IDE if you are debugging the application). Simply pass it the name of the item. For example, the following returns a FolderItem for the directory "MyTemplates" in the current folder:

Dim f as FolderItem
f= GetFolderItem("MyTemplates")


If the document or directory does not exist, the Exists property of the FolderItem is False.

If you pass the empty string to GetFolderItem, it returns the FolderItem for the directory that contains the application.

Dim f as FolderItem
f= GetFolderItem("")


The Parent property of the FolderItem class enables you to navigate one level up in the hierarchy. For example, the following gives you the FolderItem for the directory that contains the directory that contains the application:

Dim f as FolderItem
f=GetFolderItem("").Parent


Mac OS X is based on BSD Unix which uses "/" as the separator. However, because Real Studio and all applications made with Real Studio are Carbon applications on Mac OS X, they continue to use ":" as the separator. The one exception is when accessing files via the Shell class. In this case, you would use the same separator that you use on the command line.

Shell Paths and Regular Paths

If you pass the optional parameter for path, you can also pass an optional second parameter indicating whether the path is a ShellPath, a "regular" path, or a path in the form of a URL. FolderItem has three class constants that you use to indicate this, PathTypeAbsolute, PathTypeURL, and PathTypeShell. For example:

Dim f as FolderItem
f=New FolderItem("/home/shr/mytextdoc.txt",FolderItem.PathTypeShell)


You cannot pass a non-absolute Shell path. Attempting to do so will result in an UnsupportedFormatException.

If you use PathTypeURL, the URL must begin with "file:///".

You can also create a FolderItem without passing any parameters. It works the same as passing an empty text string.


Aliases

If a FolderItem is actually an alias to a FolderItem, the alias is automatically resolved when the FolderItem is accessed unless you use TrueChild and TrueItem (Aliases for Win32 do not get resolved with Item and Child). They return the item itself, even if it is an alias. Use the Alias property to determine whether the FolderItem is an alias.

For more information on File Types, see the Chapter 9 - Working With Files in the User's Guide.

Movies

The OpenResourceMovie method allows you to get a movie stored in a MooV resource inside a file or application (Macintosh only). Prior to QuickTime 4.0, the actual movie in a QuickTime movie file was stored in a MooV resource. In QuickTime 4.0 (and above), the movie is stored in the data fork.


FolderItem Properties Example

The “Property List” example project in the Examples folder that ships with Real Studio is a simple utility that displays some of the properties of a selected FolderItem. The use chooses the FolderItem and the app displays the properties in a group of Labels.

The PushButton in the main window has the following Action event handler:

dim dlg as openDialog
dim f as folderitem

//The OpenDialog class will show a standard open dialog
dlg = new OpenDialog
dlg.filter="any"
f = dlg.showModal

//if the user clicked cancel, f will equal nil
//if it's not nil, then we can display its info

if f <> nil then
// display the information

//f.absolutePath-- Full path to the file as a string
absolutePathText.text=f.absolutePath

//f.creationDate-- Creation date as a Date class
creationDateText.text=f.creationDate.shortDate
//f.ModificationDate-- Modification date as a Date class
modificationDateText.text=f.modificationDate.shortDate

//f.displayName-- The name that is displayed to the user
// Only will be different if the extension is hid (OS X.1+)
displayNameText.text=f.displayName
//f.name-- The full name of the file
nameText.text=f.name

//f.length-- The length of the data fork
// (length is the size in bytes)
lengthText.text=str(f.length)
//f.resourceForkLength-- The length of the resourceFork
resourceForkLengthText.text=str(f.resourceForkLength)

//f.MacCreator-- The four character creator code
macCreatorText.text=f.macCreator
//f.MacType-- The four character type code
macTypeText.text=f.macType
//f.Type-- The type of the file as defined in the file types menu
typeText.text=f.type
end if



Mac OS

The Mac OS implementation of FolderItem uses the File Manager API. As a result, it may not be possible to create FolderItems for many BSD directories and files.

Examples

NOTE: You can find several example projects in Files folder inside the Examples folder next to your Real Studio application.  


This example puts the names of all the items on the Desktop that are stored on the boot volume into ListBox1.

Dim DesktopFolder as FolderItem = SpecialFolder.Desktop
If DesktopFolder is nil then
return
End if

dim count as Integer = DesktopFolder.Count
For i as Integer = 1 to count
Dim f as FolderItem = DesktopFolder.Item(i)
If f <> nil then
ListBox1.AddRow f.Name
End if
Next


This example uses MoveFileTo. The source file will be deleted and moved into the destination folder. The destination is specified as the root of Volume 0. The name of the destination file OPis the same as the source. Notice that it checks that the source file exists and the destination FolderItem is not Nil.

Dim f,g as FolderItem

f= GetOpenFolderItem(FileTypes1.Text)
If f<>Nil then //if the user didn't cancel..
If f.exists then //if it is a valid file...
g= Volume(0).Child(f.Name)
If g<> Nil then
f.MoveFileTo(g)
MsgBox "success!"
end if
end if
else
MsgBox "File not found!"
end if


The following example creates a text file, changes the Creator from the default creator of "R*ch" to "ttxt", and writes some data to the file.

Dim f as FolderItem
Dim stream as TextOutputStream
f=GetSaveFolderItem(FileTypes1.Text,"Daily Planet Staff.txt")
If f <> Nil then
stream=TextOutputStream.Create(f)
f.MacCreator="ttxt"
Stream.WriteLine ("Perry White")
Stream.WriteLine ("Lois Lane")
Stream.WriteLine ("Jimmy Olsen")
Stream.Close
End if


This example displays the Open File dialog box and lets the user choose a JPEG file that is then assigned to the Backdrop property of a Canvas control.

Dim f as FolderItem = GetOpenFolderItem(FileTypes1.Jpeg)
If f is Nil then
//user cancelled
return
End if

Canvas1.Backdrop = f.OpenAsPicture
If Canvas1.Backdrop is nil then
//check f.LastErrorCode
End if


This example displays an open-file dialog box that lets the user select a QuickTime movie. The QuickTime movie is then copied into the Movie property of a MoviePlayer control.

Dim f As FolderItem = GetOpenFolderItem(FileTypes1.Quicktime)
If f <> Nil then
MoviePlayer1.Movie=f.OpenAsMovie
If MoviePlayer1.Movie is nil then
//Check f.LastErrorCode
End if
Else
//user cancelled
End if


This example opens a file as an EditableMovie and displays it in a MoviePlayer. "VideoTypes" is a file type set and "QuickTime" specifies the QuickTime file type.

Dim f As FolderItem
Dim theEMovie as EditableMovie
f=GetOpenFolderItem(FileTypes1.Quicktime)
If f<>Nil and f.exists then
theEMovie=f.OpenEditableMovie
If theEMovie<> Nil then
ThePlayer.movie=theEMovie
End if
End if


This example copies all the files in a particular folder. The following code is a button's Action:

Dim origin, destination as FolderItem
origin=SelectFolder
If origin <> Nil then
destination=SelectFolder
If destination <> Nil then
CopyFileOrFolder origin, destination
MsgBox "Copy complete!"
end if
end if


The CopyFileorFolder method is as follows:

Sub CopyFileorFolder (source as FolderItem, destination as FolderItem)
Dim i as Integer
Dim newFolder as FolderItem

If source.directory then //it's a folder
newFolder=destination.child(source.name)
newFolder.createAsFolder
For i=1 to source.count //go through each item
If source.item(i).directory then
//it's a folder
CopyFileOrFolder source.item(i), newFolder //recursively call this routine passing it the folder
else
source.item(i).CopyFileTo newFolder //it's a file so copy it
end if
next
else //it's not a folder
source.CopyFileTo destination
end if


Using GetRelative:

Dim f,g as FolderItem
f=New FolderItem
g=f.GetRelative(f.GetSaveInfo(Volume(0).Child("Documents"),0))
If g<> Nil then
Label2.text=g.Absolutepath
Else
MsgBox "FolderItem does not exist!"
End if

See Also

GetFolderItem, GetOpenFolderItem, GetSaveFolderItem, SelectFolder, Volume, VolumeCount functions; BinaryStream, FolderItemDialog, OpenDialog, SaveAsDialog, SelectFolderDialog, SpecialFolder, TextInputStream, TextOutputStream classes.

Personal tools
Namespaces

Variants
Actions
Main
Documentation
Community
Toolbox
Help