Namespaces

Variants
Actions

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 over the next few weeks. Thanks for all your past and future contributions.

Creating application help for Symbian applications

From Wiki
Jump to: navigation, search

This article shows how to create a Symbian context sensitive help file for your app (written in Qt or Symbian C++).

Article Metadata
Code ExampleTested with
SDK: All/Any
Devices(s): S60 5th Edition and newer.
Compatibility
Platform(s):
Symbian
Platform Security
Capabilities: The application must have a protected UID (0x2-range) in order to use this feature.
Article
Keywords: TCoeHelpContext, HelpContextL()
Created: chitrankgautam (19 Jan 2012)
Last edited: hamishwillee (11 Oct 2012)

Contents

Introduction

Once your Symbian application is ready to be published, it is recommended that you create an application help for your application. The application help provides an overview of the features supported by your application and also describes how to use it. The application help topics must be created in HTML.

You can create an application help in your localized language based on your needs. For the list of languages supported on the Symbian platform, see TLanguage enumeration.

You must be familiar with the following topics to create an application help:

Use cases

This section describes use cases related to creating an application help.

Creating an application help

This topic describes how to create an application help. The device user can launch the application help from Menu > User Guide.

Steps

  1. Create a folder in the folder that contains your Symbian application. For example, you can create a folder with name help.
  2. Download and extract the Helptemplate.zip file to the newly created folder. The following image shows the folder structure of the help template:
    Folder-Structure.png
  3. Navigate to the following path:
    <help_folder>\xhtml\<LANG>\<Help_UID>
    Where:
    • <help_folder> is the name of the folder that you have created in the first step.
    • <LANG> is the language code. For example, 01 represents English and 02 represents French. For more information on other language codes, see TLanguage enumeration.
    • <Help_UID> is the unique UID for the application help. You can get a unique value by using the application UID of your Symbian application as Help UID. You can also merge help content of multiple applications in a single package and differentiate them through different topics.
  4. Unzip the contents.zip file to a folder. It contains two HTML topics, SAMPLE_HLP_TOPIC_1.html and SAMPLE_HLP_TOPIC_2.html. You can rename these files based on your requirements but you must update the index.xml accordingly.
  5. Edit the HTML topics to create the help for your Symbian application. If required, you can add more HTML topics to your application help.
    Note: The content of the HTML topics must be in the language that you have selected.
    Sample HTML files demonstrate how to use the various HTML formatting options. The following image shows the different formatting options generated with example help topic:
    UserGuideSample.png
    You can also cross link the help topics using standard HTML linking format as demonstrated in the SAMPLE_HLP_TOPIC_1.html topic.
    Important:
    • The .css files determine the formatting of the HTML topics in application help. The .css files can be found in the xhtml\theme folder. However, you must not modify the .css files as these files are not delivered as part of your package but linked to the system files in ROM.
    • Avoid using advanced formatting options in HTML topics. Only use the formatting options demonstrated in the sample HTML topics, SAMPLE_HLP_TOPIC_1.html and SAMPLE_HLP_TOPIC_2.html.
    • You are not allowed to modify files under the xhtml\theme folder. However, you can add new files (mostly the image files), but the names of the files must not be same as the files in the xhtml\theme folder on any drives of the Symbian device.
  6. Open the index.xml file from <help_folder>\xhtml\01\Help_UID in an XML editor.
  7. Include all the HTML topics in the index.xml file. For information on how to include HTML topics in index.xml, see Index file.
  8. Zip all the HTML files as contents.zip.
    Notes:
    • Use the standard Winzip format to zip the files.
    • Only the zipped files are used in the application help. Therefore, if you have to edit the HTML files again, make sure that you zip them again.
  9. Include all the HTML topics in the keywords.xml file. The content of this file is used in search.
  10. Integrate and launch the application help. For details, see Integrating and testing the application help.

Launching a Symbian application from an application help

You can enable the device user to launch a Symbian application from an application help by providing a link in the application help. Use the <a> tag in an HTML topic of your application help to provide link to a Symbian application. Note: You must be aware of the path and UID of the Symbian application that you want to launch from your application help.

Steps

  1. Open the HTML topic from which you want to launch the Symbian application.
  2. Add the following code in the HTML topic from where you want to launch the Symbian application:
    <a href="app://cmd@localhost/name_of_the_application_exe/UID_of_the_application">Name_of_the_application</a>
    Where
    • name_of_the_application_exe is the name of the executable of the Symbian application that you want to launch.
      UID_of_the_application is the UID of the Symbian application that you want to launch.
    • Name_of_the_application is the name of the Symbian application that you want to launch.
    For example:
    <a href="app://cmd@localhost/cshelphelloworld_0x2002c37b.exe/0x2002c37b">CS Help Helloworld</a>3.Save the HTML topic.
  3. Integrate the application help with your Symbian application and launch it. For details, see Integrating and testing the application help.

Results

The device user can now launch the Symbian application from the application help by performing the following steps:

  1. Launch the application help and navigate to the HTML topic in which you have added the link.
  2. Click the link to launch the Symbian application which is linked.

Launching a specific help topic from a Symbian application

