Additional Resources

   

---

Mobile Project Composition

Now, let's examine the project file structure for our "Made in Borland" Hello World application.

The obvious way to view files that are associated to a project in C++Builder is by examining the Project Manager dialog as illustrated in Figure B.7.

Figure B.7. Project Manager Dialog for the "Made in Borland" Hello World Application.

There are a number of different types of files used to represent a project for a mobile application. They include one or more Mobile Management Project (MMP) files, a component description file identified as BLD.INF , and a Package Description (PKG) file. In addition to these three types of files, traditional source (CPP) and header (H) files are created by the developer to represent the aspects of the mobile application. Also, a resource (RSS) file containing UI definitions can be used and created within a mobile application project.

MOBILE EDITOR

The Project Files tab found on the Mobile Options dialog, which we used earlier to modify the project options, displays the principal files associated to our mobile project and is illustrated in Figure B.8.

Figure B.8. Project Options dialog ”Project Files Tab.

In this figure, two files are identified: HelloWorld.mmp and bld.inf . One of the tools Borland has provided with the C++ Mobile Edition is the Mobile Editor dialog. If you select view for either one of the two files listed in the Project Files tab the Mobile Editor dialog will appear, as illustrated in Figure B.9.

Figure B.9. Mobile Editor.

The Mobile Editor is a useful tool for constructing and adding elements to MMP, INF, and PKG files. The left column identifies the key elements that can be added to the file that is displayed on the right panel, which serves as an editor. By double-clicking a key element it will be reflected at the cursor position within the editor on the right side.

MMP Files

An MMP file defines the properties of a mobile application project. An example is provided in Listing B.1.

Listing B.1 The MadeInBorland.MMP File

 TARGET MadeInBorland.app  TARGETTYPE app  UID 0x100039CE 0x10004299  TARGETPATH \system\apps\MadeInBorland  SOURCEPATH .  SOURCE MadeInBorland _Main.cpp  SOURCE MadeInBorland _Application.cpp  SOURCE MadeInBorland _Document.cpp  SOURCE MadeInBorland _AppUi.cpp  SOURCE MadeInBorland _AppView.cpp  USERINCLUDE .  SYSTEMINCLUDE \epoc32\include  RESOURCE MadeInBorland.rss  LIBRARY euser.lib apparc.lib cone.lib eikcore.lib 

Within this file, there are no dependencies on the intended target platform or the compiler. It typically identifies the target filename, the target type, a Unique ID for the project, the source path indicating the location of the source files, the names of the source files being used, the location of the user and system include files, and any resource or library files that might be required. Comments within the MMP file can be made using C++ style comments.

Multiple MMP files can be included within a mobile application project. If your mobile application contains more than one module or DLL, you should include separate MMP files.

BLD.INF File

Every mobile application project has a BLD.INF file, which identifies all the components of the projects. The BLD.INF file enables you to specify the MMP files required for building the components associated to the mobile application. Table B.1 identifies the elements of a BLD.INF file.

Table B.1. BLD.INF Elements

Element	Description
PRJ_PLATFORMS	Identifies the type of platform to which you are deploying.
PRJ_EXPORTS	Used to specify the source file.
PRJ_MMPFILES	Used to identify the MMP files.
PRJ_TESTMMPFILES	Used to identify MMP files for test only.

In our example, the BLD.INF file is shown in Listing B.2.

Listing B.2 The MadeInBorland BLD.INF File

 // BLD.INF  //  // Made In Borland - Hello World app for  // C++Builder Deverloper's Guide  // Paul Gustavson  //  // Based on the HelloWorld example provided with the Symbian SDK  //  PRJ_MMPFILES  HelloWorld.mmp  

You'll notice this BLD.INF file is very simple. We only needed to identify the MMP file using PRJ_MMPFILES tag. As your confidence grows in developing mobile applications, you'll find that your BLD.INF file will become meatier.

Source Code Files

Like standard C++ applications, a mobile project contains one or more header files, source files, resource files and, sometimes, localization files.

Header File

In our example, we have one central header file that identifies the key classes required for our Hello World application. This header file is provided in Listing B.3.

