Difference between revisions of "GetOpenFolderItem"

From Xojo Documentation

(Examples)
 
m (Text replacement - "{{Deprecated|" to "{{DeprecatedItem|")
 
(30 intermediate revisions by 8 users not shown)
Line 1: Line 1:
 +
{{DeprecatedItem|version=2019r2|replacement=[[FolderItem.ShowOpenFileDialog]]}}
 +
{{SupportedPlatforms |type=d}}
 +
{{MethodBox
 +
| name=GetOpenFolderItem
 +
| platform=all
 +
| parameters=filter As [[String]]
 +
| returntype=[[FolderItem]]
 +
| owner=global
 +
| scope=global
 +
}}
 +
{{Description
 +
|text = Prompts the user to select a file using the standard open-file dialog box.}}
  
 
+
== Usage ==
=='''Description'''==
+
''result'' = '''GetOpenFolderItem'''(''filter'')
Used to access a document or application selected by the user via the standard open-file dialog box.
+
{| class="genericTable"
 
+
! width=15% | Part
 
+
! width=15% | Type
 
+
! width=55% | Description
=='''Syntax'''==
 
result='''GetOpenFolderItem'''(filter)
 
{| cellpadding="8" cellspacing="0" border="1"  
 
 
 
! width=25% style="background-color:#e0e0e0" | Part
 
 
 
! width=15% style="background-color:#e0e0e0" | Type
 
 
 
! width=55% style="background-color:#e0e0e0" | Description
 
 
|-
 
|-
 
|result
 
|result
 
+
|[[FolderItem]]
|[[FolderItem|FolderItem]]
+
|Represents the file that was opened by the user. The ''result'' will be [[Nil]] if the user clicked the Cancel button.
|Represents the file that was opened by the user. The ''result'' will be [[Nil|Nil]] if the user clicked the Cancel button.
 
 
 
 
|-
 
|-
 
|filter
 
|filter
 
+
|[[String]]
|[[String|String]]
 
 
|Semicolon separated list of file types the user can open.  
 
|Semicolon separated list of file types the user can open.  
The file types must be defined as REALbasic file types, either in the IDE in a File Type Set or with the [[FileType|FileType]] class.
+
The file types must be defined as file types in your project, either in the IDE in a File Type Set or with the [[FileType]] class.
 
 
 
|-
 
|-
 
|}
 
|}
  
 +
==Notes==
 +
The '''GetOpenFolderItem''' function displays the standard open-file dialog box for the platform on which the application is running. The [[FolderItemDialog]] class has the same purpose but allows for some customization.
  
=='''Notes'''==
+
The'' filter'' parameter is used to limit the types of files that the user can open to one or more of the file types defined via the [[FileType]] class or in the File Type Sets Editor in the IDE. The ''filter'' is a semicolon-separated list of file type names. For example, if you wanted the user to be able to open only text files and postscript files when making a particular call to the '''GetOpenFolderItem''' function, you would define two file types using either the File Type Sets Editor or the [[FileType]] class. You would then pass "application/text; application/postscript" (or the name you chose) as the filter to the '''GetOpenFolderItem''' function.
The '''GetOpenFolderItem''' function displays the standard open-file dialog box for the platform on which the REALbasic application is running. The [[FolderItemDialog|FolderItemDialog]] class has the same purpose but allows for some customization.
 
  
The filter parameter is used to limit the types of files that the user can open to one or more of the file types defined via the [[FileType|FileType]] class or in the File Type Sets Editor in the IDE. The filter is a semicolon separated list of file type names. For example, if you wanted the user to be able to open only text files and postscript files when making a particular call to the '''GetOpenFolderItem''' function, you would define two file types using either the File Type Sets Editor or the [[FileType|FileType]] class. You would then pass "application/text; application/postscript" (or the name you chose) as the filter to the '''GetOpenFolderItem''' function.
+
Only files whose type matches one of the file types passed in the filter will be displayed in the open file dialog box. If you want to display all files, you will need to add a file type to the project that uses "????" as its Mac Type.
  
Only files whose type matches one of the file types passed in the filter will be displayed in the open file dialog box. If you want to display all files, you will need to add a file type to the project that uses "????" as its Mac Type.  
+
You can also pass in actual FileType names; they are converted to their corresponding strings.
  
The '''GetOpenFolderItem''' function returns a [[FolderItem|FolderItem]] that represents the file the user selected. You can then use the [[FolderItem|FolderItem]] to access various data about the file such as its name, full path, etc. See the [[FolderItem|FolderItem]] class for more information.  
+
The '''GetOpenFolderItem''' function returns a [[FolderItem]] that represents the file the user selected. You can then use the [[FolderItem]] to access various data about the file such as its name, full path, etc. See the [[FolderItem]] class for more information.  
  
