UIQ Controls - Sound Selector

This guide explains the UIQ control Sound Selector (CQikSoundSelector). The Sound Selector basically consists of a Choice List control accompanied with an image. Consequently, the behavior of the Sound Selector mostly resembles that of the Choice List. In Pen Style UI, the image provides a way for the user to preview the selected sound; this is done by tapping the image.

The following functionality can be used by the application developer:

• Set if "silent" should be an item in the Choice List,

• Set if "find sound", an option that allows the user to browse for a sound among stored audio media files, should be an item in the Choice List,

• Use "find sound history", the three latest selections from the "find sound" dialog that are available in the Choice List,

• Add a fixed sequence of sounds, of type tones, event sounds, alarm sounds and ring sounds, to the Sound Selector,

• Add custom sounds to the Sound Selector,

• Change the default sound,

• Change the currently selected sound,

• Change the volume of the sound on a scale between 0 and 100,

• Change the font used in the Choice List,

• Toggle between dimmed state and normal state.

By default, the following configuration applies:

• The "silent" item is available in the Choice List,

• The "find sound" item is not available,

• The "find sound history" items are not available,

• Alarm and ring sounds are available in the Choice List,

• The default sound is set to "silent",

• The volume is set to 50.

Examples of Sound Selector graphics

Sound Selector Highlighted Sound Selector Dimmed Sound Selector Sound Selector with pop out list box

See the API documentation for Sound Selector (CQikSoundSelector).

The Sound Selector control is closely related to the Choice List control. See the How To guide for Choice List.

See even the API documentation for Choice List (CEikChoiceList).

Sound Selector inherits from CCoeControl and consists of a CSoundPickerChoiceList, an CEikImage and a CQikSoundSelectorExtension.

This section explains how the control is constructed, used and destroyed. Source code examples are used and explained to illustrate how the Sound Selector control is used.

Use the following #include directive:

#include <qiksoundselector.h>

Use the following LIBRARY directive in the project's mmp-file:

LIBRARY qikctl.lib

Use the following control identifier when specifying the control in resource data files. It is used by the framework when constructing the control from resource data:

EQikCtSoundSelector

No resource structure is defined for Sound Selector.

You cannot create Sound Selector using all of the four ordinary ways, which are construction with view framework using data from a resource file, construction with your own C++ code using data from a resource file, construction solely from C++ code and construction with the dialog framework using data from a resource file.

A Sound Selector for a view can only be constructed from source code. The Sound Selector control is an exception because of the absence of a defined Sound Selector struct.

This section covers the one method of constructing a Sound Selector for a view and the one method for constructing a Sound Selector for a dialog.

3.3.1 Construction with View Framework Using Data from a Resource File

Unfortunately you cannot create a Sound Selector with the View Framework using data from a resource file. Constructing a Sound Selector from a resource file in a dialog is described below.

3.3.2 Construction with Your Own C++ Code Using Data from a Resource File

Not applicable.

3.3.3 Construction Solely from C++ Code

The example below describes how to construct a Sound Selector solely from C++ code.

The reason the example seems to be rather complex is because it demonstrates how to construct a complete view containing a Scrollable Container and a Layout Manager.

The following source code constructs a Sound Selector:

/* Declare the controls' ID in a *.hrh file for use both in resource and cpp */
enum TMyViewControls
    {
    EMyViewScrollableContainer,
    EMyViewBuildingBlock,
    EMyViewSoundSelector,
    EMyViewNumberOfControls
    };

#include <qiksoundselector.h>
#include <QikScrollableContainer.h>
#include <QikRowLayoutManager.h>
#include <QikGridLayoutManager.h>
#include <QikBuildingBlock.h>
                    
void CMySinglePageView::ViewConstructL()
    {
                    
    // Give a layout manager to the view
    CQikGridLayoutManager* gridlayout = CQikGridLayoutManager::NewLC();
    SetLayoutManagerL(gridlayout);
    CleanupStack::Pop(gridlayout);
                
    // Create a container and add it to the view
    CQikScrollableContainer* container = new (ELeave) CQikScrollableContainer();
    Controls().AppendLC(container);
    container->ConstructL(EFalse);
    CleanupStack::Pop(container);
                        
    // Create a layout manager to be used inside the container
    CQikRowLayoutManager* rowlayout = CQikRowLayoutManager::NewLC();
    container->SetLayoutManagerL(rowlayout);
    CleanupStack::Pop(rowlayout);
                    
    // Create the Sound Selector and add it to the container
    CQikSoundSelector* sndslctr = new (ELeave) CQikSoundSelector();
    container->AddControlLC(sndslctr, EMyViewSoundSelector);
    sndslctr->ConstructL();
    sndslctr->SetUniqueHandle(EMyViewSoundSelector);
    sndslctr->SetObserver(this);
    CleanupStack::Pop(sndslctr);
    }

What the code does

1) Declares an enum for the controls to be used in the view in a *.hrh file. Hrh files are files to be included both in resource files (*.rss) and C++ files.

2) Initializes the Command Manager with an empty Command List. The controls placed in the view add their commands to the Command List when they receive focus.

3) Creates a Layout Manager for the view. The Grid Layout Manager fills the view with its only control in this example, the Scrollable Container.

4) Instantiates a container and adds it to the view.

5) Creates a Layout Manager and adds it to the container.

