Buttons API Specification

1 Overview

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.

API category	public
API type	c++
Existed since	Legacy S60 0.9
API libraries	avkon.lib, eikcoctl.lib
Location	`/sf/mw/classicui/classicui_pub/buttons_api`
Buildfiles	`/sf/mw/classicui/classicui_pub/buttons_api/group/bld.inf`

1.1 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

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.

1.2 Changes

Buttons API is an SDK API and part of S60 release 3.x.

None.

1.3 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.

1.4 Class Structure

Summary of API classes and header files
Classes	Files

CEikBitmapButton /epoc32/include/mw/eikcmbut.h CEikButtonBase /epoc32/include/mw/eikbutb.h CEikButtonGroupContainer /epoc32/include/mw/eikbtgpc.h CEikButtonGroupContainer::CCmdObserverArray /epoc32/include/mw/eikbtgpc.h CEikButtonGroupContainer::TCmdObserver /epoc32/include/mw/eikbtgpc.h CEikButtonGroupContainer::TCmdPos /epoc32/include/mw/eikbtgpc.h CEikButtonGroupFactoryArray /epoc32/include/mw/eikbgfty.h CEikButtonGroupStack /epoc32/include/mw/eikbtgps.h CEikCba /epoc32/include/mw/eikcba.h CEikCba::TIconInfo /epoc32/include/mw/eikcba.h CEikCbaButton /epoc32/include/mw/eikcba.h CEikCommandButton /epoc32/include/mw/eikcmbut.h CEikCommandButtonBase /epoc32/include/mw/eikcmbut.h CEikCommandTable /epoc32/include/mw/eikcba.h CEikEnhancedCbaButton /epoc32/include/mw/eikcba.h CEikInverterCommandButton /epoc32/include/mw/eikcmbut.h CEikLabeledButton /epoc32/include/mw/eiklbbut.h CEikMenuButton /epoc32/include/mw/eikmnbut.h CEikTextButton /epoc32/include/mw/eikcmbut.h CEikTwoPictureCommandButton /epoc32/include/mw/eikcmbut.h EikButtonGroupFactory /epoc32/include/mw/eikbgfty.h EikButtonGroupFactory::TCreationData /epoc32/include/mw/eikbgfty.h TEikButtonCoordinator /epoc32/include/mw/eikbutb.h

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

Softkey classes

2 Using The API

2.1 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.

2.2 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

2.3 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

2.4 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
    }

2.5 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() );
        }
    }

2.6 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;
        }
    }

2.7 Error handling

Buttons API uses standard Symbian OS 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.

2.8 Limitations of the API

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

3 Glossary

3.1 Abbreviations

**Buttons API abbreviations**
API	Application Programming Interface
CBA	Command Button Area
MSK	Middle SoftKey

3.2 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.