Friday, April 03, 2009

Hover Help (HH) Plug-in for Carbide c++ v2.0

Those of you, who use Eclipse IDE for development, know how much Eclipse IDE makes coding easier for developers. Among many other functionality, Eclipse IDE provides refactoring, skeleton project creation, automatic building, easy launching, template source generation, code completion and various and quickest way to access help contents. For example, by hovering mouse over an API or pressing F2 key on a keyword, javadoc of the keyword/API can be displayed in a pop-up browser in java source editors. In my last work, as an eclipse plug-in developer at Symbian/Nokia, London, I participated in a project to develop a plug-in for similar help functionality for Carbide c++.

There are many open source products and IDE based on Eclipse framework.
Carbide c++ from Nokia is one of them. “Carbide.c++ is a family of IDEs for the creation of C++ and C applications for Symbian OS devices. Carbide.c++ is based on the Eclipse IDE and the C/C++ development tools from the Eclipse CDT Project.”

Upon several open source mobile framework such as Google's Andriod and Apple's iPhone, last year Nokia decided to go open source too and acquired Symbian in Dec, 2008 and set up Symbian Foundation. By the end of this month (April, 2009), Symbian Foundation will kick off. One of the biggest task at Symbian nowadays is to prepare Symbian SDK to open source community. A good and easy accessible documentation is one of these tasks. My role in Symbian as eclipse plug-in developer was to prepare a Carbide c++ plug-in (Hover Help plug-in) to provide Symbian OS API documentation seamlessly in a c++ editor, similar to Javadoc display functionality in eclipse with F2 key or hovering by mouse.

Below you can find an overview of Hover Help plug-in. It is extracted from help of the HH plug-in. In this text, i wont go in technical details. But if you need more technical information (such as CDT, API binding, plug-ins, hover extension points, direct access to jar content without extracting), please contact me via email.

Hover Help (HH)


The Hover Help Plug-in is an Eclipse plug-in that provides a link between the Carbide IDE and the C++ Developer Library. When installed, it provides developers with easy access to the API reference documentation. When a user hovers over a C++ API, the editor shows the documentation for this API reference.




The Hover Help Plug-in uses the The Developer Library Plug-in. This is an Eclipse documentation plug-in that contains the information displayed when an API reference item is hovered over.
You can download the Developer Library Plug-in from the
Symbian Foundation website.

Prerequisites for installation


The following software package is required for the Developer Library Hover Help Plug-in to work:

  • Carbide 2.0 Note: The Hover Plug-in does not work with Carbide 1.3.
  • Hover Help Plug-in Dependencies: com.nokia.carbide.cpp.sysdoc.hover.dependencies
  • Hover Help Plug-in version 1.0 or higher: com.nokia.carbide.cpp.sysdoc.hover

You must also you have installed the other programs that are required to do Symbian OS C++ development in Carbide, such as Active Perl and an SDK. Refer to the readme documentation of Carbide for further information.

Installing the Hover Help Plug-in

You can install the Hover Help Plug-in in the same way as other Eclipse plug-ins:

  1. Place the Hover Help Plug-in and its dependency plug-in into Carbide’s plugins directory.
  2. Restart Carbide.

Set Up

This section describes the initial set up of the Hover Help Plug-in and how you can add the Developer Library plug-in.

After installation

After installation of all the components, the Hover Help Plug-in prepares itself for its first use by reading of the interchange file (hover_help.xml).

This process will take a few seconds and progress is displayed in Progress view.

You can cancel the indexing process, the hover help plug-in will be deactivated. You can re-activate the hover help plug-in using

the preference panel, the indexing will start again.

Adding a new Developer Library Plug-in

New versions of the Developer Library Plug-in are published regularly. You can configure the Hover Help Plug-in to use a new version as follows:

  1. Obtain the latest Developer Library Plug-in from the Symbian Foundation website, and copy the new plug-in into Carbide’s plugins directory.
  2. Restart Carbide.
  3. From Developer Library Hover Help Preference panel, make sure new added Developer library is selected. If not select it from plug-in drop-down box.

Activating the Hover Help Plug-in

If the Hover Help Plug-in has been de-activated, you can activate it by following the steps:

  1. Go to the Developer Library Hover Help Preferences and un-check the check box deactivate the plug-in. When you reactivate the Hover Help Plug-in, the plug-in will initialise to "Automatically select latest Developer Library". See automatically select the latest Developer Library for more information
  2. Select the plug-in from the Developer Libraries Help Files plug-in drop-down box.

Hover Help Preferences

This section describes the preferences panel that you can use to configure and change the Developer Library Plug-ins used by the Hover Help Plug-in.


With the preference panel I can:

  • Let the Hover Help plug-in automatically choose for me the right Developer Library Plug-in.
  • Select a Developer Library plug-in using the drop-down box.
  • Deactivate the Hover Help plug-in.
  • Restore the plug-in configuration to default.
  • Apply, confirm or cancel the changes.

Automatically select the Developer Library plug-in

When you check the check box "Automatically select the latest Developer Library" the Developer Library is automatically selected for you. The name of the selected library is displayed in the greyed field.

If you want to select a particular Developer Library Plug-in, you can uncheck the checkbox "Automatically select latest Developer Library".

The right Developer library is chosen using the following heuristic. To be noted that the items are ordered by importance.

  • Audience and license of the Developer Library. The choice is between platform and public development. For example: "DL for platform" will be chosen rather then "DL for public"
  • Publication date of the Developer Library For example: "DL published 15/02/2009" will be chosen rather then "DL published 01/01/2009"

Select a Developer Library

The selected Developer Library is shown in the drop-down box.
To be able to change the Developer Library, the
"Automatically select latest Developer Library" checkbox should not be checked. To change the active Developer Library, select the Developer Library Help Plug-ins drop-down box.

Deactivate Hovering check box

The Deactivate Hovering check box enables or disables the hovering feature in the Eclipse IDE.
When you reactivate the Hover Help plug-in, the plug-in is set to
"Automatically select latest Developer Library".

Apply, confirm, cancel

These buttons have the common Carbide behaviour.

Defaults

If “Restore Default” button is clicked, the plug-in will automatic reset to "Automatically select latest Developer Library".

3 comments:

Fabrício S. Epaminondas said...

Hi, can you send a link where I can download the SDL that contains the interchange file? I have downloaded S60_5th_Edition_Cpp_Developers_Library_2.0.4.jar from nokia forum, but the hover help does not work, I checked inside this file and I could not found any hover_help.xml. On Symbian foundation site I could not found any reference to download this plugin with the interchange file. Thanks =]

Roman said...

That is a grate feature to getting instant help. Is there any way to download this plugin? I couldn't find it in even in google.

Deniz Turan, PhD said...

I am not with Nokia team anymore. But i got following from a Nokia insider:

"Concerning the HH (http://carbidehelp.nokia.com/help/index.jsp?topic=/com.nokia.carbide.cpp.doc.user/html/release_notes.htm), the HH content has not yet published.

We published HTML content but not the JAR one, where the HH plug-in is.

If you log in the SF web site developers.symbian.org, you will be able to download the Application Tools Kit which contain Carbide 2.0.4, the one that contains the HH logic.

We will make a contribution soon for the HH content plug-in."