Steps

  1. Open the .cpp file containing HandleCommandL(TInt aCommand).
  2. Add a menu item Ehelp by adding the following code in HandleCommandL(TInt aCommand):
    case EHelp:
    {
    if (FeatureManager::FeatureSupported(KFeatureIdHelp))
    {
    CArrayFix<TCoeHelpContext> *buf = CCoeAppUi::AppHelpContextL();
    HlpLauncher::LaunchHelpApplicationL(iEikonEnv->WsSession(), buf);
    }
    }
    You must also make appropriate standard arrangements for the Ehelp enum as you do for any menu item.
  3. Add the HelpContextL() function to define the topic that you want to launch from the application.
    The following code demonstrates how to define HelpContextL():
     _LIT(KCXHELPHelloworld_HLP_SETTINGS, "SAMPLE_HLP_TOPIC_1");
    CArrayFix<TCoeHelpContext>* CcshelphelloworldAppUi::HelpContextL() const
    {
    if (FeatureManager::FeatureSupported(KFeatureIdHelp))
    {
    CArrayFixFlat<TCoeHelpContext>* array = new (ELeave) CArrayFixFlat<TCoeHelpContext> (1);
    CleanupStack::PushL(array);
    array->AppendL(
    TCoeHelpContext(KUidcshelphelloworldApp,
    KCXHELPHelloworld_HLP_SETTINGS));
    CleanupStack::Pop(array);
    return array;
    }
    else
    {
    return NULL;
    }
    }
    Notes:
    • The preceding code snippet uses feature manager harness mechanism to launch a help topic from the Symbian application. If you want to use this mechanism, make sure you include <featmgr.h> and link LIBRARY featmgr.lib in your MMP file.
    • The Application UID of the application which needs to launch the application help must be in the protected range. For information on protected and unprotected range of UIDs, see UID Q&As (Symbian Signed).
  4. Integrate the application help with your Symbian application. For details, see Integrating and testing the application help.

Results

The device user can now launch the specific help topic from the Symbian application by performing the following steps:

  1. Launch the application and navigate to the application's view in which Ehelp menu item has been added.
  2. Click the menu item to launch the application help. This opens the help topic that you have linked.

Integrating and testing the application help

This topic describes how to integrate the application help with your Symbian application and test it on emulator and on the Symbian device.

The application help can be integrated and tested on the following platforms:

On emulator

Perform the following steps to integrate and launch the application help on emulator:

  1. Open the bld.inf file of your Symbian application.
  2. Edit the bld.inf file to export contents.zip, index.xml, keywords.xml, meta.xml and images to the c: drive of the emulator and also other appropriate paths.
    For example:
    ../help/xhtml/01/0x2002c37b/contents.zip  	\epoc32\winscw\c\resource\xhtml\01\0x2002c37b\contents.zip
    ../help/xhtml/01/0x2002c37b/index.xml \epoc32\winscw\c\resource\xhtml\01\0x2002c37b\index.xml
    ../help/xhtml/01/0x2002c37b/keywords.xml \epoc32\winscw\c\resource\xhtml\01\0x2002c37b\keywords.xml
    ../help/xhtml/01/0x2002c37b/meta.xml \epoc32\winscw\c\resource\xhtml\01\0x2002c37b\meta.xml
    ../help/xhtml/theme/icons/cshelphelloworld_button1.png \epoc32\winscw\c\resource\xhtml\theme\icons\cshelphelloworld_button1.png
    ../help/xhtml/theme/icons/qgn_cshelphelloworld_caution.gif \epoc32\winscw\c\resource\xhtml\theme\icons\qgn_cshelphelloworld_caution.gif
    ../help/xhtml/theme/icons/qgn_cshelphelloworld_example.gif \epoc32\winscw\c\resource\xhtml\theme\icons\qgn_cshelphelloworld_example.gif
    ../help/xhtml/theme/icons/qgn_cshelphelloworld_link_ref_popup.gif \epoc32\winscw\c\resource\xhtml\theme\icons\qgn_cshelphelloworld_link_ref_popup.gif
    ../help/xhtml/theme/icons/qgn_cshelphelloworld_link_web.gif \epoc32\winscw\c\resource\xhtml\theme\icons\qgn_cshelphelloworld_link_web.gif
    ../help/xhtml/theme/icons/qgn_cshelphelloworld_note.gif \epoc32\winscw\c\resource\xhtml\theme\icons\qgn_cshelphelloworld_note.gif
    ../help/xhtml/theme/icons/qgn_cshelphelloworld_tip.gif \epoc32\winscw\c\resource\xhtml\theme\icons\qgn_cshelphelloworld_tip.gif
    ../help/xhtml/theme/icons/qgn_cshelphelloworld_warning.gif \epoc32\winscw\c\resource\xhtml\theme\icons\qgn_cshelphelloworld_warning.gif3.Save and close the bld.inf file.
  3. Build the Symbian application to export the contents.zip, index.xml, keywords.xml, meta.xml, and images.
  4. Run the emulator.
  5. Launch the application help by selecting Menu > User Guide > App user guide topics > <help>.
    Where <help> is the name of the application help that you have created.
    If you have added the help menu item as instructed in Launching a specific help topic from a Symbian application, you can view the specific help topic by launching the Symbian application and clicking the help menu item.