Listing B.3 The "Made in Borland" HelloWorld.h File

 // HelloWorld.h  //        //  // Made In Borland - Hello World app for  // C++Builder Deverloper's Guide  // Paul Gustavson  //  // Based on the HelloWorld example provided with the Symbian SDK  //  ////////////////////////////////////////////////////////////////////  // MadeInBorland (HelloWorld app)  //       //  //  // The class definitions for the simple example application  // containing a single view with the text "Made In Borland" drawn  // on it.  //  // The class definitions are:  //  // CExampleApplication  // CExampleAppUi  // CExampleAppView  // CExampleDocument  //  //  ////////////////////////////////////////////////////////////////////  #ifndef __HELLOWORLD_H  #define __HELLOWORLD_H  #include <coeccntx.h>  #include <eikenv.h>  #include <eikappui.h>  #include <eikapp.h>  #include <eikdoc.h>  #include <eikmenup.h>  #include <eikon.hrh>  #include <helloworld.rsg>  #include "helloworld.hrh"  ////////////////////////////////////////////////////////////////////////  //  // CExampleApplication  //  ////////////////////////////////////////////////////////////////////////  class CExampleApplication : public CEikApplication        {  private:                  // Inherited from class CApaApplication        CApaDocument* CreateDocumentL();        TUid AppDllUid() const;        };  ////////////////////////////////////////////////////////////////////////  //  // CExampleAppView  //  ////////////////////////////////////////////////////////////////////////  class CExampleAppView : public CCoeControl      {  public:       static CExampleAppView* NewL(const TRect& aRect);       CExampleAppView();       ~CExampleAppView();      void ConstructL(const TRect& aRect);  private:                  // Inherited from CCoeControl       void Draw(const TRect& /*aRect*/) const;  private:  HBufC*  iExampleText;      };  ////////////////////////////////////////////////////////////////////////  //  // CExampleAppUi  //  ////////////////////////////////////////////////////////////////////////  class CExampleAppUi : public CEikAppUi      {  public:      void ConstructL();       ~CExampleAppUi();  private:                // Inherirted from class CEikAppUi       void HandleCommandL(TInt aCommand);  private:       CCoeControl* iAppView;       };  ////////////////////////////////////////////////////////////////////////  //  // CExampleDocument  //  ////////////////////////////////////////////////////////////////////////  class CExampleDocument : public CEikDocument       {  public:       static CExampleDocument* NewL(CEikApplication& aApp);       CExampleDocument(CEikApplication& aApp);       void ConstructL();  private:                  // Inherited from CEikDocument       CEikAppUi* CreateAppUiL();       };  #endif  

This header file identifies the classes that are defined within the multiple source files associated to our mobile project.

Source Files

A mobile application is typically composed of a number of C++ source files. In our example, each source file defines one of the specific classes identified by our HelloWorld.h header file. Rather than examining each source file pertaining to our example, we'll look strictly at the HelloWorld_AppView.cpp source file that defines the CExampleAppView class. This file is shown in Listing B.4.

Listing B.4 The "Made in Borland" HelloWorld_AppView.cpp File

 // HelloWorld_CExampleAppView.cpp  //   //  ////////////////////////////////////////////////////////////////////////  //  // Source file for the implementation of the  // application view class - CExampleAppView  //  ////////////////////////////////////////////////////////////////////////  #include "HelloWorld.h"  //  //             Constructor for the view.  //  CExampleAppView::CExampleAppView()       {       }  //             Static NewL() function to start the standard two  //             phase construction.  //  CExampleAppView* CExampleAppView::NewL(const TRect& aRect)       {       CExampleAppView* self = new(ELeave) CExampleAppView();       CleanupStack::PushL(self);       self->ConstructL(aRect);       CleanupStack::Pop();       return self;       }  //  //             Destructor for the view.  //  CExampleAppView::~CExampleAppView()       {       delete iExampleText;       }  //             Second phase construction.  //  void CExampleAppView::ConstructL(const TRect& aRect)      {                           // Fetch the text from the resource file.        iExampleText = iEikonEnv->AllocReadResourceL(R_EXAMPLE_TEXT_HELLO);                   // Control is a window owning control        CreateWindowL();                   // Extent of the control. This is                   // the whole rectangle available to application.                   // The rectangle is passed to us from the application UI.        SetRect(aRect);                            // At this stage, the control is ready to draw so                   // we tell the UI framework by activating it.        ActivateL();        }  //             Drawing the view - in this example,  //             consists of drawing a simple outline rectangle  //             and then drawing the text in the middle.  //             We use the Normal font supplied by the UI.  //  //             In this example, we don't use the redraw  //             region because it's easier to redraw to  //             the whole client area.  //  void CExampleAppView::Draw(const TRect& /*aRect*/) const        {                 // Window graphics context        CWindowGc& gc = SystemGc();                   // Area in which we shall draw        TRect      drawRect = Rect();                            // Font used for drawing text        const CFont*     fontUsed;                   // Start with a clear screen        gc.Clear();                            // Draw an outline rectangle (the default pen                   // and brush styles ensure this) slightly                   // smaller than the drawing area.        drawRect.Shrink(10,10);        gc.DrawRect(drawRect);                 // Use the title font supplied by the UI        fontUsed = iEikonEnv->TitleFont();        gc.UseFont(fontUsed);                            // Draw the text in the middle of the rectangle.        TInt   baselineOffset=(drawRect.Height() - fontUsed->HeightInPixels())/2;        gc.DrawText(*iExampleText,drawRect,baselineOffset,CGraphicsContext::ECenter,0);                 // Finished using the font        gc.DiscardFont();        }  

