Mapping custom softkeys

Describes the changes required to map the custom softkeys to the corresponding Symbian Belle icons.

Context

The custom softkeys are not mapped to the appropriate icons automatically like the standard softkeys. You can either choose to use the following standard AVKON softkey IDs or map an icon to your custom softkey key ID explicitly:

EAknSoftkeyEmpty
EAknSoftkeyOk
EAknSoftkeySelect
EAknSoftkeyCancel
EAknSoftkeyDetails
EAknSoftkeyCall
EAknSoftkeyOptions
EAknSoftkeyBack
EAknSoftkeyDone
EAknSoftkeyExit
EAknSoftkeyClose
EAknSoftkeyHide
EAknSoftkeyMark
EAknSoftkeyUnmark
EAknSoftkeyYes
EAknSoftkeyNo
EAknSoftkeyUnlock
EAknSoftkeySave
EAknSoftkeyShow
EAknSoftkeyRead
EAknSoftkeyListen
EAknSoftkeySearch
EAknSoftkeyAgain
EAknSoftkeyQuit
EAknSoftkeyInsert

It is recommended that you use these standard softkey IDs to avoid the effort of explicitly mapping the softkey to an icon, and also to ensure that the look-and-feel of the application adheres to the UI guidelines for Symbian Belle.

Prerequisites

If you decide to explicitly map your custom softkey ID to an icon, have the icon ready and follow the steps outlined here.

Steps

Set callback to CEikCba::SetCommandToIconMapperL

Example: For example:

static_cast<CEikCba*>( cba->ButtonGroup() )->SetCommandToIconMapperL(MapCommandToIcon, cba);

//Callback handler function
TBool CMyClass::MapCommandToIcon( TInt aCommand, CEikCba::TIconInfo& aIconInfo, TAny* /*aPtr*/ )
    {
    switch( aCommand )
    {
    case EMyCmd0:
        aIconInfo = CEikCba::TIconInfo( KAknsIIDQgnIndiTpIdle, KAvkonBitmapFile,
            EMbmAvkonQgn_indi_tp_idle, EMbmAvkonQgn_indi_tp_idle_mask );
        return ETrue;
    case EMyCmd1:
        aIconInfo.iIconFile.Set(KAvkonBitmapFile);
        aIconInfo.iIconId = EMbmAvkonQgn_indi_tp_dialler;
        aIconInfo.iMaskId = EMbmAvkonQgn_indi_tp_dialler_mask;
        return ETrue;
    default:
        return EFalse;
    }
    }

Add the icon information to theICONIC_CBA_BUTTON resource structure in the application's resource header

Example: For example:

RESOURCE ICONIC_CBA_BUTTON r_custom_icon_cba_button
    {
    id = EMyCmd0;
    txt = "Options";
    bmpfile = "\\resource\\apps\\avkon2.mbm";
    bmpid = EMbmAvkonQgn_indi_tp_idle;
    bmpmask = EMbmAvkonQgn_indi_tp_idle_mask;
    skinid_major = EAknsMajorGeneric;
    skinid_minor = EAknsMinorGenericQgnIndiTpIdle;
    }

RESOURCE CBA r_custom_icon_cba
    {
    buttons =
        {
        ICONIC_CBA_BUTTON
            {
            id = EMyCmd0;
            txt = "Options";
            bmpfile = "\\resource\\apps\\avkon2.mbm";
            bmpid = EMbmAvkonQgn_indi_tp_dialler;
            bmpmask = EMbmAvkonQgn_indi_tp_dialler_mask;
            skinid_major = EAknsMajorGeneric;
            skinid_minor = EAknsMinorGenericQgnIndiTpDialler;
            },
        ICONIC_CBA_BUTTON
            {
            id = EMyCmd1;
            txt = "Back";
            bmpfile = "\\resource\\apps\\avkon2.mbm";
            bmpid = EMbmAvkonQgn_indi_tp_help;
            bmpmask = EMbmAvkonQgn_indi_tp_help_mask;
            skinid_major = EAknsMajorGeneric;
            skinid_minor = EAknsMinorGenericQgnIndiTpHelp;
            }
        };
    }

Results

This will ensure that the custom softkeys are mapped to icons. If the icons are not found in the specified location, a textual softkey is displayed.