On the Symbian device

Perform the following steps to integrate and launch the application help on the Symbian device:

  1. Open the .pkg file of your Symbian application.
  2. Ensure that contents.zip, index.xml, keywords.xml, meta.xml and images are included in the .pkg file.
    For example:
    ; all help content related files here till the end of this file.
    "../help/xhtml/01/0x2002c37b/contents.zip" -"!:\resource\xhtml\01\0x2002c37b\contents.zip"
    "../help/xhtml/01/0x2002c37b/index.xml" -"!:\resource\xhtml\01\0x2002c37b\index.xml"
    "../help/xhtml/01/0x2002c37b/keywords.xml" -"!:\resource\xhtml\01\0x2002c37b\keywords.xml"
    "../help/xhtml/01/0x2002c37b/meta.xml" -"!:\resource\xhtml\01\0x2002c37b\meta.xml"
    "../help/xhtml/theme/icons/cshelphelloworld_button1.png" -"!:\resource\xhtml\theme\icons\cshelphelloworld_button1.png"
    "../help/xhtml/theme/icons/qgn_cshelphelloworld_caution.gif" -"!:\resource\xhtml\theme\icons\qgn_cshelphelloworld_caution.gif"
    "../help/xhtml/theme/icons/qgn_cshelphelloworld_example.gif" -"!:\resource\xhtml\theme\icons\qgn_cshelphelloworld_example.gif"
    "../help/xhtml/theme/icons/qgn_cshelphelloworld_link_ref_popup.gif" -"!:\resource\xhtml\theme\icons\qgn_cshelphelloworld_link_ref_popup.gif"
    "../help/xhtml/theme/icons/qgn_cshelphelloworld_link_web.gif" -"!:\resource\xhtml\theme\icons\qgn_cshelphelloworld_link_web.gif"
    "../help/xhtml/theme/icons/qgn_cshelphelloworld_note.gif" -"!:\resource\xhtml\theme\icons\qgn_cshelphelloworld_note.gif"
    "../help/xhtml/theme/icons/qgn_cshelphelloworld_tip.gif" -"!:\resource\xhtml\theme\icons\qgn_cshelphelloworld_tip.gif"
    "../help/xhtml/theme/icons/qgn_cshelphelloworld_warning.gif" -"!:\resource\xhtml\theme\icons\qgn_cshelphelloworld_warning.gif"
  3. Create and sign the SIS file for the Symbian application. For information on how to create and sign a SIS file, see Creating and Signing an Installation File.
  4. Copy the SIS file to the Symbian device and then install it.
  5. Launch the help by selecting Menu > User Guide > App user guide topics > <help>.

Reference

This section provides information about the Index.xml file.

Index file

This topic describes the syntax of the index.xml file.

The index.xml file enables you to include and organize the HTML topics in the application help.

Syntax

<?xml version="1.0" encoding="UTF-8"?><?xml-stylesheet href="../../theme/xsl/index2html.xslt" type="text/xsl"?>
<topics FeatureID="FEATURE_ID" title="TITLE_OF_THE_HELP" compressed="true">
<topicref FeatureID="FEATURE_ID" href="PATH_OF_the_HTML_TOPIC_1" navtitle="TITLE_OF_the_HTML_TOPIC_1"/>
<topicref FeatureID="FEATURE_ID" href="PATH_OF_the_HTML_TOPIC_1" navtitle="TITLE_OF_the_HTML_TOPIC_1"/>
...
...
</topics>

In the preceding code snippet, <topics> is the root element of the index.xml file which includes the <topicref> tags to define topics of the help. The <topics> tag contains the following parameters:

  • FeatureID="FEATURE_ID": Specify the value –1.
  • title="TITLE_OF_THE_HELP": Indicates the title of the application help.

You must add the <topicref> tags in <topics> for the each HTML topic you want to include in the application help. The <topicref> tag contains the following parameters:

  • FeatureID="FEATURE_ID": Specify the value –1.
  • href="PATH_OF_the_HTML_TOPIC_1": Specifies the path of the HTML topic.
  • navtitle="TITLE_OF_the_HTML_TOPIC_1": Specifies the title of the HTML topic.

Note: The values of the title and navtitle must be in the language that you have selected while creating the application help. For example, if you have selected the Chinese language, the values of these parameters must be in that language.

Example

<?xml version="1.0" encoding="UTF-8"?><?xml-stylesheet href="../../theme/xsl/index2html.xslt" type="text/xsl"?>
<topics FeatureID="-1" title="CS Help HelloWorld application" compressed="true">
<topicref FeatureID="-1" href="SAMPLE_HLP_TOPIC_1.html" navtitle="Formatting the content"/>
<topicref FeatureID="-1" href="SAMPLE_HLP_TOPIC_2.html" navtitle="Linking a topic"/>
</topics>

The preceding index.xml file defines the application help for the CS Help HelloWorld application. The application help contains two topics, Formatting the content and Linking a topic.

This page was last modified on 11 October 2012, at 01:16.
60 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×