If the user clicks the Cancel button in the open file dialog box, the [[FolderItem|FolderItem]] will be [[Nil|Nil]]. You can test for this by comparing the [[FolderItem|FolderItem]] with the [[Nil|Nil]] value. Accessing a [[Nil|Nil]] [[FolderItem|FolderItem]] will cause a [[NilObjectException|NilObjectException]] error.  
+
If the user clicks the Cancel button in the open file dialog box, the [[FolderItem]] will be [[Nil]]. You can test for this by comparing the [[FolderItem]] with the [[Nil]] value. Accessing a [[Nil]] [[FolderItem]] will cause a [[NilObjectException]] error.
  
 +
== Sample Code ==
 +
This code opens an mp4 file and then opens its movie and assigns it to a [[MoviePlayer]] control. The file type was added using the File Types Editor as a custom Common File Type.
 +
<rbcode>
 +
Dim f As FolderItem
 +
Dim m As New Movie
  
 +
f = GetOpenFolderItem("video/mp4")
 +
If f<> Nil Then
 +
  m = f.OpenResourceMovie(1)
 +
Else
 +
  MsgBox("Open failed.")
 +
End If
 +
</rbcode>
  
=='''Examples'''==
+
This code illustrates how to use the [[FileType]] class do specify the types of files that can be opened by '''GetOpenFolderItem'''. When you define [[FileType]] objects, you must specify the MacType and Extensions properties. The call to '''GetOpenFolderItem''' can combine several FileTypes in the way the example shows.
This example illustrates how to use the [[FileType|FileType]] class do specify the types of files that can be opened by '''GetOpenFolderItem'''. When you define [[FileType|FileType]] objects, you must specify the MacType and Extensions properties. The call to '''GetOpenFolderItem''' can combine several FileTypes in the way the example shows.
+
<rbcode>
<div style="background-color:#d0d0d0; padding-left:30px">[[Dim|Dim]] jpegType as [[New|New]] '''FileType'''<br /></div>
+
Dim jpegType As New FileType
<div style="background-color:#d0d0d0; padding-left:30px">jpegType.Name = "image/jpeg"   <br /></div>
+
jpegType.Name = "image/jpeg"
<div style="background-color:#d0d0d0; padding-left:30px">jpegType.MacType = "JPEG"   <br /></div>
+
jpegType.MacType = "JPEG"
<div style="background-color:#d0d0d0; padding-left:30px">jpegType.Extensions = "jpg;jpeg" <br /></div>
+
jpegType.Extensions = "jpg;jpeg"
<div style="background-color:#d0d0d0; padding-left:30px">    <br /></div>
 
<div style="background-color:#d0d0d0; padding-left:30px">[[Dim|Dim]] pngType As [[New|New]] '''FileType'''  <br /></div>
 
<div style="background-color:#d0d0d0; padding-left:30px">pngType.Name = "image/png"  <br /></div>
 
<div style="background-color:#d0d0d0; padding-left:30px">pngType.MacType = "PNG "  <br /></div>
 
<div style="background-color:#d0d0d0; padding-left:30px">pngType.Extensions = "png" <br /></div>
 
<div style="background-color:#d0d0d0; padding-left:30px">    <br /></div>
 
<div style="background-color:#d0d0d0; padding-left:30px">[[Dim|Dim]] f As [[FolderItem|FolderItem]]  <br /></div>
 
<div style="background-color:#d0d0d0; padding-left:30px"><br /></div>
 
<div style="background-color:#d0d0d0; padding-left:30px">//using the addition and conversion operators...<br /></div>
 
<div style="background-color:#d0d0d0; padding-left:30px">f ='''GetOpenFolderItem'''( jpegType + pngType )<br /></div>
 
  
 +
Dim pngType As New FileType
 +
pngType.Name = "image/png"
 +
pngType.MacType = "PNG "
 +
pngType.Extensions = "png"
 +
 +
Dim f As FolderItem
 +
 +
// The actual FileTypes are converted to strings automatically for use
 +
// with GetOpenFolderItem
 +
f = GetOpenFolderItem( jpegType + pngType )
 +
</rbcode>
  
 
In the IDE you can create file types for practically all types using the Common File Types button in the File Type Sets editor. It displays a pop-up menu of the most common types and a "More" button that displays a much larger pop-up. Instead of creating your file types in code, you can use the Common File Types feature to set these properties.  
 
In the IDE you can create file types for practically all types using the Common File Types button in the File Type Sets editor. It displays a pop-up menu of the most common types and a "More" button that displays a much larger pop-up. Instead of creating your file types in code, you can use the Common File Types feature to set these properties.  
  
The following example uses the built-in file type for WMV movies to open a WMV file, assign the movie to the Movie property of a MoviePlayer, and plays the movie.
+
The following code uses the built-in file type for WMV movies to open a WMV file, assign the movie to the Movie property of a MoviePlayer, and plays the movie.
<div style="background-color:#d0d0d0; padding-left:30px">[[Dim|Dim]] f as [[FolderItem|FolderIem]]<br /></div>
+
<rbcode>
<div style="background-color:#d0d0d0; padding-left:30px">f='''GetOpenFolderItem'''(FileTypes1.VideoXMsWmv)<br /></div>
+
Dim f As FolderIem
<div style="background-color:#d0d0d0; padding-left:30px">[[If|If]] f &lt;&gt; [[Nil|Nil]] then<br /></div>
+
f = GetOpenFolderItem(FileTypes1.VideoXMsWmv) // Converts FileType1.VideoXMsWmv to a string
<div style="background-color:#d0d0d0; padding-left:45px">[[MoviePlayer|MoviePlayer1]].Movie=f.OpenAsMovie<br /></div>
+
If f <> Nil Then
<div style="background-color:#d0d0d0; padding-left:45px">[[MoviePlayer|MoviePlayer1]].Play<br /></div>
+
  MoviePlayer1.Movie = f.OpenAsMovie
<div style="background-color:#d0d0d0; padding-left:30px">End if<br /></div>
+
  MoviePlayer1.Play
 
+
End If
=='''See Also'''==
+
</rbcode>
[[GetSaveFolderItem|GetSaveFolderItem]], [[SelectFolder|SelectFolder]] functions; [[FileType|FileType]], [[FolderItem|FolderItem]], [[FolderItemDialog|FolderItemDialog]] classes.
 
  
 +
==See Also==
 +
[[GetSaveFolderItem]], [[SelectFolder]] functions; [[FileType]], [[FolderItem]], [[FolderItemDialog]], [[OpenDialog]].
  
[[Category:Dialogs]]
+
[[Category:Files_Dialogs]]
[[Category:OS]]
+
[[Category:Files_Input/Output]]
 +
[[Category:Desktop]]

Latest revision as of 19:05, 3 September 2020


Global Method

GetOpenFolderItem(filter As String) As FolderItem

Supported for all project types and targets.

Prompts the user to select a file using the standard open-file dialog box.

Usage

result = GetOpenFolderItem(filter)

Part Type Description
result FolderItem Represents the file that was opened by the user. The result will be Nil if the user clicked the Cancel button.
filter String Semicolon separated list of file types the user can open.

The file types must be defined as file types in your project, either in the IDE in a File Type Set or with the FileType class.

Notes

The GetOpenFolderItem function displays the standard open-file dialog box for the platform on which the application is running. The FolderItemDialog class has the same purpose but allows for some customization.

The filter parameter is used to limit the types of files that the user can open to one or more of the file types defined via the FileType class or in the File Type Sets Editor in the IDE. The filter is a semicolon-separated list of file type names. For example, if you wanted the user to be able to open only text files and postscript files when making a particular call to the GetOpenFolderItem function, you would define two file types using either the File Type Sets Editor or the FileType class. You would then pass "application/text; application/postscript" (or the name you chose) as the filter to the GetOpenFolderItem function.

Only files whose type matches one of the file types passed in the filter will be displayed in the open file dialog box. If you want to display all files, you will need to add a file type to the project that uses "????" as its Mac Type.

You can also pass in actual FileType names; they are converted to their corresponding strings.

The GetOpenFolderItem function returns a FolderItem that represents the file the user selected. You can then use the FolderItem to access various data about the file such as its name, full path, etc. See the FolderItem class for more information.

If the user clicks the Cancel button in the open file dialog box, the FolderItem will be Nil. You can test for this by comparing the FolderItem with the Nil value. Accessing a Nil FolderItem will cause a NilObjectException error.

Sample Code

This code opens an mp4 file and then opens its movie and assigns it to a MoviePlayer control. The file type was added using the File Types Editor as a custom Common File Type.

Dim f As FolderItem
Dim m As New Movie

f = GetOpenFolderItem("video/mp4")
If f<> Nil Then
m = f.OpenResourceMovie(1)
Else
MsgBox("Open failed.")
End If

This code illustrates how to use the FileType class do specify the types of files that can be opened by GetOpenFolderItem. When you define FileType objects, you must specify the MacType and Extensions properties. The call to GetOpenFolderItem can combine several FileTypes in the way the example shows.

Dim jpegType As New FileType
jpegType.Name = "image/jpeg"
jpegType.MacType = "JPEG"
jpegType.Extensions = "jpg;jpeg"

Dim pngType As New FileType
pngType.Name = "image/png"
pngType.MacType = "PNG "
pngType.Extensions = "png"

Dim f As FolderItem

// The actual FileTypes are converted to strings automatically for use
// with GetOpenFolderItem
f = GetOpenFolderItem( jpegType + pngType )

In the IDE you can create file types for practically all types using the Common File Types button in the File Type Sets editor. It displays a pop-up menu of the most common types and a "More" button that displays a much larger pop-up. Instead of creating your file types in code, you can use the Common File Types feature to set these properties.

The following code uses the built-in file type for WMV movies to open a WMV file, assign the movie to the Movie property of a MoviePlayer, and plays the movie.

Dim f As FolderIem
f = GetOpenFolderItem(FileTypes1.VideoXMsWmv) // Converts FileType1.VideoXMsWmv to a string
If f <> Nil Then
MoviePlayer1.Movie = f.OpenAsMovie
MoviePlayer1.Play
End If

See Also

GetSaveFolderItem, SelectFolder functions; FileType, FolderItem, FolderItemDialog, OpenDialog.