Integrating your Xtext editor with eclipse help

You have implemented a Xtext editor for a cool language and have even documented both via eclipse help, but unfortunately pressing F1 does not yield the desired effect? Here are some (hopefully) helpful code snippets.

First of all, it is important that you provided context ids for your help.

For a simple scenario, the necessary modifications in the UI project are quite small.
1) add org.eclipse.help to the plugin dependencies
2) bind your own implementation of XtextEditor (code snippets from below go there)

If you want a “static” help for your editor, i.e. the result of pressing F1 does not depend on the cursor position within the editor, overriding the createPartControl method is enough:

  @Override
  public void createPartControl(Composite parent) {
    //important to set context id before super call
    setHelpContextId(ITextEditorHelpContextIds.TEMPLATES_VIEW);
    super.createPartControl(parent);
  }

If you want more dynamic behaviour, e.g. the help should depend on the cursor position, explaining a language concept used there, one way to go is the IContextProvider… The following is a somewhat minimal example. Just as above, it uses existing help ids, so that you can play around without actually needing your own help. Normally, you would inspect the model element present at the given offset (available via text.getSelection().x):

  @Override
  public Object getAdapter(Class adapter) {
    if(adapter.equals(IContextProvider.class)){
      //this is just an example!
      //you should not instantiate a new provider every time
      return new IContextProvider() {
        @Override
        public String getSearchExpression(Object target) {
          //adapt the search expression according to the current position
          return "grammar mixin";
        }
        @Override
        public int getContextChangeMask() {
          //provide a new context whenever the selection changes
          return IContextProvider.SELECTION;
        }
        @Override
        public IContext getContext(Object target) {
          //retrieve one (or more for combining them) context
          //from the help system and return the result
          StyledText text = (StyledText)target;
          if(text.getSelection().x>20){
            return HelpSystem.getContext(
              ITextEditorHelpContextIds.TEXT_EDITOR_PREFERENCE_PAGE);
          }else{
            return HelpSystem.getContext(
              ITextEditorHelpContextIds.TEMPLATES_VIEW);
          }
        }
      };
    }
    return super.getAdapter(adapter);
  }

Some additional remarks:

PlatformUI.getWorkbench().getHelpSystem().setHelp(control, contextId) is nice for setting the help for a particular control. We used it for redirecting to our help in the DSL’s preference pages (bind extension of e.g. SyntaxColoringPreferencePage, there override setControl with super call + setHelp for the given control).

Assume that for a certain position in the editor several of your help contexts are relevant. In that case you could create a new “artificial” IContext with the accumulated related topics.

There are extensions of IContext that allow changing the title, categories etc.

Leave a Reply