S60 5th Edition SDK v0.9 CommonDialogsEx

- Classes
- Files

# CommonDialogsEx

1. About this Example
2. Architecture
3. Design and Implementation

## 1. About this Example

The CommonDialogsEx example demonstrates the usage of Common Dialogs APIs. This example mainly demonstrates how to use normal and Multiple Drive CFD APIs. This example covers the following operations:

- opening the memory selection dialog
- opening the memory settings dialog
- opening a file selection dialog
- opening a file name prompt dialog.

### 1.1 APIs demonstrated

The CommonDialogsEx application mainly demonstrates the usage of the following APIs:

- `CAknMemorySelectionDialog::NewL()`
- `CAknMemorySelectionDialog::ExecuteL()`
- `CAknMemorySelectionDialogMultiDrive::NewL()`
- `CAknMemorySelectionDialogMultiDrive:ExecuteL()`
- `CAknFileSelectionDialog::NewL()`
- `CAknFileSelectionDialog::ExecuteL()`
- `CAknFileNamePromptDialog::RunDlgLD()`
- `CAknMemorySelectionSettingItem()`
- `CAknMemorySelectionSettingItemMultiDrive()`
- `CAknMemorySelectionSettingItem::ConstructL()`
- `CAknMemorySelectionSettingItemMultiDrive::ConstructL()`
- `CAknMemorySelectionSettingItem::ConstructL()`
- `CAknMemorySelectionSettingItemMultiDrive::ConstructL()`
- `CAknSettingItemArray::AppendL()`
- `CAknSettingItemArray::RecalculateVisibleIndicesL()`
- `CTextListBoxModel::SetItemTextArray()`
- `CTextListBoxModel::SetOwnershipType()`
- `CAknSettingStyleListBox::CreateScrollBarFrameL()`
- `CAknSettingStyleListBox::ScrollBarFrame()`
- `CAknSettingStyleListBox::HandleItemAdditionL()`
- `CAknSettingStyleListBox::SetListBoxObserver()`
- `CAknSettingStyleListBox::UpdateScrollBarsL()`
- `CEikListBox::SetScrollBarVisibilityL();`
- `CAknMemorySelectionSettingItem::EditItemL( )`
- `CAknMemorySelectionSettingItemMultiDrive::EditItemL()`

The following header files are included in the example:

- `CAknMemorySelectionDialog.h`
- `CAknMemorySelectionDialogMultiDrive.h`
- `CAknMemorySelectionSettingPage.h`
- `CAknFileSelectionDialog.h`
- `CAknFileNamePromptDialog.h`
- `AknSettingItemList.h`
- `EikDialg.h`

The CCommonDialogsExSettingsDialog class is inherited from the following classes:

- `CEikDialog`
- `MEikListBoxObserver`

The following functions have been implemented:

- `TBool OkToExitL( TInt aButtonId )`
- `void PreLayoutDynInitL()`
- `void ProcessCommandL( TInt aCommandId )`
- `void HandleListBoxEventL( CEikListBox* aListBox,TListBoxEvent aEventType )`

### 1.2 Prerequisites

This example requires a familiarity with the C++ programming language and S60 application structure.

## 2. Architecture

The CommonDialogsEx example application follows the standard S60 application framework. The application, document and view classes implement the framework and the actual example code is in the CCommonDialogsExAppUi class.

## 3. Design and Implementation

### 3.1 Capabilities

The CommonDialogsEx application needs the `ReadUserData` and `WriteUserData` capabilities for creating, modifying and deleting contact(s).

### 3.2 Build and Installation

The CommonDialogsEx application has two `.pkg` files which will be used for making `.sis` packages for different target platforms. The whole project can be imported to the CodeWarrior IDE as an `.mmp` file. The project can be built in the CodeWarrior IDE. It can also be build on from the command line with the following commands:

     ..\group>bldmake bldfiles
     ..\group>abld build winscw udeb

### 3.3 Preparation

When the application is started, the CCommonDialogsExContainer class will be initialized by View class. Here are the steps done in `CCommonDialogsExContainer`'s constructor (the labels are two components for display text):

       iLabel = new (ELeave) CEikLabel;
       iLabel->SetContainerWindowL( *this );
       iLabel->SetTextL( _L("Example View") );

       iToDoLabel = new (ELeave) CEikLabel;
       iToDoLabel->SetContainerWindowL( *this );
       iToDoLabel->SetTextL( _L("Press Options to start") );

The `ShowTextL(const TDesC& aText, const TDesC& aTextSub)` function shows a text message on the screen by using label:

       iLabel->SetTextL(aText);
       iToDoLabel->SetTextL(aTextSub);

When the application is launched the CCommonDialogsExAppUi class is initialized by the `AppUi` class. Here are the steps done in the constructor:

     iAppContainer = new (ELeave) CCommonDialogsExContainer;
     iAppContainer->ConstructL( ClientRect() );

The CCommonDialogsExSettingsDialog class is inherited from the `CEikDialog` and `MEikListBoxObserver` classes. In this class you should implement function `PreLayoutDynInitL()` `OkToExitL()` `ProcessCommandL()` from `CEikDialog`, implement function `HandleListBoxEventL()` from `MEikListBoxObserver`.

