FilePicker

Since: BlackBerry 10.0.0

#include <bb/cascades/pickers/FilePicker>

To link against this class, add the following line to your .pro file: LIBS += -lbbcascadespickers

Allows the user to select a file or select a name and location for saving a file.

The FilePicker class in Picker mode allows the user to traverse the folder hierarchy to select a file. The application invoking the FilePicker can provide the types of the files that are allowed and in the case of multiple file types, the default file type.

The application invoking the FilePicker can also provide a custom filter and/or the directory that FilePicker displays when it opens. This overrides the filter and folders associated with the file type. The filter is a list of string patterns that supports wildcards. For example, if the filter string is "*.jpg", FilePicker lists files where the file has an extension of ".jpg".

The user can click a file to make a selection, or press the Cancel button. In the first case, FilePicker emits the fileSelected() signal and closes. If the user presses the Cancel button, FilePicker emits the canceled() signal before closing. In addition FilePicker emits error () signal and closes if it encounters an error that forces it to close.

FilePicker can be opened in Saver mode. In this mode, the application invoking the FilePicker can provide the file type of content and the default name and location to save the content to. FilePicker displays the content of the default folder associated with the file type. The user can change the location and/or default name.

FilePicker supports two view modes - List view and Grid view. The view mode is chosen based on the selected file type to display the content in the best possible way. For example, pictures and videos are displayed as a grid and documents are displayed as a list. While viewing, the user can toggle between list and grid view modes. The application can specify the view mode that FilePicker uses for display. This overrides the default view mode.

The default view in the FilePicker is the content on the local device. However, the user can access sources other than on the local device, for example, Cloud services, USB, and so on.

In QML, you must prefix the absolute file path of an external resource with file:// or your app won't be able to access the resource. File paths returned from FilePicker must be prefixed with file:// to be used as an absolute path to ImageView or MediaPlayer.

The following example creates a FilePicker in Picker mode with a file type of Picture:

       FilePicker* filePicker = new FilePicker();
       filePicker->setType(FileType::Picture);
       filePicker->setTitle("Select Picture");
       filePicker->setMode(FilePickerMode::Picker);
       filePicker->open();

       // Connect the fileSelected() signal with the slot.
       QObject::connect(filePicker, 
           SIGNAL(fileSelected(const QStringList&)), 
           this, 
           SLOT(onFileSelected(const QStringList&)));
 
       // Connect the canceled() signal with the slot.
       QObject::connect(filePicker, 
           SIGNAL(canceled()), 
           this, 
           SLOT(onCanceled()));

The above example creates a FilePicker and sets the title as "Select Picture". FilePicker initially displays the contents of folders associated with the file type Picture, e.g. /accounts/1000/shared/photos, and displays only files that match the Picture file type.

The following example creates a FilePicker in Saver mode with a file type of Document.

 FilePicker* filePicker = new FilePicker(FileType::Document, 0, 
     QStringList(), QStringList(), QStringList("ImportantDoc.doc"));
 filePicker->setMode(FilePickerMode::Saver);
 filePicker->open();

In the above example, FilePicker displays the contents of the folder associated with the file type Document and displays the default file name, "ImportantDoc.doc". The user can change the name or location and click the save button to return to the application.

In Saver mode, the user can either click the Cancel Button or the Save Button. In the first case, FilePicker emits the fileSelected() signal and closes, returning control back to the calling application. If the user clicks the Cancel button, FilePicker emits the canceled() signal before closing.

Here is example of using FilePicker in QML:

   import bb.cascades.pickers 1.0

       Page {
           content: Container {
               Button {
                   text: "FilePicker from QML"
                   onClicked: {
                       filePicker.open()
                   }
               }
           }
           attachedObjects: [
               FilePicker {
                   id:filePicker
                   type : FileType.Picture
                   title : "Select Picture"
                   directories : ["/accounts/1000/shared/misc"]
                   onFileSelected : {
                       console.log("FileSelected signal received : " + selectedFiles);

                       //make sure to prepend "file://" when using as a source for an ImageView or MediaPlayer
                       myImageView.imageSource = "file://" + selectedFiles[0];

                   }
               }
           ]
       }


Overview

QML properties

allowOverwrite: bool
defaultSaveFileNames: QStringList
defaultType: bb::cascades::pickers::FileType::Types
directories: QStringList
filter: QStringList
imageCropEnabled: bool
mode: bb::cascades::pickers::FilePickerMode::Type
perimeter: bb::system::SecurityPerimeter::Type
sortBy: bb::cascades::pickers::FilePickerSortFlag::Type
sortOrder: bb::cascades::pickers::FilePickerSortOrder::Type
sourceRestriction: bb::cascades::pickers::FilePickerSourceRestriction::Type
title: QString
type: bb::cascades::pickers::FileType::Types
viewMode: bb::cascades::pickers::FilePickerViewMode::Type

Public Functions Index

FilePicker (QObject *parent=0)
FilePicker (FileType::Types fileType, FileType::Types defaultFileType, const QStringList &filterList, const QStringList &directories, const QStringList &defaultSaveFileNames, QObject *parent=0)
virtual PRIVATE~FilePicker ()
PRIVATE PRIVATE *boolallowOverwrite () const
Q_SLOT voidclose ()
QStringListdefaultSaveFileNames () const
bb::cascades::pickers::FileType::TypesdefaultType () const
QStringListdirectories () const
QStringListfilter () const
boolisImageCropEnabled () const
bb::cascades::pickers::FilePickerMode::Typemode () const
Q_SLOT voidopen ()
bb::system::SecurityPerimeter::Typeperimeter () const
QStringListselectedFiles ()
voidsetAllowOverwrite (bool overwrite)
voidsetDefaultSaveFileNames (const QStringList &defaultSaveName)
voidsetDefaultType (bb::cascades::pickers::FileType::Types fileType)
voidsetDirectories (const QStringList &directories)
voidsetFilter (const QStringList &filter)
voidsetImageCropEnabled (bool imageCrop)
voidsetMode (bb::cascades::pickers::FilePickerMode::Type mode)
voidsetPerimeter (bb::system::SecurityPerimeter::Type perimeter)
voidsetSortBy (bb::cascades::pickers::FilePickerSortFlag::Type sortBy)
voidsetSortOrder (bb::cascades::pickers::FilePickerSortOrder::Type order)
voidsetSourceRestriction (bb::cascades::pickers::FilePickerSourceRestriction::Type mode)
voidsetTitle (const QString &title)
voidsetType (bb::cascades::pickers::FileType::Types fileType)
voidsetViewMode (bb::cascades::pickers::FilePickerViewMode::Type mode)
bb::cascades::pickers::FilePickerSortFlag::TypesortBy () const
bb::cascades::pickers::FilePickerSortOrder::TypesortOrder () const
bb::cascades::pickers::FilePickerSourceRestriction::TypesourceRestriction () const
QStringtitle () const
bb::cascades::pickers::FileType::Typestype () const
bb::cascades::pickers::FilePickerViewMode::TypeviewMode () const

Signals Index

voidallowOverwriteChanged (bool allowOverwrite)
voidcanceled ()
voiddefaultSaveFileNamesChanged (const QStringList &newSaveFileNames)
voiddefaultTypeChanged (bb::cascades::pickers::FileType::Types newDefaultType)
voiddirectoriesChanged (const QStringList &newDirectories)
voiderror (bb::cascades::pickers::FilePickerError::Type error)
voidfileSelected (const QStringList &selectedFiles)
voidfilterChanged (const QStringList &newFilter)
voidimageCropEnabledChanged (bool enable)
voidmodeChanged (bb::cascades::pickers::FilePickerMode::Type newMode)
voidperimeterChanged (bb::system::SecurityPerimeter::Type perimeter)
voidperimeterChanged (int perimeter)
voidpickerClosed ()
voidpickerOpened ()
voidsortByChanged (bb::cascades::pickers::FilePickerSortFlag::Type newSortBy)
voidsortOrderChanged (bb::cascades::pickers::FilePickerSortOrder::Type newSortOrder)
voidsourceRestrictionChanged (bb::cascades::pickers::FilePickerSourceRestriction::Type newSourceRestriction)
voidtitleChanged (const QString &newTitle)
voidtypeChanged (bb::cascades::pickers::FileType::Types newType)
voidviewModeChanged (bb::cascades::pickers::FilePickerViewMode::Type newViewMode)

