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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.