The `PreLayoutDynInitL()` function initializes the dialog's controls before the dialog is sized and layed out:

      CAknSettingStyleListBox* listBox =  static_cast< CAknSettingStyleListBox* >
                                                                 ( Control( ECommonDialogsExSettingsListboxId ) );
       User::LeaveIfNull( listBox );

Create the memory selection item (if your current SDK supports Multiple Drive APIs):

      if ( iMultiDriveSupport )
           {
           settingItem = new( ELeave ) CAknMemorySelectionSettingItemMultiDrive(
                                                iResourceId, iDriveNumber );
           }
      else
           {
           settingItem = new( ELeave ) CAknMemorySelectionSettingItem(
                                               iResourceId, iMemory );
           }
       CleanupStack::PushL( settingItem );

Set title for the memory selection item:

       itemTitle = iCoeEnv->AllocReadResourceLC( R_STRING_COMMONDIALOGSEX_SET_MEMORY );
       settingItem->ConstructL( EFalse, 0, *itemTitle, NULL, 0,
                                                       EAknCtPopupSettingList );
       CleanupStack::PopAndDestroy();  // itemTitle

Add memo store item to the settings array:

       iSettingItemArray.AppendL( settingItem );
       CleanupStack::Pop();    // settingItem

Set listBox:

       CTextListBoxModel* model = listBox->Model();
       model->SetItemTextArray( &iSettingItemArray );
       model->SetOwnershipType( ELbmDoesNotOwnItemArray );
       iSettingItemArray.RecalculateVisibleIndicesL();
       listBox->CreateScrollBarFrameL( ETrue );
       listBox->ScrollBarFrame()->SetScrollBarVisibilityL(
                           CEikScrollBarFrame::EOff, CEikScrollBarFrame::EAuto );
       listBox->HandleItemAdditionL();
       listBox->SetListBoxObserver( this );
       listBox->UpdateScrollBarsL();

### 3.5 Execution

There are total of six cases for this example:

1. opening memory selection dialog
2. opening Multiple Drive memory selection dialog
3. opening memory settings dialog
4. opening Multiple Drive memory settings dialog
5. opening file selection dialog
6. opening file name prompt dialog

(1) Creating memory selection dialogs with case `ECommonDialogsExCmd101`:

               CAknMemorySelectionDialog* dlg = CAknMemorySelectionDialog::NewL(
                                                           ECFDDialogTypeNormal,
                                                           ETrue );
               CleanupStack::PushL( dlg );
               returnValue = dlg->ExecuteL( iMemory );

Then set the display text:

               if( returnValue )
                   {
                   textMain.Append( KCommonDialogsExSelected );
                   if ( iMemory == CAknMemorySelectionSettingPage::EPhoneMemory )
                       {
                       textSub.Append( KCommonDialogsExPhoneMemoryName );
                       }
                   else
                       {
                       textSub.Append( KCommonDialogsExMemoryCardName );
                       }
                   }
               else
                   {
                   textMain.Append( KCommonDialogsExCanceled );
                   textSub.Append( KCommonDialogsExSpace );
                   }
               iAppContainer->ShowTextL( textMain, textSub );
               CleanupStack::PopAndDestroy(); //dlg

(2) Creating Multiple Drive memory selection dialogs with case `ECommonDialogsExCmd102`.

If your current SDK supports Multiple Drive APIs, the dialog will display:

               CAknMemorySelectionDialogMultiDrive* dlg =
                   CAknMemorySelectionDialogMultiDrive::NewL(
                           ECFDDialogTypeNormal, ETrue );
               CleanupStack::PushL( dlg );
               returnValue = dlg->ExecuteL( iDrive , &tempRootPath, NULL );
               ......
               CleanupStack::PopAndDestroy();

(3) Creating memory settings dialog with case `ECommonDialogsExCmd201`:

               CCommonDialogsExSettingsDialog* dlg =
                             CCommonDialogsExSettingsDialog::NewL(0, EFalse);
               dlg->ExecuteLD( R_COMMONDIALOGSEX_SETTINGS_DIALOG );
               textMain.Append( KCommonDialogsExSelected );
               textSub.Append( KCommonDialogsExDefaultSetting );
               iAppContainer->ShowTextL( textMain, textSub );

(4) Creating Multiple Drive memory settings dialog with case `ECommonDialogsExCmd202`:

                CCommonDialogsExSettingsDialog* dlg =
                    CCommonDialogsExSettingsDialog::NewL(0, ETrue);
                dlg->ExecuteLD( R_COMMONDIALOGSEX_SETTINGS_DIALOG );
                textMain.Append( KCommonDialogsExSelected );
                textSub.Append( KCommonDialogsExMultiSetting );
                iAppContainer->ShowTextL( textMain, textSub );

(5) Creating file selection dialog with case `ECommonDialogsExCmd301`:

               CAknFileSelectionDialog* dlg = CAknFileSelectionDialog::NewL( ECFDDialogTypeSelect );
               CleanupStack::PushL( dlg );
               returnValue = dlg->ExecuteL( rootFileName );
               ......
               iAppContainer->ShowTextL( textMain, textSub );
               CleanupStack::PopAndDestroy();

(6) Creating file name prompt dialog with case `ECommonDialogsExCmd401`:

               returnValue = CAknFileNamePromptDialog::RunDlgLD(
                                     defaultFileName,
                                     KRootPath );
               ......
               iAppContainer->ShowTextL( textMain, textSub );

© Nokia 2008 |