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

java.lang.Object
  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. The options include setting a start path so the user is presented first with files in that specific location. It also includes providing a string filter to match the files.

Sample Usage

To get the file picker and display the user interface:

 final FilePicker filePicker = FilePicker.getInstance();
 filePicker.show();
 

To specify a URL start path for the file selection UI:

 String startPath = "file:///store/home/user/documents/";
 filePicker.setPath(startPath);
 

To specify a file filter:

 String filterString = "jpg";
 filePicker.setFilter(filterString);
 

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.
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 deafult 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.

Parameters:

filterString - The filter string is 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".

Since:

BlackBerry API 5.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. The caller should ensure that the path exists before sending it to this function.

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 deafult title of a media screen (such as "Select Picture").

Parameters:

title - the custom dialog title overriding the default one. The value of null restores the deafult dialog title.

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