net.rim.device.api.ui.picker
Class FilePicker

java.lang.Object
  extended by net.rim.device.api.ui.picker.FilePicker

public abstract class FilePicker
extends Object

A user interface component for picking a file.

This API can support various options for selecting files.

Sample Usage

To display a generic file picker:

 final FilePicker filePicker = FilePicker.getInstance();
 filePicker.setView(VIEW_ALL);
 String selectedPath = filePicker.show();
 

To specify a start path:

 String startPath = "file:///store/home/user/documents/";
 filePicker.setPath(startPath);
 selectedPath = filePicker.show();
 filePicker.setPath(null); // Reset the path to default if needed
 

To filter by a file extension:

 String filterString = ".doc";
 filePicker.setFilter(filterString);
 selectedPath = filePicker.show();
 filePicker.setFilter(null); // Reset the filter if needed
 

To display music files but exclude those that contain DRM technologies (forward locked):

 filePicker.setTitle("Select my music");    // Set custom title
 filePicker.setView(VIEW_MUSIC);
 filePicker.excludeDRMForwardLocked(true);
 selectedPath = filePicker.show();
 filePicker.excludeDRMForwardLocked(false); // Reset the DRM filter if needed
 filePicker.setTitle(null);                 // Reset the title if needed 
 

Since:
BlackBerry API 5.0.0

Nested Class Summary
static interface FilePicker.Listener
          Defines the functionality of a listener for when the user has selected a file.
 
Field Summary
static int VIEW_ALL
          Generic file selection dialog type (like File Explorer).
static int VIEW_MUSIC
          File selection dialog type for selecting music files (like a Music application).
static int VIEW_PICTURES
          File selection dialog type for selecting pictures (like a Pictures application).
static int VIEW_RINGTONES
          File selection dialog type for selecting ringtones (like a Ring Tones application).
static int VIEW_VIDEOS
          File selection dialog type for selecting videos (like a Video application).
static int VIEW_VOICE_NOTES
          File selection dialog type for selecting voice notes (Like a Voice Notes application).
 
Method Summary
abstract  void cancel()
          Removes the view of the file picker.
abstract  void excludeDRMForwardLocked(boolean exclude)
          Sets a filter for DRM forward locked files.
static FilePicker getInstance()
          Returns a file picker.
abstract  void setFilter(String filterString)
          Sets the filter that is used to reduce the set of files presented to the user.
abstract  void setListener(FilePicker.Listener listener)
          Sets a listener for the user selecting a path.
abstract  void setPath(String defaultPath)
          Sets the full URL path that will be initially displayed to the user upon presentation of the picker, for example "file:///store/home/user/documents/".
abstract  void setTitle(String title)
          Sets the custom title of the file selection dialog, overrides the default title of a media screen (such as "Select Picture").
abstract  void setView(int view)
          Sets the view of the file selection dialog based on the currently supported Media application views.
abstract  String show()
          Displays the File selection popup and returns the full URL encoded path to the selected file.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

VIEW_ALL

public static final int VIEW_ALL
Generic file selection dialog type (like File Explorer).

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VIEW_PICTURES

public static final int VIEW_PICTURES
File selection dialog type for selecting pictures (like a Pictures application).

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VIEW_RINGTONES

public static final int VIEW_RINGTONES
File selection dialog type for selecting ringtones (like a Ring Tones application).

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VIEW_VIDEOS

public static final int VIEW_VIDEOS
File selection dialog type for selecting videos (like a Video application).

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VIEW_MUSIC

public static final int VIEW_MUSIC
File selection dialog type for selecting music files (like a Music application).

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VIEW_VOICE_NOTES

public static final int VIEW_VOICE_NOTES
File selection dialog type for selecting voice notes (Like a Voice Notes application).

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0


Method Detail

cancel

public abstract void cancel()
Removes the view of the file picker.

Since:
BlackBerry API 5.0.0

getInstance

public static final FilePicker getInstance()
Returns a file picker. By default, the path is the root, and there is no filter.

Returns:
The instance of FilePicker.
Since:
BlackBerry API 5.0.0

setFilter

public abstract void setFilter(String filterString)
Sets the filter that is used to reduce the set of files presented to the user. You can set multiple filters by separating each filter by a colon (:). For example:
 FilePicker filePicker = FilePicker.getInstance();
 filePicker.setListener(_listener);
 filePicker.setView(FilePicker.VIEW_ALL);
 filePicker.setFilter(".doc:.xls:.ppt");
 filePicker.setPath("file:///SDCard/BlackBerry/documents/");
 filePicker.show());
 

Parameters:
filterString - The filter string used to reduce the set of files presented to the user. To present only files with the extension of jpg for example, enter a filter string of ".jpg". To set multiple filters, separate each filter with a :. If null, the filter is reset.
Since:
BlackBerry API 5.0.0

excludeDRMForwardLocked

public abstract void excludeDRMForwardLocked(boolean exclude)
Sets a filter for DRM forward locked files.

Parameters:
exclude - If true, DRM forward locked files are excluded from the picker display. If false, DRM forward locked files are included in the picker display. By default, DRM forward locked files are included in the picker.
Since:
BlackBerry API 7.0.0

setListener

public abstract void setListener(FilePicker.Listener listener)
Sets a listener for the user selecting a path. When the user accepts or cancels the dialog, the listener class is called.

Parameters:
listener - The listener that will receive notifications from this picker.
Since:
BlackBerry API 5.0.0

setPath

public abstract void setPath(String defaultPath)
Sets the full URL path that will be initially displayed to the user upon presentation of the picker, for example "file:///store/home/user/documents/".

Parameters:
defaultPath - The default path is the location on the filesystem that will be initially displayed to the user upon presentation of the dialog. If the path does not exist, the root of the device will be presented. If null, the filter is reset to the default file system root path.
Since:
BlackBerry API 5.0.0

setView

public abstract void setView(int view)
Sets the view of the file selection dialog based on the currently supported Media application views.

Parameters:
view - Type of the file selection dialog view, such as VIEW_ALL, VIEW_PICTURES, VIEW_RINGTONES, VIEW_MUSIC, VIEW_VIDEOS, VIEW_VOICE_NOTES.
Since:
BlackBerry API 6.0.0

setTitle

public abstract void setTitle(String title)
Sets the custom title of the file selection dialog, overrides the default title of a media screen (such as "Select Picture").

Parameters:
title - The custom dialog title overriding the default one. If null, the title is reset to the default.
Since:
BlackBerry API 6.0.0

show

public abstract String show()
Displays the File selection popup and returns the full URL encoded path to the selected file. The function will block until a file is selected or the selection process is cancelled. The function will return null if the user cancels.

Returns:
the fully qualified URL encoded path to the file selected, for example "file:///store/home/user/documents/MyDoc.doc"
Since:
BlackBerry API 5.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal