File pickers

A FilePicker allows you to select a file, or select a file name and location to save a file.

A FilePicker in Picker mode is used to traverse the folder hierarchy to select a file. The application that calls the FilePicker can specify the types of files supported by the FilePicker.

A FilePicker in Saver mode is used to specify a file name and location for the file you want to save. In Saver mode, the application calling the FilePicker can provide the file type and location to save the file, and the user is able to change the location of the file and specify a name.

Screen showing a file picker control.

A FilePicker can be displayed in either a list view or a grid view depending on the type of content being displayed. For example, pictures and videos are typically displayed in a grid view, while documents are best displayed in a list view.

FilePicker supports viewing local content saved to the device, as well as content saved to cloud services, mass storage devices, and more.

Implementing a file picker

When you implement a FilePicker, you need to link to the appropriate library to be able to use the classes you want in your app. In your .pro file, add the following line immediately after the CONFIG line:

LIBS += -lbbcascadespickers

File system access

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. This is very important in apps that use the FilePicker APIs, which return absolute file paths that are not prefixed with file://. File paths returned from FilePicker must be prefixed with file:// to be used as an absolute path to ImageView or MediaPlayer. For more information about accessing external images, see External images.

Picker mode

To implement a FilePicker in Picker mode in your app, attach the FilePicker and specify the type, mode, title, directories, and logic for the picker. The type parameter specifies the FileType to associate with the FilePicker. The mode parameter specifies the mode of the FilePicker. If the mode is not specified, the FilePicker opens in Picker mode by default. The title parameter specifies the title for the FilePicker. In Picker mode, a directory specified in the directories parameter is added to a list of associated folders.

import bb.cascades 1.0
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);
			}
		}
	]
}

Here’s how to create the FilePicker using C++:

FilePicker* filePicker = new FilePicker();
filePicker->setType(FileType::Picture);
filePicker->setTitle("Select Picture");
filePicker->setMode(FilePickerMode::Picker);
filePicker->setDirectories(QStringList("/accounts/1000/shared/misc"));   
filePicker->open();
 
// Connect the fileSelected() signal with the slot.

// If any Q_ASSERT statement(s) indicate that the slot failed to connect to 
// the signal, make sure you know exactly why this has happened. This is not
// normal, and will cause your app to stop working!!
bool connectResult;

// Since the variable is not used in the app, this is added to avoid a 
// compiler warning.
Q_UNUSED(connectResult);

connectResult = QObject::connect(filePicker, 
    SIGNAL(fileSelected(const QStringList&)), 
    this, 
    SLOT(onFileSelected(const QStringList&)));
    
// This is only available in Debug builds.
Q_ASSERT(connectResult);
    
// Connect the canceled() signal with the slot.
connectResult = QObject::connect(filePicker, 
    SIGNAL(canceled()), 
    this, 
    SLOT(onCanceled()));
    
// This is only available in Debug builds.
Q_ASSERT(connectResult);

Saver mode

To implement a FilePicker in Saver mode in your app, attach the FilePicker and specify the type, mode, title, directories, and logic for the picker. The type, mode, and title parameters are used in the same way as they are used in Picker mode, but the directories parameter behaves differently. In Saver mode, the FilePicker navigates to the first directory specified in the directories parameter.

attachedObjects: [
            FilePicker {
                id: picker
                title: "File Picker"
                mode: FilePickerMode.Saver
                type: FileType.Picture
		viewMode: FilePickerViewMode.ListView 
		directories : ["/accounts/1000/shared/misc"]
		onFileSelected : {
		console.log("FileSelected signal received : " +    selectedFiles);
		}
    }
]

Here's how to do the same thing in C++:

FilePicker* filePicker = new FilePicker();
filePicker->setType(FileType::Picture);
filePicker->setTitle("Save Picture");
filePicker->setMode(FilePickerMode::Saver);
filePicker->setDirectories(QStringList("/accounts/1000/shared/misc"));   
filePicker->open();
 
// Connect the fileSelected() signal with the slot.

// If any Q_ASSERT statement(s) indicate that the slot failed to connect to 
// the signal, make sure you know exactly why this has happened. This is not
// normal, and will cause your app to stop working!!
bool connectResult;

// Since the variable is not used in the app, this is added to avoid a 
// compiler warning.
Q_UNUSED(connectResult);

connectResult = QObject::connect(filePicker, 
                    SIGNAL(fileSelected(const QStringList&)), 
                    this, 
                    SLOT(onFileSelected(const QStringList&)));
    
// This is only available in Debug builds.
Q_ASSERT(connectResult);
 
// Connect the canceled() signal with the slot.
connectResult = QObject::connect(filePicker, 
                    SIGNAL(canceled()), 
                    this, 
                    SLOT(onCanceled()));
    
// This is only available in Debug builds.
Q_ASSERT(connectResult);

For a more detailed FilePicker sample, check out the FilePicker sample in Github.

Last modified: 2013-12-21

comments powered by Disqus