The most common use cases of the Common File Dialogs API are described below.
Common File Dialogs API provides some default dialog resources for file operations. User can also define a specified one.
The example below is to demonstrate how to copy the image directory from phone memory to the internal memory card.
1. Define the memory select dialog resource in the resource file (RSS).
#include <CommonDialogs.rh>
RESOURCE MEMORYSELECTIONDIALOG r_memory_selection
{
title = "Select memory:";
softkey_1 = text_softkey_ok; // The text for the left softkey.
softkey_2 = text_softkey_cancel; // The text for the right softkey.
locations =
{
LOCATION { root_path = text_phone_memory_root_path; },
LOCATION { root_path = text_memory_card_root_path; }
};
}
2. Invoke methods to run the copy dialog.
_LIT( KImageDirectory, "C:\\Image\\" );
TBuf<KMaxFileName> buf;
buf.Copy(KImageDirectory); // The data to be copied.
AknCommonDialogsDynMem::RunCopyDlgLD(
0,
buf,
R_MEMORY_SELECTION, // Set to 0 when using default resource.
NULL); // Pointer to MAknMemorySelectionObserver.
An observer derived from MAknMemorySelectionObserver can
be set as the last input parameter in this method. When a file has been selected
the callback method MAknMemorySelectionObserver::OkToExit() is
invoked. In this method, client can verify if the memory selected is valid.
If this callback method returns ETrue, the selecting operation
is completed and the memory select dialog exits. If EFalse is
returned, the memory select dialog keeps active.
An alternate way is to use the selecting dialog instead. The code snippet
below uses traditional class CAknMemorySelectionDialog:
// Using CAknMemorySelectionDialog.
//
CAknMemorySelectionDialog::TMemory memory;
CAknMemorySelectionDialog* dlg = CAknMemorySelectionDialog::NewL(
ECFDDialogTypeCopy, R_MEMORY_SELECTION, ETrue );
CleanupStack::PushL( dlg );
If( dlg->ExecuteL( memory ) )
{
// User select an item, and memory holds the selected memory.
}
CleanupStack::PopAndDestroy();
The code snippet below uses class CAknMemorySelectionDialogMultiDrive,
which supports multiple drives:
TDriveNumber drive.
CAknMemorySelectionDialogMultiDrive* dlg = CAknMemorySelectionDialogMultiDrive::NewL(
ECFDDialogTypeCopy, R_MEMORY_SELECTION, ETrue);
CleanupStack::PushL( dlg );
If( dlg->ExecuteL(drive) )
{
// User select an item, and drive holds the selected memory.
}
CleanupStack::PopAndDestroy();
ECFDDialogTypeCopy is specified by enumeration TCommonDialogType,
and is defined in header file CAknCommonDialogsBase.h.
3. A copy dialog is shown. The user can select the memory card as the destination for the copied data.
As mentioned is the first use case, the user can use class CAknMemorySelectionDialog or
the facade interface class AknCommonDialogsDynMem. The example
below is to demonstrate how to select an image (JPG) in internal mass storage
memories. In this example, the facade interface class AknCommonDialogsDynMem is
use. A specified filter is defined.
1. Define the filter resource in the resource file (RSS)
RESOURCE FILTER r_test_filename _filter
{
filter_type = EFilenameFilter;
filter_style = EInclusiveFilter;
filter_data = {*.jpg};
}
2. Invoke methods to run the select dialog.
// Load the filter resource.
//
TResourceReader resReader;
CCoeEnv::Static()->CreateResourceReaderLC( resReader,
R _TEST_FILENAME _FILTER );
CAknFileNameFilter fileFilter = CAknFileNameFilter::CreateFilterLC( resReader );
CleanupStack::Pop(); // iFileFilter
CleanupStack::PopAndDestroy(); // resReader
// Run select dialog using the filter.
//
TBuf<KMaxFileName> buf;
AknCommonDialogsDynMem::RunSelectDlgLD(
AknCommonDialogsDynMem::EMemoryTypeInternalMassStorage,
buf, // Holds the path and name of the selected file.
NULL, // start folder.
0, // Use default memory select dialog.
fileFilter,
NULL); // Pointer to MAknFileSelectionObserver
An observer derived from MAknFileSelectionObserver can
be set as the last input parameter in this method. When a file has been selected,
the callback method MAknFileSelectionObserver::OkToExit() is
invoked. In this method, client can verify if the selected file is valid.
If this callback method returns ETrue, the selecting operation
is completed and the file select dialog exits. If EFalse is
returned, the file select dialog keeps active.
3. User selects the memory card and file in the select dialogs manually.
The default memory card is used as a setting item. The traditional default memory selection and that used for multiple drives have different UI layout. The code snippet below demonstrates how to create a default memory item in a listbox.
// Assumption: listBox holds the CAknSettingStyleListBox instance and has been initialized.
// ifMultiDriveSupport holds the TBool value, which indicate if multiple drive is supported.
//
_LIT8(KItemTitle, "Select memory");
CAknSettingItemArray settingItemArray;
CAknMemorySelectionDialog::TMemory memory = AknMemorySelectionDialog::EPhoneMemory;
TDriveNumber driveNumber = EDriveC;
CAknSettingItem* settingItem;
// Set memory selection item's title
TBuf<20> itemTitle = "Select memory";
// Create the memory selection item
if ( ifMultiDriveSupport )
{
// If multiple drive is supported.
settingItem =
new( ELeave ) CAknMemorySelectionSettingItemMultiDrive( 0, driveNumber );
}
else
{
// If multiple drive is not supported.
settingItem =
new( ELeave ) CAknMemorySelectionSettingItem( 0, memory );
}
CleanupStack::PushL( settingItem );
settingItem->ConstructL( EFalse, 0, *itemTitle, NULL, 0, EAknCtPopupSettingList );
// Add memo store item to the settings array
settingItemArray.AppendL( settingItem );
CleanupStack::Pop(); // settingItem
// Add other setting items.
// Set item array to listbox.
listBox->Model->SetItemTextArray( &settingItemArray);
All methods may leave, for example if invalid parameter is given as input. Normal Symbian OS error handling practices should be used, including e.g. using cleanup stack and trap harness.