Help Framework HOWTO

This document has been reviewed for maemo 4.0.

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

The Help Framework is a centralized way to offer help services to the user of the program. Maemo platform has an in-built help system that handles all the help documentation for the programs using the Help Framework. Libraries are used to register a program to the Help Framework, and after that the content of the actual help documentation can be written. An ID tag will be given to the help file, which will be in XML format. This way it is possible to control which help file will be loaded, when user asks for help: it is only necessary to call the correct help content ID. When using the Help Framework, the help documentation for a program will also be available when using the 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 an application, by going through an example in which a small program is written to utilize the framework. The document also explains the XML format that is used in the actual writing of the help content.

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>
    <title>Help Framework Example</title>
    <topic>
      <topictitle>Main Topic</topictitle>
      <context contextUID="osso_example_help" />
      <para>This is a help file with example content.</para>
    </topic>
  </folder>
</ossohelpsource>

The <context /> 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).

In the example above, context UID osso_example_help was created and it will be used in the example application.

In addition to the <context /> tag, there are various other tags. Below is a list of the tags with a short description:

• folder
  Contains help topics, one or more.
• title
  Title text for the folder to be shown in the Contents list of the Help application. Usually it is 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. N.B. Not all the topics require a heading, because the topictitle is used as the main heading of a topic. Headings are formatted with a 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. To use them, either the absolute path (with 'filename' parameter), or the plain filename has to be defined. The former is used to show third-party pictures, while the latter is used to show 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 the contextUID of the referred topic, 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 the Global search, and are not visible to the users. Synonyms can be used as extra keywords for search.

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

The example XML file can be downloaded from help-framework downloads.

This section will demonstrate how to create an application with an online help system. The 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 the application:

#include <libosso.h>
#include <hildon/hildon-help.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 hildon/hildon-help.h file contains prototypes for functions in the library hildon-help. These are used for locating the help topics and displaying these topics for the user.

Next, after including these files into the source code, a couple of pre-compilation macros are defined 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 the application, two steps are necessary:

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

The following example shows in detail, how this initialization must be performed:

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 the hildon help system can be used. To show one of the topics from the help file, the function hildon_help_show() has to be called, like the example below shows.

In case the topic is not available, the function hildon_help_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 = hildon_help_show(
      appdata.osso_context, /* global osso_context */
      help_id,              /* topic id */
      HILDON_HELP_SHOW_DIALOG);
}

To create a button to activate help, the following code should be added into the main function:

   /* 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 '?' on the upper right-hand corner of the dialog box). The process is quite simple: the button is enabled in the dialog box with the function hildon_help_dialog_help_enable(). The example below shows how this is 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 */
   hildon_help_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 the only thing needed is to compile the example:

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

It is possible to test the help system also in Scratchbox. You can download the example application and code snippets from here:

• Help-Framework examples

To quickly test the help content, the XML file can be manually copied to the correct path (e.g. /usr/share/osso-help/en_GB/), where it can be found by the help library. The directories may have to be created manually, if testing in Scratchbox. If the help file is written for some other language, en_GB in the path should be replaced with the correct language definition. After starting the newly-created application (or Help application), the help content should be available for viewing. The easiest way to distribute the help file and the application is to create an Application Manager package. For more details, please see Making Application Packages.