Properties

bool allowOverwrite

Indicates whether FilePicker will append a number to the file name to make it unique in Saver mode.

Since:

BlackBerry 10.0.0

QStringList defaultSaveFileNames

The name of one or more files in Saver or SaverMultiple mode.

In Saver mode, FilePicker takes the first one from this list as the default file name. This default file name can be changed in FilePicker.

In SaverMultiple mode, the application can provide a list of file names.

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FileType::Types defaultType

Represents the default file type if multiple file types are specified in FilePicker.

Since:

BlackBerry 10.0.0

QStringList directories

The application invoking FilePicker can provide the list of directories where the files are most likely to be found.

In Picker mode, these directories are added to list of associated folders. In Saver mode, the FilePicker will navigate to the first directory in the list.

Since:

BlackBerry 10.0.0

QStringList filter

The files in the FilePicker will be filtered based on this filter.

Since:

BlackBerry 10.0.0

bool imageCropEnabled

Indicates whether to enable image cropping in the FilePicker.

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FilePickerMode::Type mode

Determines the mode of the FilePicker.

FilePicker can be opened in Picker or Saver mode. By default, FilePicker opens in Picker mode.

Since:

BlackBerry 10.0.0

bb::system::SecurityPerimeter::Type perimeter

Indicates the security perimeter for the FilePicker.

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FilePickerSortFlag::Type sortBy

Determines the attribute to sort the content in the FilePicker.

By default, FilePicker choose the sort flag based on the file type.

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FilePickerSortOrder::Type sortOrder

Determines the sort order for the content in the FilePicker.

By default, FilePicker choose the sort order based on the file type.

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FilePickerSourceRestriction::Type sourceRestriction

Determines which sources FilePicker displays.

By default, FilePicker displays all sources.

Since:

BlackBerry 10.2.0

QString title

The title for the FilePicker.

This is displayed on the title bar of the FilePicker

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FileType::Types type

Represents the type of file that can be viewed in the FilePicker.

FileType determines the filter, sort order, and view mode in the FilePicker.

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FilePickerViewMode::Type viewMode

Determines whether FilePicker displays the content in a list view or a grid view.

By default, FilePicker chooses the ViewMode based on the file type. For example, pictures are displayed in grid view.

Since:

BlackBerry 10.0.0

Public Functions

