UIQ Controls - Toolbar

The toolbar is used to collect controls that can be used in your application. A toolbar can be placed next to the application space in Pen style. It can be placed above or below the application space or else it can be placed to the left or the right of the application space. It is also possible to specify if the toolbar is movable (drag-and-drop).

The toolbar is a view-specific control containing frequently used options. Since the toolbar is view specific, a toolbar must be added for each view. The upside of this is that switching between views does not mean that it is necessary to switch toolbars as this is done automatically.

Controls can be made visible/invisible and dimmed/not dimmed. No runtime modification, such as adding controls to or deleting controls from the toolbar, is supported. However, several toolbars can be made in advance and shifted during runtime.

The layout of the toolbar is automatically handled by the system depending on where it is placed in relation to the application space.

Your application UI class is derived from CQikAppUi. CQikAppUi can handle the commands that are issued from the toolbar.

It is possible to add the toolbar from this class using CQikAppUi::SetToolbarL(), but this is not recommended. The reason for this is that in UIQ 2.1 and earlier the toolbar was AppUi based, but since UIQ 3 the toolbar has become View based and it is therefore strongly recommended that you add the toolbar to a view.

This does not mean, however, that you are restricted to using views. If the application does not have a view it is possible to add a toolbar to the AppUi as was the case before UIQ 3.

Your AppUi class contains your view classes.

Your view classes can be derived from CQikViewBase, which is a base class for views. CQikViewBase provides a view with a single page. All UIQ views are derived directly or indirectly from this class.

Since the toolbar is View based from UIQ 3 it is recommended that you add the toolbar to a view. This does not however mean that one is restricted to the use of views only. If the application does not have a view it is possible to add it to the AppUi as was the case before UIQ 3.

CQikViewBase handles much of the new functionality found in UIQ 3:

• Constructing views, controls and layouts from resource files,

• Basic focus management,

• Hardware-button navigation between controls,

• Command handling,

• Interface for changing UI configurations in runtime,

• Handling the Context Bar.

See UIQ API Reference for more information about CQikAppUi, CQikViewBase and CQikToolbar.

The toolbar is placed next to the application space. You can specify whether it is placed above the application space, below the application space, which is the default position, to the left of the application space or to the right of the application space.

Include your .hrh file in your application UI class:

#include "exampleApplication.hrh"

Use the following #include directives in your view classes.

//Parent class for the View
#include <CQikViewBase.h>

// The compiled resource file
#include <LibraryBooks.mbg>

This example shows how to add a slider and a button to the toolbar which then can be used.

1) Declare an enumerator for the controls that are to be placed in the toolbar in a *.hrh file. Hrh files are files to be included both in resource files (*.rss) and C++ files:

/* Declare the control ID in *.hrh file for use both in resource and cpp */
enum TExampleToolbarButtons
   {
   EMyToolbarButton0 = 100,
    EMyToolbarSlider
   };

2) Add the toolbar in your .rss file.

RESOURCE QIK_TOOLBAR r_my_toolbar
    {
    // Where the toolbar should be placed in the application area.
    orientation = EQikToolbarOrientationNorth;

    //If the user should be able to drag the toolbar around the application space.
    movable = 1;        
    
    controls=
        {
        QIK_TBAR_CTRL
            {
            type = EQikCtSlider;
            id = EMyToolbarSlider;
            length = 130;
            control = QIK_SLIDER
                {
                min_value = 0;
                max_value = 300;     
                num_markers = 6;
                flags = EQikSliderSnapToMarker;
                };
            },
            QIK_TBAR_BUTTON // Text button.
                {
                id = EMyToolbarButton0;
                txt = "Show";
                }
        };                  
    }

3) From the view class we have to call SetViewToolBarL() to add it to the view's application area.

This can be done, for example, in the overloaded CQikAppUi::ViewActivated() function.

void CExampleAppView::ViewActivatedL(const TVwsViewId& aPrevViewId, const TUid aCustomMessageId,const TDesC8& aCustomMessage)
    {
   SetViewToolbarL(R_MY_TOOLBAR, iQikAppUi);
    }

In the future it will be possible to add the QIK_TOOLBAR resource directly into the view's QIK_VIEW resource, making it possible to create and add the toolbar entirely from the resource file. Of course the toolbar's commands will have to be processed from code (see section 3.3).

4) To be able to handle the toolbar's commands you have to overload CQikAppUi::ProcessCommandL() in your own AppUi class. In this example, an alert window with the value from the slider appears when the button is pressed.

void CLibraryBooksAppUi::ProcessCommandL(TInt aCommandId)
    {
    switch(aCommandId)
        {   
        case EMyToolbarButton0:
            {   
                
            //Get a pointer to the view that holds the toolbar (in this case it is the first one)
            CExampleApplicationView* view = static_cast<CExampleApplicationView*>(ViewAsControl(0));                      
            
            if(view)
                {
                //Get the toolbars Button group so that the control can be fetched from it      
                MEikButtonGroup* group = view->ViewToolbar();
                if(group)
                    {
                   //Get the control from the group
                    CCoeControl* ctrl = group->GroupControlById(EMyToolbarSlider);
            
                    //The control was returned as a CCoeControl* and must be cast to a CQikSlider*
                    CQikSlider* slider = static_cast<CQikSlider*>(ctrl);          
                    
                    if(slider)
                        {
                        //Format the message to show the user
                        TBuf<10> KMessage;
                        KMessage.Format(_L("%d"),slider->CurrentValue());  
    
                        //Show the user the message
                        iEikonEnv->AlertWin(KMessage);           
                        }
                    }
                }
            break;
            }
        default:
            {               
            break;
            }
        }
    }