6) Creates the Sound Selector control from C++ code. Sets the view, this, to be an observer of the Sound Selector. The view's base class, CQikViewBase, handles focus changes in its method HandleControlEventL. For more details see the section below on how to be notified with Control Events.

7) The result should look something like this:

3.3.4 Construction with the Dialog Framework Using Data from a Resource File

The Sound Selector can be constructed from resource files in dialogs as well. To construct a dialog from resource a valid resource definition of that dialog must be in one of the project's resource files.

An example of a dialog resource containing the control is given below. For more information about the dialog class and its resource struct see CEikDialog and DIALOG in the API documentation.

1) Declare a dialog resource containing the Sound Selector control:

RESOURCE DIALOG r_my_sound_selector_dialog
    {
    title = "Sound Selector Test";
    flags = EEikDialogFlagWait;
    items =
        {
        DLG_LINE
            {
            type = EQikCtSoundSelector;
            prompt = "Sound";
            id = EMyViewSoundSelector;
            }
        };
    }

The resource properties inside the Control Block are the same as the ones described in the previous section.

2) Launch the dialog using the following source code. The dialog resource ID is passed as an argument:

CEikDialog* dlg = new (ELeave) CEikDialog();
dlg->ExecuteLD(R_MY_SOUND_SELECTOR_DIALOG);

The function returns immediately if EEikDialogFlagWait has not been specified in the dialog resource. If EEikDialogFlagWait is specified, it returns when the dialog exits. The dialog framework will, in both situations, delete the dialog appropriately as indicated by the D suffix of the ExcecuteLD function name.

This section covers the most common functions used for interacting with the control.

When constructing the control with resource data, no reference to the control is available in the view class. When constructing the control with code, the preferred way might be to not save a reference to the control. In both these cases, the LocateControlByUniqueHandle function is used to get a pointer to the control by supplying the control's unique handle. When constructing the view and the control from code, you must explicitly set this unique handle by calling the method SetUniqueHandle. See the code examples below.

Note that the function will return NULL if the control could not be found. Always check the pointer before using it!

// Set the unique handle
sndslctr->SetUniqueHandle(EMyViewSoundSelector);
            
// Get a pointer to the edwin control
CQikSoundSelector* sndslctr = LocateControlByUniqueHandle<CQikSoundSelector>(EMyViewSoundSelector);

3.4.1 Get the Currently Selected Sound from the Sound Selector

This example shows how to obtain the sound that is currently selected in the Sound Selector.

TFileName theSelectedSound;
    
// Get a pointer to the Sound Selector control
CQikSoundSelector* sndslctr = LocateControlByUniqueHandle<CQikSoundSelector>(EMyViewSoundSelector);
                        
sndslctr->GetSound(TheSelectedSound);

3.4.2 Set the Volume of the Sound Selector

This example shows how to set the volume of the Sound Selector.

TInt theMaximumVolume = 100;
                        
// Get a pointer to the Sound Selector control
CQikSoundSelector* sndslctr = LocateControlByUniqueHandle<CQikSoundSelector>(EMyViewSoundSelector);

sndslctr->SetSoundVolume(theMaximumVolume);

3.4.3 How to be Notified with Control Events

In order to be notified when the Sound Selector changes state you must add an observer to the Sound Selector. An observer is an object of the type MCoeControlObserver. The observer receives a function call to its function HandleControlEventL(CCoeControl* aControl, TCoeEvent aEventType) when the Sound Selector changes state.

The view base class, CQikViewBase, implements the MCoeControlObserver. The HandleControlEventL function must be overloaded in the view class because the view inherits from CQikViewBase.

The following source code example shows how to add an object as an observer and how to receive events from the Sound Selector:

void CMySinglePageView::ViewConstructL()
    {
    // Construction code
    …
    // Adding this object as an observer
    sndslctr->SetObserver(this);
    }

void CMySinglePageView::HandleControlEventL(CCoeControl* aControl, TCoeEvent aEventType)
    {
    // Call base class to handle focus management
    CQikViewBase::HandleControlEventL(aControl, aEventType);
                        
    CQikSoundSelector* sndslctr = LocateControlByUniqueHandle<CQikSoundSelector>(EMyViewSoundSelector);
    if(aControl == sndslctr)
        {
        switch(aEventType)
            {
            case EEventStateChanged:
                // The internal state of the Sound Selector was changed,
                // for example, due to another item being selected. 
                break;          
                                    
            case EEventRequestExit:
                break;
                                    
            case EEventRequestCancel:
                break;
                                    
            case EEventRequestFocus:
                // The Sound Selector received a pointer down event
                break;
                                    
            case EEventPrepareFocusTransition:
                // A focus change is about to appear
                break;
                                
            case EEventInteractionRefused:
                // The Sound Selector is dimmed and received a
                // pointer down event.
                break;
                                
            default:
                break;
            }
        }
    }

The reason for calling the base class's HandleControlEventL function is that the view base class, CQikViewBase, handles focus management between controls in the view. If the control's observer is not a class which derives from CQikViewBase, focus management must be resolved by the observer itself. If a control requests focus and it does not get it from the observer, it will generate a panic in some cases if the observer does not leave.

For more details on the TCoeEvent type, see class MCoeControlObserver in the API documentation.

Destroying the control is just a matter of invoking operator delete on the Sound Selector object.

Subclassing Sound Selector is not recommended.