UIQ Controls - Application Title Bar

The application title bar is used to hold the name and icon for the application. It is possible to set the title and icon from both a resource file and from code. That is what this guide is about.

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.

It is in this class that the functionality for changing the icon and text from code is located.

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.

Packages two bitmaps, one for an icon image and the other for its mask.

It is in this class that you create your icon and then add it to the View Context Bar.

See UIQ API Reference for more information about CQikViewBase and CGulIcon.

The application title bar is placed above the application space.

Use the following #include directives in your view classes.

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

//Include file for the icon
#include <gulicon.h>

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

This example shows how to change the icon and application title in the application title bar.

Symbian OS uses a special multi-bitmap (*.mbm) format for its bitmaps. It contains one or more bitmaps that are compiled into an mbm file, which in turn is used by the application.

The easiest way to create the .mbm file is to specify it in your .mmp file

The mbm icon files are built by adding start bitmap statements to the mmp file, for instance:

START BITMAP Stars.mbm
TARGETPATH \Resource\Apps
SOURCE c24 Star18.bmp Starmask18.bmp Star40.bmp Starmask40.bmp Star64.bmp Starmask64.bmp
END

Note that it is best to give your .mbm file the same name as your application. If it is given another name you will have to specify the full file path when using it from your code. Otherwise it is sufficient to use *. This is mentioned below.

Notice that it is recommended to make three different sizes for the icon used by the application. To read more about this read Icon Size.

1) Declare the text resources in your resource (*.rss) file.

RESOURCE TBUF r_app_title_bar_string { buf = STRING_r_app_title_bar_string; }

2) Declare the text string that the text resource is using in your localizable (*.rls) string file.

rls_string STRING_r_app_title_bar_string "Library Books";

The use of resource strings that are declared in a localizable string file is the recommended way.

3.3.1 Changing the application title

This is the preferred way to change your application's title and icon. If it is possible to perform a certain task by using data in a resource file or by implementing it directly in code, it is generally preferred to use the resource file.

In your *_loc.rss file you have to define a CAPTION_AND_ICON_INFO in the RESOURCE LOCALISABLE_APP_INFO resource struct. It is the caption line that we have change. We will use the localized resource string declared earlier.

CAPTION_AND_ICON_INFO
            {
            caption = STRING_r_app_title_bar_string;
            number_of_icons = 3;
            icon_file = "\\Resource\\Apps\\default_app_icon.mbm";         
            }

3.3.2 Changing the application icon

In your *_loc.rss file you have to define a CAPTION_AND_ICON_INFO in the RESOURCE LOCALISABLE_APP_INFO resource struct. The icon_file line declares where the icon file is located. We will use the .mbm file declared in the .mmp project file. The number_of_icons line declares which pair to use as the icon. To use the first pair, write "1" and for the second pair write "2".

CAPTION_AND_ICON_INFO
            {
            caption = STRING_r_app_title_bar_caption;
            number_of_icons = 3;
            icon_file = "z:\\resource\\apps\\Stars.mbm";
            }

Notice that we have to declare an icon and its mask as a pair, otherwise the operation will fail.

Unless there is some reason for changing the title or icon from code during runtime, this is not recommended. This is partly because categories also use the application title bar.

3.4.1 Changing the application title

If the application uses categories this step is not possible.

From the view class we have to allocate a string from the text string resource. After that, you just need to call CQikViewBase::SetAppTitleNameL(). And finally we cleanup after ourselves.

    //Allocate the text string resource, this will put the string on the cleanup stack
    HBufC* viewContextText = iEikonEnv->AllocReadResourceLC(R_APP_TITLE_BAR_STRING);
    
    //Change the application title
    SetAppTitleNameL(viewContextText->Des());
    
    //Pop and destroy the text string from the cleanup stack
    CleanupStack::PopAndDestroy(viewContextText);
    

3.4.2 Changing the application icon

Create a CGulIcon from the bitmap. We are creating two different icons for demonstration of add and change. Also, we push the icons to the cleanup stack for safe handling. See Cleanup Stack Basics for more information. Do not forget to pop the variables off the cleanup stack when done (see 3.6).

_LIT(KShortSearchPath, "*");
// No bitmap mask. The third argument can be omitted
    CGulIcon* myIcon = iEikonEnv->CreateIconL(KShortSearchPath, EMbmStarsStar1);
    CleanupStack::PushL(myIcon);
    
_LIT(KFullSearchPath, "z:\\Resource\\Apps\Stars.mbm");
    // With bitmap mask which is supplied as a third argument
    CGulIcon* myIcon2 = iEikonEnv->CreateIconL(KFullSearchPath, EMbmStarsStar1, EMbmStarsStarmask);
    CleanupStack::PushL(myIcon2);

Notice that we use a star for the pathname if we gave the .mbm file the same name as the application. Otherwise we use the full path to the .mbm file. The two lines above points to the same mbm file through two different methods.

The second argument is the enumerator name for the icon. This is automatically created in the Hello.mbg and it only needs to include this file. The naming convention for this is as follows:

EMbm

The third argument is the bitmap mask to be used.

    // It is in this file that the enums are defined
    #include <Stars.mbg>

If there is no need for a bitmap mask the third argument should be -1. But since this is the default argument there is no need to supply that at all as can be seen in the first function call.

Set the icon in the application title bar.

    SetAppTitleIconL(myIcon->Bitmap(), myIcon->Mask());
    

3.4.3 Pop the icons off the cleanup stack

Finally you must pop the icons off the cleanup stack when you are done with them. We use the PopAndDestroy function that destroys the items after the item are popped.

Also notice that objects are pushed on and popped off in a strict order: a series of PopAndDestroy() calls must occur in the reverse order of the PushL() calls. This is very important; otherwise you will get a panic message. This is because of the cleanup stack being in imbalance.

    CleanupStack::PopAndDestroy(myIcon2);
    CleanupStack::PopAndDestroy(myIcon);

Application title bar

An area on the mobile phone display located above the application area. The application title bar contains the icon and title for the application.

Bitmap

Provides the pixel patterns used by pictures, icons and masks, sprites and brush styles for filling areas of the display.

Mask

A bitmap whose pixels are used to hinder or allow the individual pixels of another bitmap to be written to a graphics device.

Multiple Bitmap (Mbm)

Symbian OS multiple bitmap file. This file is compiled from one or more bitmap files into one .mbm file.