Help framework guide

Abstract

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. This document focuses on the explanation of the various steps necessary to enable this feature in your application. The current version of this document was updated specifically for maemo SDK version 2.1, and is subject to changes, as new versions of the SDK become available.

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

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 conform to:

<?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).

This is the osso_example_help context UID that is used in the application.

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 displayed in the Help application's Contents list, usually the name of the application
• topic
  
  Single help content to be displyed 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 on long help pages to separate different subsections. Note that headings are not needed for all topics because the topic title is used as a topic's main heading. Headings are formatted with a different colour and are bigger and in bolder font.
• display_text
  
  Used for presenting text that appears on the device display, like button labels and so on. Display text is formatted with a different colour in the Help application.
• graphic
  
  Used to show in-line images in the text. You have to define either the absolute path (with the '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
• para_context
  
  A context paragraph (see also tip, note, important, example and warning)
• tip
  
  Shows a "Tip:" prefix (see para_context)
• note
  
  Shows a "Note:" prefix (see para_context)
• important
  
  Shows an "Important:" prefix (see para_context)
• example
  
  Shows an "Example:" prefix (see para_context)
• ref
  
  Used to create a cross-reference, the 'refid' parameter defines referred topic's contextUID and the 'refdoc' parameter is the name of the reference
• emphasis
  
  Used to emphasise 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 for change_history
• synonyms
  
  Synonyms are only used by Global search and are not displayed for the users. Synonyms are extra keywords for search.

You can download an example xml file here>.

Adding help context support to the application

This section demonstrates how to create an application with an online help system. This application uses the XML file described in the previous section.

To use the online help system on the maemo platform, you must include the following header files with your application:

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

The header file libosso.h provides the environment initialisation 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 to the user.

Now you must 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 the application, carry out these two steps:

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

In the following example shows you in detail how this initialisation must be carried out:

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;
}

The maemo help system is now fully functional. To show one of the topics from our help file, you only need to call the function ossohelp_show(), as in the example below.

In the event that the topic is not available, the ossohelp_show() function returns 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 to 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 to the dialog box. The process is simple: enable the button in the dialog box with the ossohelp_dialog_help_enable() function. 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 */
   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 you only need to compile the example:

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

Starting from the SDK 2.1 it is also possible to test the help system in the scratchbox. You can download the following help-framework example, help-framework desktop, and help-framework service files.

Distributing the example application

To quickly test your help content, manually copy the XML file to a correct path (for example, /usr/share/osso-help/en_GB/) where it can be found by the help library. 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 are now able to show your help content. The easiest way to distribute help file and application is to create an Application Manager package.