Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries. Thanks for all your past and future contributions.

Implementing context-sensitive help on Symbian

From Wiki
Jump to: navigation, search
Article Metadata
Tested with
Devices(s): Nokia E90 Communicator
Nokia 5800 XpressMusic
Platform(s): S60 3rd Edition
S60 3rd Edition, FP1
S60 3rd Edition, FP2
S60 5th Edition
S60 5th Edition
S60 3rd Edition FP2
S60 3rd Edition FP1
S60 3rd Edition (initial release)
Keywords: HlpLauncher
Created: tapiolaitinen (31 Jan 2008)
Last edited: lpvalente (18 Jul 2012)


This code example describes how to implement context-sensitive help for an application.

IMPORTANT: In order to use context-sensitive help, you need to apply for a protected UID from Symbian for the help file (if you use an uprotected UID, the help file(s) of the application cannot be launched from the application). The UID3 of the actual application binary does not necessarily have to be protected. However, it should be different from the UID of the help file.

This snippet can be self-signed (the protected UID of the Help file does not prevent self-signing).


1. Create a directory for help files (for example, help).

2. Write the help file (.rtf). Use the file as a template. The file can be found under the SDK (for example, C:\Symbian\9.2\S60_3rd_FP1\Epoc32\cshlpcmp_template\

3. Open the rtf file in a text editor and delete the formatting instruction that Word has created:

  • {\*\wgrffmtfilter XXXX} in Word version 11.8134.8132, or
  • {\*\generator Microsoft Word 10.0.6612;} in Word version 10.0.6612.

4. Write the XML file (help\help.xml) for the application:

<?xml version="1.0" encoding="UTF-8"?>
<?xml:stylesheet href="\epoc32\tools\cshlpcmp\xsl\CSHproj.xsl"
title="CS Help project" type="text/xsl"?>
<!DOCTYPE cshproj SYSTEM "\epoc32\tools\cshlpcmp\dtd\CSHproj.dtd">
<helpfileUID>0x2000E190</helpfileUID> <!-- From help file -->

5. Write the XML file (help\custom.xml) for style declarations:

<?xml version="1.0"?>
<!DOCTYPE cshcust SYSTEM "\epoc32\tools\cshlpcmp\dtd\CSHcust.dtd">
<?xml:stylesheet href="\epoc32\tools\cshlpcmp\xsl\cshcust.xsl"
title="CS Help customization" type="text/xsl"?>
<parastyle name="body" font="sansserif" size="10"/>
<parastyle name="note" font="sansserif" size="10" left="20">
<body style="body"/>
<titlestyle fontstyle="sansserif" size="10"/>
<listbullet1style bulletchar="8226"/>
<listbullet2style bulletchar="8226"/>
<lists leftindent="20"/>

6. Create a makefile (group\ that compiles the help files:

makmake :
cshlpcmp ..\help\help.xml
ifeq (WINS, $(findstring WINS, $(PLATFORM)))
copy ..\help\help.hlp $(EPOCROOT)\epoc32\$(PLATFORM)\c\resource\help
clean :
del ..\help\help.hlp
del ..\help\help.hlp.hrh
bld :
cshlpcmp ..\help\help.xml
ifeq (WINS, $(findstring WINS, $(PLATFORM)))
copy ..\help\help.hlp $(EPOCROOT)\epoc32\$(PLATFORM)\c\resource\help
freeze lib cleanlib final resource savespace releasables :

Note: When editing the makefile, make sure that you use tabulators instead of spaces, or you get the error "HELP.MK:27: *** missing separator. Stop."

7. Edit group\bld.inf to contain the makefile created above:

#ifdef EKA2 //3rd edition
#else //1st and 2nd edition

Note: Remember to run bldmake bldfiles after editing the bld.inf file.

8. Add the help files and the help launcher library to the mmp file of the application (group\[app].mmp):

USERINCLUDE       ..\help
DOCUMENT help.rtf
DOCUMENT help.xml
DOCUMENT custom.xml
LIBRARY hlplch.lib // help

9. Add .hlp file to the package file of the application (sis\[app].pkg):

"..\help\help.hlp" - "!:\resource\help\help.hlp"

10. Add the constant for the help command (EClientHelp) to inc\[app].hrh file:

// Client enumerate command codes
enum TClientIds
EClientHelp = 1 // start value must not be 0

11. Add UID to inc\[app]Application.h:

const TUid KUidHelpFile = {0x2000E190};  // From the help file

12. Add the localization strings to localized data files (for example, data\[app]_loc.l01):

#define STRING_r_app_options_help  "Help"

13. Add the menu item to the RESOURCE MENU_PANE section of the application resource file (data\[app].rss):

command = EClientHelp;
txt = STRING_r_app_options_help;

14. Add the code associated to the help command to the HandleCommandL function of the AppUI (src\[app]AppUi.cpp) file:

#include <hlplch.h>  // HlpLauncher
case EClientHelp:
CArrayFix <TCoeHelpContext>* buf = CCoeAppUi::AppHelpContextL();
HlpLauncher::LaunchHelpApplicationL(iEikonEnv->WsSession(), buf);

15. Override the HelpContextL function:

(inc\[app]AppUi.h part):

private: // from CAknAppUi
* HelpContextL()
* Returns the help context for this application
* Returns:
* A pointer to the help context

CArrayFix<TCoeHelpContext>* HelpContextL() const;

(src\[app]AppUi.cpp part):

#include "[app]Application.h"
#include "help.hlp.hrh"
// ----------------------------------------------------------------------------
// CClientAppUi::HelpContextL()
// Return the help context for this application.
// ----------------------------------------------------------------------------
CArrayFix <TCoeHelpContext>* CClientAppUi::HelpContextL() const
CArrayFixFlat <TCoeHelpContext>* array =
new (ELeave) CArrayFixFlat <TCoeHelpContext>(1);
// KContextApplication below should refer to the context declared in
// help.rtf
array->AppendL(TCoeHelpContext(KUidHelpFile, KContextApplication));
return array;

16. Override the GetHelpContext function:

(inc\[app]AppView.h part):

* From CoeControl
* Identify the help context so that the framework can look up
* the corresponding help topic
* @param aContext The help context

void GetHelpContext(TCoeHelpContext& aContext) const;

(src\[app]AppView.cpp part):

#include "[app]Application.h"
#include "help.hlp.hrh"
// -----------------------------------------------------------------------------
// CClientAppView::GetHelpContext()
// Gets the control's help context.
// -----------------------------------------------------------------------------
void CClientAppView::GetHelpContext(TCoeHelpContext& aContext) const
// Get the help context for the application
aContext.iMajor = KUidHelpFile;
// KContextApplication below should refer to the context declared in
// help.rtf
aContext.iContext = KContextApplication;

See also

This page was last modified on 18 July 2012, at 16:23.
40 page views in the last 30 days.