For my Code generation plug-in I wanted to add some context sensitive help. Looking for any hints I only found a quick description at Macrobug’s that dates back in autumn 2007 when Eclipse 3.3 (Europa) was the current platform. Following these steps I could not produce any meaningful results. Therefore I figured it out on my own and present my solution here for anyone interested.
To reduce the the problem to its most simplest I created a new plug-in to test this out: New->Other->Plug-in-Project. Fill in the required values with some sensible data. On the third page select the „Plug-in with multi-page editor“. Then you can hit finish since all we need is a wizard with one page where we can call the context sensitive help.
In the project create a new folder and name it „html“. Create some html files in this folder (ie. help1.htm,help2.htm,…) that contain the contents of your context help. Then create an XML file under your project root (ie. contextHelp.xml) and add the contexts to it:
Note the id „firsthelp“. The href points to your corresponding html file with a relative path. You can add several topic elements. Now you have to make your context sensitive known in the plug-in through the extension point org.eclipse.help.contexts. To do that add the following lines to the plugin.xml:
The file has the path to your XML file you just defined. Note that the plugin attribute denotes this plug-in. It can define some other plug-in if your XML context help file is located in another bundle/plug-in.
What we have done until now is generating some artefacts that are not needed – yet. So we have to tie up all the loose ends. In effect this is done with essentially one line of code. But to understand how all this works let’s take a closer look on how the context sensitive help works.
The context is defined by a unique ID the context-ID. In your wizard this context-ID is set as a data attribute on the widget of the shell. To understand why this is important lets take a look at the suggested solution by Macrobugs:
PlatformUI.getWorkbench().getHelpSystem.displayHelp(context-ID);
What happens here is that the help context is created with your supplied context-ID and afterwards a second time with the context-ID defined in the shell that overrides your context. Your call stems from the direct call in the method performHelp, the second is executed based on the registered event listener. For all more interested in the details are referred to the inner class WorkbenchHelpListener in org.eclipse.ui.internal.help.WorkbenchHelp and there have a look at the method helpRequested(Event).
With that said all we have to is supply the widget with our context-ID. For that we override the method performHelp in our WizardPage class:
/** * Set the right help key for the context sensitive help */ public void performHelp() { // (WorkbenchHelpSystem.HELP_KEY = "org.eclipse.ui.help" getShell().setData(WorkbenchHelpSystem.HELP_KEY, "ch.sahits.tutorial.help.firsthelp"); }
The HELP_KEY is a constant in an internal class. This will generate you a warning for discouraged access, alternatively you can use the value of the constant: „org.eclipse.ui.help“. The important part is the second argument of the setData method, the value. This is your context-ID. This context-ID is put together from the plug-in ID of your plug-in where you defined your extension (in our case the very same plug-in) and the id of the context divided by a point.
An example plug-in that followed basically the same steps described here can be obtained.
I often find such examples not very instructive when being confronted with a real world problem. This one though works perfectly. I put the help into its own plug-in and passed the plug-in ID as described.
If you follow the steps as described (help pages, XML-file, plugin.xml, performHelp) you are on a sure way since everything you use, you have defined in a previous step.
The description at Macrobugs works under the assumption that the wizard is not called through file->new->…
If the wizard is called like this the problem described in this article arises. If you call your wizard through a button on your task bar or even through a button on your wizard which you started through file->new the above fails.
To make sure your wizard works in both scenarios add the following line to your
performHelp()
Method:PlatformUI.getWorkbench().getHelpSystem().displayHelp("ch.sahits.tutorial.help.firsthelp");
Or instead of „ch.sahits.tutorial.help.firsthelp“ whatever your context-ID is.
Hi andi,
I used your above method to implement context sensitive help,it worked,thanks.
But I have a small issue,when I click on help(?) or button,in my custom window which i have designed,that help window takes some space of my custom window.It is fine for me if it appears on left and doesn’t eat my custom window’s space.
I can share the printscreen with you if needed.Please provide me your personal ID, you can mail me at sujamait@gmail.com
It would be nice if you could reply soon,its kinda urgent 🙁
thanks!!
Regards,
Sumit
As I understand your problem it is the sizing and location of context help pane that is shown. This seems to be something that is defined in the underlying help framework. I did not investigate in that direction but suggest, that you run your application in debug mode and follow the
getShell().setData(...)
Somewhere the pane will be set up with sizes and location and made visible.