In the ConstructL() method for the CExampleAppView class provided in this code listing, text identified by the R_EXAMPLE_TEXT_HELLO is fetched from the resource file and contained in the iExampleText class property. In a moment we will look at this resource file that contains this string.

In the Draw() method, a Symbian windows graphics context is created. A rectangle and the string associated to the iExampleText is then drawn to this graphics context. Notice the use of Symbian OS API calls in many of these methods .

Resource File

Let's now take a look at the resource file associated for our "Made in Borland" Hello World project. The MadeInBorland.RSS file is provided in Listing B.5.

Listing B.5 The "Made in Borland" HelloWorld.RSS Resource File

 // HelloWorld.RSS  //  // Made In Borland - Hello World app for  // C++Builder Deverloper's Guide  // Paul Gustavson  //  // Based on the HelloWorld example provided with the Symbian SDK  NAME HEWO  #include <eikon.rh>  #include <eikcore.rsg>  #include "helloworld.hrh"  RESOURCE RSS_SIGNATURE { }  RESOURCE TBUF { buf=""; }  RESOURCE EIK_APP_INFO        {        hotkeys=r_example_hotkeys;        menubar=r_example_menubar;        }  RESOURCE HOTKEYS r_example_hotkeys      {      control=  {          HOTKEY { command=EEikCmdExit; key='e'; }          };      }  RESOURCE MENU_BAR r_example_menubar      {      titles=          {          MENU_TITLE { menu_pane=r_example_first_menu; txt="MBorland"; }                };      }  RESOURCE MENU_PANE r_example_first_menu        {        items=                {                MENU_ITEM { command=EExampleItem0; txt="Item 0"; },                MENU_ITEM { command=EExampleItem1; txt="Item 1"; },                MENU_ITEM { command=EExampleItem2; txt="Item 2"; }          };      }  RESOURCE TBUF r_example_text_Hello { buf="Made In Borland"; }  RESOURCE TBUF r_example_text_Item0 { buf="Item 0"; }  RESOURCE TBUF r_example_text_Item1 { buf="Item 1"; }  RESOURCE TBUF r_example_text_Item2 { buf="Item 2"; }  

Notice the r_example_text_Hello resource string that identifies the tag that we want displayed when this application is launched.

Additional Files

There are other files associated to a mobile project that you might encounter as well. One, for example, is a multi-bitmap (MBM) file, which represents the Symbian OS icon used for a mobile application. The common tool used to create and modify MBM files is the Icon Designer that is part of AIF Builder utility application provided with the Symbian OS SDK. The AIF builder is a Java application (thus another reason for the JRE). Another file is an Application Information File (AIF), which is used to describe the application features such as icons and captions. This AIF file is generated from an RSS file.

In a moment we'll also talk about the Package Description (PKG) files and Symbian Installation System (SIS) files used for deploying a mobile application.

GUIDELINES FOR MOBILE DEVELOPMENT

Keep in mind that a mobile device does not have as much functionality or screen space as a desktop or laptop. Furthermore, the functionality and screen space varies greatly among mobile devices such as cell phones and Personal Digital Assistants (PDAs). For instance, the standard form factor for a Series 60 device, such as the Nokia 3650, provides a screen size resolution of 176x208 pixels, which is relatively large for a cell phone. A typical PocketPC, however, provides a resolution of 320x240 pixels.

If you're developing for the Series 60 device, the good news is that the same user interface and form factor can be used by all series 60 licenses, including Nokia, Siemens, Samsung, and Matsushita (Panasonic). This allows applications targeted for a Series 60 device immediate portability across the major phone manufacturers.

Therefore, the mobile applications you develop need to be practical and easy to use. In addition, the majority of mobile devices have limited keyboards, memory space, and power capacity. The design of a mobile application needs to consider these attributes. Focus on easy navigation and efficient memory management. It's recommended that you refer to the mobile SDK documentation during design and development, which provides an API reference and Style guides for the device you're targeting.

---

Top