Purpose

Button is a generic control in the UI environment, being not only a visual area on the screen but also managing interaction with the user: it can be activated. It may contain text, image or both.

Command button component (which this document describes) is a specialized button placed into a softkey pane, see Definitions .

Constraints

None.

Classification and release information

Buttons API is an SDK API and part of S60 3rd Edition.

API Description

The following picture shows the visual appearance and placement of the softkeys (command buttons). The Softkey pane is not necessarily placed at the bottom of the screen, layout and orientation changes it.

Softkeys and softkey pane


Softkeys and softkey pane

A softkey cannot be instantiated directly. It is included into a CEikButtonGroupContainer class. As the button's main feature is to respond to key events the Softkey pane is added to the control stack automatically.

Use Cases

The main use cases of Buttons API are:

  • Defining resource.

  • Using CBA resource.

  • Changing text label.

  • Changing the command set via the command stack.

  • Creating ButtonGroupContainer manually.

  • Receiving command button activation event.

API Class Structure

The following diagram shows the class hierarchy of the command buttons component.

Softkey classes


Softkey classes

Related APIs
  • CEikButtonGroupContainer

Using the Buttons API

Defining resource

The following resource structure should be used for the command button object (defined in eikon.rh ):

             
              STRUCT CBA
              
    {
    LONG flags = EEikButtonGroupAddToStack;
    LLINK related_buttons = 0;
    STRUCT buttons[];
    }

STRUCT CBA_BUTTON
    {
    BYTE version = 0;
    WORD id = 0;
    LTEXT txt = "";
    }

A typical CBA definition looks like this ( app_res_def.rss ):

             
              // contains application specific enums, commands, texts
              
#include "app_res_def.hrh"

RESOURCE CBA r_app_softkeys_prev_next__contextoptions
    {
    flags = 0;
    buttons = 
        {
        CBA_BUTTON {id = EAppCommandPrev; txt = text_softkey_prev;},
        CBA_BUTTON {id = EAppCommandNext; txt = text_softkey_next;},
        CBA_BUTTON {id = EAknSoftkeyContextOptions; txt = text_softkey_contextoptions;}
        };
    }

Many CBA controls (e.g. R_AVKON_SOFTKEYS_EMPTY , R_AVKON_SOFTKEYS_OK_BACK__OK ) are predefined in AVKON.RSG .

By default CBA controls do not respond when they are invisible. This prevents hidden CBAs from receiving any type of key events. However, the feature can be activated by setting the EAknCBAFlagRespondWhenInvisible flag.

Related APIs
  • EAknCBAFlagRespondWhenInvisible
  • R_AVKON_SOFTKEYS_EMPTY
  • R_AVKON_SOFTKEYS_OK_BACK__OK

Using CBA resource

Changing the command set in the CBA object:

             
              #include <app_res_def.rsg>
              

CEikButtonGroupContainer* myCba = CEikButtonGroupContainer::Current();
CleanupStack::PushL( myCba );
myCba->SetCommandSetL( R_APP_SOFTKEYS_PREV_NEXT__CONTEXTOPTIONS );
myCba->MakeVisible( ETrue );
myCba->DrawNow();
CleanupStack::Pop();  // myCba

Changing text label

Text label of the command button can be changed by setting a new command:

             
              // in application resource file
              
RESOURCE TBUF r_app_softkey_prev { buf = text_softkey_prev; }

// Left softkey, new text is a resource
HBufC* myText = StringLoader::LoadLC( R_APP_SOFTKEY_PREV );
Cba()->SetCommandL( 0, EAppCommandPrev, *myText );
Cba()->DrawDeferred(); // or DrawNow
CleanupStack::PopAndDestroy();  // myText

// Right softkey, new text is static text
Cba()->SetCommandL( 2, EAppCommandNext, _L("next") );
Cba()->DrawDeferred(); // or DrawNow

// Middle softkey, new text is static text
Cba()->SetCommandL( 3, EAppCommandMSK, _L("MSK") );
Cba()->DrawDeferred(); // or DrawNow

Changing the command set via the command stack

Command stack is an advanced tool in CBA control: it stores multiple command definitions in a stack. Only the top one is active, but it also gives the possibility to remove any command and use a previous one.

