UIQ Controls - How to handle icons in the View Context

This guide explains the process of adding and changing icons in the view context bar control.

Adding text in the view context bar is quite simple because the functionality for this is gathered in just one class. The view class itself handles tabs.

The view context bar is owned by the view and is not shared with other views.

MQikViewContext is the interface the view class uses for adding, removing, and handling contexts in the view context bar. Through this interface, text and icons are added to the context bar.

All views are derived, directly or indirectly, from CQikViewBase.

The view context bar can contain different types of controls. Text and icons are handled through the MQikViewContext class and tabs are handled directly through the view class which is derived from CQikViewBase.

An icon is actually made up of two bitmaps. One bitmap is for the image and the other bitmap is for the mask. The class which holds these two bitmaps is CGulIcon. Icons are handled through pointers to instances of CGulIcon.

Once you have created the two bitmaps for an icon, use the CEikonEnv member function CreateIconL() to package your bitmaps in a CGulIcon object and return a pointer to it.

Read more about screen layout in the UIQ Style Guide.

See UIQ API Reference for MQikViewContext, CQikViewBase and CGulIcon.

Use the following #include directives in your view class:

#include <QikViewBase.h>
#include <gulicon.h>

1) Create the bitmaps to be used in the application. This can be done using your favorite graphical software, for example, Microsoft ® Paint or Jasc ® Paint Shop Pro. Save them in a suitable location in your code library.

If you are going to use more than one image it is good practice to store them in an images library. The resolution for icons used in the view context bar is 18x18 pixels.

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

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

The .mbm icon files are built by adding start bitmap statements in the .mmp file, for example:

START BITMAP Stars.mbm
TARGETPATH \Resource\Apps
SOURCE c24 Star1.bmp Star2.bmp Starmask.bmp
END

For information about the code above see the link above. Observe 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.

Declare an enumeration for the control to be used in the view in a .hrh file, which is included in both resource files, .rss, and C++ files:

/*
   Declare the control ID in the .hrh file for use both in resource and cpp.
   This is the control ID and also the order in which the icons are placed.
*/

enum TMyViewControls
 {
 KIconSlot=1
 };

In your view class, use the CEikonEnv member function CreateIconL() to package the two bitmaps for an icon and return a pointer to the CGulIcon object which holds them.

Here we present two examples of creating icons and variables to access them. In both examples, the name of the application that contains the view is "Stars".

The first example creates an icon that does not need a mask.

// No bitmap mask. The third argument is not necessary.
CGulIcon* myIcon = iEikonEnv->CreateIconL(_L("z:\\Resource\\Apps\Stars.mbm"), EMbmStarsStar1);
CleanupStack::PushL(myIcon);

A variation of the first example is to use the wildcard "*" instead of the pathname to the .mbm file. In that case, the default application resource file will be used.

// No bitmap mask. The third argument is not necessary.
CGulIcon* myIcon = iEikonEnv->CreateIconL(_L("*"), EMbmStarsStar1);
CleanupStack::PushL(myIcon);

The variable that is created in the first example, myIcon, will be used to demonstrate how an icon is added to the view context bar in section 3.5.

The second example creates an icon that uses a mask.

// With bitmap mask which is supplied as a third argument.
CGulIcon* myIcon2 = iEikonEnv->CreateIconL(_L("z:\\Resource\\Apps\Planet.mbm"), EMbmStarsPlanet, EMbmStarsPlanetmask);
CleanupStack::PushL(myIcon2);

The third argument in CreateIconL() is the bitmap mask to be used. 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 it at all as can be seen in the first example.

The variable that is created in the second example, myIcon2, will be used to demonstrate how an icon is changed in the view context bar in section 3.6.

Here, "*" cannot replace the pathname to the .mbm file because we are not using the default application resource file.

Note that in both examples, we pushed the icons to the cleanup stack for safe handling. See cleanup stack for more information. The variables must be popped off the cleanup stack when we are done as is shown in section 3.7.

The second and third arguments in CreatIconL() are enumerations that name the bitmaps to use. These enumerations are automatically created in the application's .mbg file. All you need to do is include this file. For our examples the include would be:

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

The naming convention for the enumerations is EMbm.

1) To be able to add icons to the view context bar, an interface has to be retrieved through the view.

MQikViewContext* viewContext = ViewContext();

2) From here it is simply a matter of calling the MQikViewContext::AddIconL() function.

viewContext->AddIconL(KIconSlot, myIcon->Bitmap(), myIcon->Mask());

// We have to set the icon to owned externally as the view context takes over ownership.
myIcon->SetBitmapsOwnedExternally(ETrue);

The KIconSlot is a control ID that represents in what order the icons are placed. The lowest number is placed furthest to the left. Do not use 0 and 1000. These numbers are reserved.

1) To be able to change an icon in the view context bar, an interface has to be retrieved through the view.

MQikViewContext* viewContext = ViewContext();

2) From here it is simply a matter of calling the MQikViewContext::ChangeIconL() function.

viewContext->ChangeIconL(KIconSlot, myIcon2->Bitmap(), myIcon2->Mask());

// We have to set the icon to owned externally as the view context takes over ownership.
myIcon2->SetBitmapsOwnedExternally(ETrue);

The KIconSlot is a control ID that represents an already existing icon ID.

Finally, you must pop the icons of 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);

Bitmap

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

Bitmap 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 File .mbm

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