Help Framework HOWTO

Introduction

This document has been reviewed for maemo 3.x.

Various services are available for software developed on the maemo platform. One of them is the Help Framework, a context based help system, which can be easily used in any application.

The Help Framework is a centralized way to offer the user help services for your program. Maemo platform has inbuilt help system that handles all help documentation for the programs using the Help Framework. You only make use of the libraries that register your program to the Help Framework, and write the content of the actual help documentation. An ID tag will be given to the help file, which will be in XML format. This way you can control which help file will be loaded, when user asks for help, just by calling the right help content ID. When using the Help Framework, the help documentation for your program will also be available when using maemo Platform Help application.

This document is a short guide for using the Help Framework. It focuses on the explanation of the various steps necessary to enable this feature in your application, by going through an example in which a small program is written to use the framework. Also the XML format in which the help content is actually written is explained. The current version of this document was updated specifically for maemo SDK version 3.x, and it is subject to changes, as new versions of the SDK become available.

The examples discussed in this document can be downloaded from help-framework downloads.

Creating the Help File

The help file is an XML document, with various pre-defined tags, used to aid the creation of help topics. The example below shows the format this file must obey:

<?xml version="1.0" encoding="UTF-8"?>

<ossohelpsource>
  <folder>
    <h2>Help Framework Example</h2>
    <topic>
      <topich2>Main Topic</topich2>

      <context contextUID="osso_example_help" />
      <para>This is a help file with example content.</para>
    </topic>
  </folder>

</ossohelpsource>

The tag is used to define the topic "context", which is needed for referring the document by the help framework. The context string is defined by the attribute contextUID and must follow the format xxx_filename_yyy, where filename must be exactly the name of the XML file (without the extension).

Here we've created the osso_example_help context UID that will be used in our application.

In addition to the tag, below is a list of available tags with a short description:

• folder
  Contains help topics, one or more.
• title
  Title text for the folder to be shown in the Help application's Contents list, usually the name of the application.
• topic
  Single help content to be shown for the user. Every topic can be referred via its unique contextUID.
• topictitle
  Title text for the topic to be shown under the main title in the folder list.
• heading
  Can be used in long help pages to separate different subsections. Note that headings aren't needed for all topics because the topictitle is used as a topic's main heading. Headings are formatted with different color and bigger and bolder font.
• display_text
  Used for presenting text that appears on the device display, like button labels etc. Display text is formatted with a different color in the Help application.
• graphic
  Used to show in-line images among the text. You have to define either the absolute path (with 'filename' parameter) to show third-party pictures or the plain filename when using system images.
• task_seq
  Used for task sequence ordered lists.
• step
  Used to define a step in a task sequence ordered list.
• list
  Used for unordered lists.
• listitem
  Used for an item in an unordered list.
• para
  A general paragraph.
• tip
  Shows a "Tip:" prefix.
• note
  Shows a "Note:" prefix.
• important
  Shows an "Important:" prefix.
• example
  Shows an "Example:" prefix.
• warning
  Shows a "Warning:" prefix.
• ref
  Used to create a cross-reference, 'refid' parameter defines referred topic's contextUID and 'refdoc' parameter is the name of the reference.
• emphasis
  Used to emphasize the text.
• ossohelpsource
  Main XML tag for the help files.
• change_history
  Change history of the help content. Used only by help content authors (see change).
• change
  Entry on change_history.
• synonyms
  Synonyms are only used by Global search and aren't shown for the users. Synonyms are extra keywords for search.

Also common HTML tags like <b> for bold text and <i> for italic can be used.

The link to the example files is in the end of this document.

Adding help context support into the application

In this section we will demonstrate, how to create an application with an online help system. This application will use the XML file described in the previous section.

To use the online help system on the maemo platform, it is necessary to include the following header files into your application:

#include <libosso.h>
#include <osso-helplib.h>

The header file libosso.h provides the environment initialization functions of the maemo platform, which are responsible for registering the context used by the application for the help framework.

The osso-helplib.h file contains prototypes for functions in the library osso-help. These are used for locating the help topics and displaying these topics for the user.

Next, after including these files into your source code, we define a few precompilation macros to help the build in the future. It is also important to define a global structure for the application to save HildonProgram, HildonWindow, and osso_context_t, which are, respectively, application object, main window, and application context object of our program.

/* Help topic */
#define OSSO_HELP_TOPIC_EXAMPLE "osso_example_help"

/* Application UI data struct */
typedef struct {
   HildonProgram *program;
   HildonWindow *window;
   osso_context_t *osso_context;
} AppData;

AppData appdata; /* global appdata */

To start our application you need these two steps:

• Initialize the GTK+ library by calling the function gtk_init().
• Initialize the application context using osso_initialize().

In the following example you can see in details how this initialization must be done:

int main(int argc, char *argv[]) {
   /* Initialize GTK. */
   gtk_init(&argc, &argv);

   /* Initialize maemo application */
   appdata.osso_context = osso_initialize(
               "example_help_framework", /* app name */
               "0.0.1",                  /* app version */
               TRUE,
               NULL
            );

   /* Check that initialization was ok */
   if (appdata.osso_context == NULL)
      return OSSO_ERROR;
}

Now we are able to use the maemo help system. To show one of the topics from our help file, you just need to call the function ossohelp_show(), as per the example below.

In case the topic is not available, the function ossohelp_show() will return the error code OSSO_ERROR.

/* handler for Help button */
void help_activated(GtkWidget *win, gchar *help_id)
{
   osso_return_t retval;

   if (!help_id)
      return;

   retval = ossohelp_show(
      appdata.osso_context, /* global osso_context */
      help_id,              /* topic id */
      OSSO_HELP_SHOW_DIALOG);
}

Add this code into the main function to create a button to activate help:

   /* add a Help button */
   help_button = gtk_button_new_with_label("Help");
   g_signal_connect(G_OBJECT(help_button), "clicked",
      G_CALLBACK(help_activated),
      OSSO_HELP_TOPIC_EXAMPLE);

The next step is to add a help button into a dialog box (symbol '?' at the upper right corner of dialog box). The process is quite simple: just enable the button in the dialog box with the function ossohelp_dialog_help_enable(). In the example below, we show how this can be done.

void show_dialog(GtkWidget *widget, gpointer data) {
   /* Enabling "?" button on dialog boxes */
   GtkWidget *dialog;
   guint result;

   dialog = hildon_color_selector_new(GTK_WIDGET(appdata.window));

   /* enable help system on dialog */
   ossohelp_dialog_help_enable(
        GTK_DIALOG(dialog),
        OSSO_HELP_TOPIC_EXAMPLE,
        appdata.osso_context
   );

   result = gtk_dialog_run(GTK_DIALOG(dialog));
   gtk_widget_destroy(dialog);
}

Now we only need to compile our example:

gcc `pkg-config --cflags --libs hildon-libs libosso libossohelp` \
   -o example_help_framework example_help_framework.c

Since the SDK 2.0 it has been possible to test the help system in the scratchbox, too. You can download the example application and code snippets from here:

• Help-Framework examples

Distributing the example application

To quickly test your help content you can manually copy the XML file to a correct path (e.g. /usr/share/osso-help/en_GB/) where it can be found by the help library. You may have to create these directories manually if testing in scratchbox. Replace the en_GB path by the correct language definition if your help is written for some other language. When you start your newly created application (or Help application) you should be able to show your help content. The easiest way to distribute help file and application is to create an Application Manager package.