Adding a new command set to the CBA command stack:

             
              #include "app_res_def.rsg"
              

CEikButtonGroupContainer* myCba = CEikButtonGroupContainer::Current();
CleanupStack::PushL( myCba );
myCba->AddCommandSetToStackL( R_APP_SOFTKEYS_PREV_NEXT__CONTEXTOPTIONS );
myCba->MakeVisible( ETrue );
myCba->DrawNow();
CleanupStack::Pop();  // myCba

Removing a command:

             
              // code to remove softkeys from CBA stack
              
if( iActualCbaResource == R_APP_SOFTKEYS_PREV_NEXT__CONTEXTOPTIONS )
    {
    RemoveCommandFromStack(CEikButtonGroupContainer::ELeftSoftkeyPosition,
                           EappCommandPrev }; // left softkey command
    RemoveCommandFromStack(CEikButtonGroupContainer::ERightSoftkeyPosition,
                           EAppCommandNext }; // right softkey command
    RemoveCommandFromStack(CEikButtonGroupContainer::EMiddleSoftkeyPosition,
                           EAknSoftkeyContextOptions }; // MSK command
    }

Creating ButtonGroupContainer manually

Application UIs always have a CEikButtonGroupContainer . Most of the Application Views and Dialogs have it too. The following functions can be used to access their CBA object:

             
              CEikButtonGroupContainer* CAknAppUi::Cba()
              
CEikButtonGroupContainer* CAknView::Cba()
CEikButtonGroupContainer* CEikDialog::ButtonGroupContainer()

It is also possible to create a local CEikButtonGroupContainer :

             
              // constructing the local button group container
              
void CMyAppView::ConstructL()
    {
    iLocalButtonGroup = CEikButtonGroupContainer::NewL(
        CEikButtonGroupContainer::ECba,  // type
        CEikButtonGroupContainer::EHorizontal,  // orientation
        this,  // command observer
        R_APP_SOFTKEYS_PREV_NEXT__CONTEXTOPTIONS );  // default resource to use
    // remove from control stack (added automatically),
    // because don't want to use it yet
    AppUi()->RemoveFromStack( iLocalButtonGroup->ButtonGroup() );
    }

// and using it when View is activated
void CMyAppView::DoActivateL( const TVwsViewId&, TUid, const TDesC8& )
    {
    // add to control stack to receive key events
    if( iLocalButtonGroupContainer )
        {
        AppUi()->AddToStackL( iLocalButtonGroupContainer->ButtonGroup() );
        }
    }

void CMyAppView::DoDeactivate()
    {
    if( iLocalButtonGroupContainer )
        {
        AppUi()->RemoveFromStack( iLocalButtonGroupContainer->ButtonGroup() );
        }
    }
Related APIs
  • CEikButtonGroupContainer

Receiving command button activation event

Softkey pressing event is reported to the Observer via the MEikCommandObserver interface.

             
              class CMyAppView: public CAknView
              
    // CAknView already inherited from MEikCommandObserver
    {
    public:
        virtual void ProcessCommandL( TInt aCommandId );
    };

Processing the command:

             
              void CMyAppView::ProcessCommandL( TInt aCommandId )
              
    {
    switch( aCommandId ) {
        case EAppCommandPrev:
            if( iActualPage < iPageCount-1 )
                SwitchToPage( ++iActualPage );
            break;
        case EAppCommandNext:
            if( iActualPage > 0 )
                SwitchToPage( --iActualPage );
            break;
        default:
            CAknView::ProcessCommandL( aCommandId );  // pass it up
            break;
        }
    }
Related APIs
  • MEikCommandObserver

Error handling

Buttons API uses standard Symbian platform error reporting mechanism. Leaves and system wide error codes as function return values are used if the error is recoverable. A client application can handle these errors similarly as a normal Symbian platform application.

Limitations of the API

Setting an image as a command button is a future development feature.

Glossary

Abbreviations

Buttons API abbreviations

API Application Programming Interface

CBA

Command Button Area

MSK

Middle SoftKey

Definitions

Buttons API definitions

Softkey A command button mapped to a hard key on the device.

Softkey pane

A UI control containing all the Softkeys supported by the device. It may contain other controls too, e.g. scrolbars.