FilePicker (

Constructs a FilePicker in Picker mode.

By default, the contents of the root folder based on application perimeter will be displayed, e.g. /accounts/1000/shared

      FilePicker* FilePicker = new FilePicker();
Parameters
parent

The parent or 0. If not 0, the ownership of constructed FilePicker will be transferred to parent.

Since:

BlackBerry 10.0.0

FilePicker (

Constructs a FilePicker with the file type of the file to select.

In Picker mode, the application can provide multiple file types. For a single file type, FilePicker displays the aggregated view of folders associated with file type. The contents of the directory are filtered based on the type provided. If multiple file types are provided, FilePicker opens up by default, to the aggregated view of folders associated with the default file type

 // For a single type
      FilePicker* FilePicker = new FilePicker(FileType::Picture, 0, QStringList(), QStringList(), QStringList());

 // For multiple types
      FilePicker* FilePicker = new FilePicker(FileType::Picture | FileType::Video, FileType::Picture, QStringList(), QStringList(), QStringList() );

In the above example, the application provided two file types,Picture and Video, with Picture as the default type. FilePicker will show a drop down with two entries, Picture and Video, and Picture will be selected by default. If the user chooses any of the other file types, the view will be updated to display the folders associated with the selected file type.

The application can provide a list of directories that FilePicker can use for picking or saving files. In this case, the FilePicker will add these directories to the list of folders associated with the file type and display them on open.

In Saver mode, the application will provide a single file type and FilePicker will open the default folder associated with the file type. The application can optionally provide the default file name and location of the file to save. In this case, FilePicker will open the default location and display the provided file name. If the application provides multiple locations, the FilePicker will navigate to the first one.

Parameters
fileType

The type of files to display in FilePicker

defaultFileType

defaultfileType or 0. If more than one Type is specified in the first parameter, FilePicker will display the content of defaultFileType

filterList

The filter used to filter the content in FilePicker. This filter will override the default filter associated with the file Type. Each filter in the list is a string pattern that supports wildcards ("*"). The files with extensions that match this filter will be displayed.

directories

The list containing the complete path to folders. These folders will be added to the list of folders associated with the file type. In Saver mode, only the first folder in the list will be used.

defaultSaveFileNames

The list of one or more default file names in Saver Mode.

parent

The parent or 0. If not 0, the ownership of the constructed FilePicker will be transferred to parent.

Since:

BlackBerry 10.0.0

virtual PRIVATE ~FilePicker ()

Destructor.

Since:

BlackBerry 10.0.0

PRIVATE PRIVATE *bool allowOverwrite ()

Indicates whether the FilePicker should allow the user to specify a file name that already exists.

If allowOverwrite is set to true, FilePicker will not check for uniqueness of a file name.

If allowOverwrite is set to false, the FilePicker will ensure that the file name is unique by adding a suffix to the name.

Return:

Returns True if the name can be overwritten, false otherwise

Since:

BlackBerry 10.0.0

Q_SLOT void close ()

Closes the FilePicker.

Since:

BlackBerry 10.0.0

QStringList defaultSaveFileNames ()

Returns the default file names set earlier using the setDefaultSaveFileNames in FilePicker in Saver mode.

This method will return an empty list in Picker mode.

Return:

the list of default save file names

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FileType::Types defaultType ()

Returns the default file type.

The default file type is used if an application provides multiple file types.

Return:

Default type

Since:

BlackBerry 10.0.0

QStringList directories ()

Returns the folder(s) for where to pick or save the file.

Return:

directories The list of folders from where to pick or save the file

Since:

BlackBerry 10.0.0

QStringList filter ()

Returns the filter set using the setFilter().

Return:

The list of filters

Since:

BlackBerry 10.0.0

bool isImageCropEnabled ()

Returns whether image cropping is enabled.

Return:

bool Returns true if the image cropping is enabled in FilePicker, otherwise returns false

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FilePickerMode::Type mode ()

Returns whether the FilePicker is in Picker Mode or Saver Mode.

Return:

FilePickerMode::Mode

See also:

setMode(), Mode

Since:

BlackBerry 10.0.0

Q_SLOT void open ()

Opens up the FilePicker.

This will display the FilePicker, allowing the user to navigate the folders and select the file. When the selection is made, the fileSelected() signal is emitted with the absolute path of the selected files. If the selection is canceled, the canceled() signal is emitted.

Attribute of FilePicker must be set before calling the open() method. Any call to setters after open() is called will be ignored

Since:

BlackBerry 10.0.0

bb::system::SecurityPerimeter::Type perimeter ()

Returns the security perimeter in which FilePicker should be invoked.

Return:

Security perimeter in which FilePicker will be invoked

Since:

BlackBerry 10.0.0

QStringList selectedFiles ()

Returns the absolute paths of the files that were selected in the FilePicker, in Picker or Saver mode.

If no files were selected, an empty list is returned. Calling this method before the selection is made will return an empty list.

Return:

QStringList Returns a list of the absolute paths of the selected files, or an empty list if no files were selected.

Since:

BlackBerry 10.0.0

void setAllowOverwrite (
  • booloverwrite)

Indicates whether or not the FilePicker should generate a unique file name if the file name already exists.

If it is set to false, FilePicker will ensure that the file name is unique by adding a suffix to the name. If it is set to true, the FilePicker will not check for the uniqueness of the file name.

By default, the allowOverwrite will be set to false. This flag will be used only when the FilePicker is in Saver or SaverMultiple mode

Parameters
overwrite

Since:

BlackBerry 10.0.0

void setDefaultSaveFileNames (

Sets the list of one or more default or suggested file name(s) in FilePicker in Saver mode.

For a single file name, the name will be displayed in FilePicker and can be changed. In Picker mode, FilePicker will ignore the value of defaultSaveName.

Parameters
defaultSaveName

A list of one of more default file names

Since:

BlackBerry 10.0.0

void setDefaultType (
  • bb::cascades::pickers::FileType::TypesfileType)

Sets the default file type.

The default file type is used if an application provides multiple file types.
Parameters
fileType

FilePicker will display this fileType if the application provide multiple file types

Since:

BlackBerry 10.0.0

void setDirectories (

Sets a list of one or more directories to pick or save the file.

The FilePicker, in Picker Mode, will add these directories to the list of associated folders. In Saver Mode, FilePicker will navigate to the first directory in the list. If the directories are not specified, FilePicker, in Picker Mode, will display the folders associated with the specified file type or navigate to the default folder in Saver Mode

Warning: This behavior will be deprecated. In the future when specifying multiple directories, the first directory in the list will be used, but the rest of the directories in the list will be ignored.

      FilePicker *picker = new FilePicker();
      picker->setType(FileType::Document);
      picker->setDirectories("/accounts/1000/shared/temp");
In the above example, FilePicker will add "/accounts/1000/shared/temp" to its list of associated folders for FileType Document.
Parameters
directories

The list containing the complete path to the folders for where to pick or save the file

Since:

BlackBerry 10.0.0

void setFilter (

Sets the filter.

FilePicker will use this filter to filter the content of the folders associated with a file type. If the filter is not specified, the content will be filtered based on file type.

      FilePicker *picker = new FilePicker();
      picker->setType(FileType::Picture);
      QStringList filters;
      filters << "*.jpg" << "*.bmp";
      picker->setFilter(filters);
Parameters
filter

Filter list

Since:

BlackBerry 10.0.0

void setImageCropEnabled (
  • boolimageCrop)

Indicates whether to allow cropping of image in FilePicker in Picker mode.

This is only applicable for a file type of Picture. By default, image cropping is disabled.
Parameters
imageCrop

Enable or disable cropping of images.

Since:

BlackBerry 10.0.0

void setMode (

Indicates whether the FilePicker will open in Picker or Saver mode.

By default, the FilePicker will open in Picker mode.

Parameters
mode

FilePicker will open in this mode

Since:

BlackBerry 10.0.0

void setPerimeter (

Sets the security perimeter in which FilePicker should be invoked.

If the security perimeter is not specified FilePicker uses the environment variable 'PERIMETER' to determine the perimeter.

Parameters
perimeter

Security perimeter in which FilePicker will be invoked

Since:

BlackBerry 10.0.0

void setSortBy (

Sets the attribute that FilePicker will use to sort the content.

If the FilePickerSortFlag is not specified, FilePicker will choose the sort flag based on the file type specified.

Parameters
sortBy

The attribute to sort on.

Since:

BlackBerry 10.0.0

void setSortOrder (

Sets the sort order.

If the sort order is not specified, FilePicker will choose the sort order based on the file type
Parameters
order

Sort Order

Since:

BlackBerry 10.0.0

void setSourceRestriction (

Sets which sources FilePicker displays.

By default, FilePicker displays all sources.

Parameters
mode

Since:

BlackBerry 10.2.0

void setTitle (

Sets the title of the FilePicker.

This title is displayed at the top.

Parameters
title

Since:

BlackBerry 10.0.0

void setType (
  • bb::cascades::pickers::FileType::TypesfileType)

Sets the file type(s) of the files that can be selected in the FilePicker.

One or more file types can be combined by using an OR operator. The FilePicker will filter the content based on the type(s) provided.

Parameters
fileType

The file type(s) of the files that will be displayed

Since:

BlackBerry 10.0.0

void setViewMode (

Sets whether the FilePicker displays the content in List View or Grid View.

If the ViewMode is not specified, FilePicker will choose to display the files based on the FileType.

Parameters
mode

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FilePickerSortFlag::Type sortBy ()

Returns the sort attribute set using setSortBy.

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FilePickerSortOrder::Type sortOrder ()

Returns the sortOrder set using setSortOrder.

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FilePickerSourceRestriction::Type sourceRestriction ()

Returns the sourceRestriction set using setSourceRestriction.

Since:

BlackBerry 10.2.0

QString title ()

Returns the FilePicker title if it is available.

Return:

QString

See also:

setTitle()

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FileType::Types type ()

Gets the file type(s) from the FilePicker.

Types is typedef for QFlags<Type>. It stores an OR combination of Type values.

Return:

Types

See also:

setType()

Since:

BlackBerry 10.0.0

bb::cascades::pickers::FilePickerViewMode::Type viewMode ()

Returns the viewMode set using setViewMode.

Return:

ViewMode::Mode

Since:

BlackBerry 10.0.0

Signals

void allowOverwriteChanged (
  • boolallowOverwrite)

Emitted when the allowOverwrite property changes.

Parameters
allowOverwrite

True if the FilePicker can return a file name that already exist, false otherwise

Since:

BlackBerry 10.0.0

void canceled ()

Emitted when the cancel button is clicked in the FilePicker.

Since:

BlackBerry 10.0.0

void defaultSaveFileNamesChanged (

Emitted when the defaultSaveFileNames property changes.

Parameters
newSaveFileNames

The new list of save File Names

Since:

BlackBerry 10.0.0

void defaultTypeChanged (
  • bb::cascades::pickers::FileType::TypesnewDefaultType)

Emitted when the default File type property changes.

Parameters
newDefaultType

The new default FileType to display in FilePicker

Since:

BlackBerry 10.0.0

void directoriesChanged (

Emitted when the directories property changes.

Parameters
newDirectories

The new list of folders

Since:

BlackBerry 10.0.0

void error (

Emitted when the picker is forced to close due to an error.

Parameters
error

The encountered error

Since:

BlackBerry 10.2.0

void fileSelected (

Emitted when a selection has been made in the FilePicker in Picker or Saver mode.

Parameters
selectedFiles

A list containing the absolute path of the selected files

Since:

BlackBerry 10.0.0

void filterChanged (

Emitted when the filter property changes.

Parameters
newFilter

The new filter for the FilePicker

Since:

BlackBerry 10.0.0

void imageCropEnabledChanged (
  • boolenable)

Emitted when the imageCropEnabled property changes in Picker mode.

Parameters
enable

If this value is true, imageCropping is enabled in FilePicker. If this value is false, imageCropping is disabled.

Since:

BlackBerry 10.0.0

void modeChanged (

Emitted when the Mode property changes.

Parameters
newMode

The new Mode of the FilePicker

Since:

BlackBerry 10.0.0

void perimeterChanged (

Emitted when the perimeter property changes.

Parameters
perimeter

Security perimeter for FilePicker

Since:

BlackBerry 10.0.0

void perimeterChanged (
  • intperimeter,
  • )

void pickerClosed ()

Emitted when the FilePicker is closed.

Since:

BlackBerry 10.0.0

void pickerOpened ()

Emitted when the FilePicker is opened.

Since:

BlackBerry 10.0.0

void sortByChanged (

Emitted when the sortBy property changes.

Parameters
newSortBy

The new sort attribute to sort the FilePicker content

Since:

BlackBerry 10.0.0

void sortOrderChanged (

Emitted when the sortOrder property changes.

Parameters
newSortOrder

The new sort order for the FilePicker content

Since:

BlackBerry 10.0.0

void sourceRestrictionChanged (

Emitted when the sourceRestriction property changes.

Parameters
newSourceRestriction

The new sourceRestriction for the FilePicker

Since:

BlackBerry 10.2.0

void titleChanged (

Emitted when the title property changes.

Parameters
newTitle

The new title for the FilePicker

Since:

BlackBerry 10.0.0

void typeChanged (
  • bb::cascades::pickers::FileType::TypesnewType)

Emitted when the File type property changes.

Parameters
newType

The new FileType of the file to display in FilePicker

Since:

BlackBerry 10.0.0

void viewModeChanged (

Emitted when the viewMode property changes.

Parameters
newViewMode

The new viewMode for the FilePicker

Since:

BlackBerry 10.0.0

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus