File pickers

A FilePicker control 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 to be supported by the FilePicker control.

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

Screen showing a file picker control.

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

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

Prerequisites for a file picker

When you implement a FilePicker control, 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://. If you want to pass a file path that was returned from a FilePicker control to ImageView or MediaPlayer, you must first add the prefix file:// to the file path.

For more information about accessing external images, see External images.

Picker mode

To implement a FilePicker control 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 {
			id: btnfilepicker
			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);
			}
		}
	]
}
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 failure has happened.
// This error is not normal and will cause your app to stop working
bool connectResult;

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

connectResult = QObject::connect(filePicker, 
    SIGNAL(fileSelected(const QStringList&)), 
    this, 
    SLOT(onFileSelected(const QStringList&)));
    
// The Q_ASSERT macro 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()));
    
// The Q_ASSERT macro is only available in Debug builds
Q_ASSERT(connectResult);

Not applicable

Saver mode

To implement a FilePicker control 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: filepicker
                title: "File Picker"
                mode: FilePickerMode.Saver
                type: FileType.Picture
		viewMode: FilePickerViewMode.ListView 
		directories : ["/accounts/1000/shared/misc"]
		onFileSelected : {
		console.log("FileSelected signal received : " +    selectedFiles);
		}
    }
]
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 failure has happened.
// This error is not normal and will cause your app to stop working
bool connectResult;

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

connectResult = QObject::connect(filePicker, 
                    SIGNAL(fileSelected(const QStringList&)), 
                    this, 
                    SLOT(onFileSelected(const QStringList&)));
    
// The Q_ASSERT macro 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()));
    
// The Q_ASSERT macro is only available in Debug builds
Q_ASSERT(connectResult);

Not applicable

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

Last modified: 2015-03-31



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

comments powered by Disqus