Christoph's Blog

Hover support in Xtext 2.0

with 9 comments

From the time I was starting with Xtext 2-3 years ago I recall a statement from Sven Efftinge saying “I want a JDT for all my languages”. Well, Xtext is great and it is coming closer and closer to the JDT level. The guys are really doing a fantastic job. But something I was missing was the support for hovers like the JDT offers for java-doc comments. So I started to work on this topic and had the chance to contribute my implementation back to Xtext. Some of you may have already noticed it in the latest milestones of Xtext 2.0. Let’s take a closer look at it.

Introduction

When editing a mwe2 file with Xtext 2.0 you can see the hovers in action. Just move your mouse over a reference to a mwe2 variable and a hover will show up.


I use mwe2 as an example language here. There is no special configuration in mwe2 to show these hovers. It should work  for any language out of the box. The hover displays the text of the leading multi line comment (java style). If you want to display different content or your language may have a different comment syntax, just replace the default implementation with your own and adopt the Guice configuration.

The hover will appear whenever you move your mouse on a cross-reference or on a declaration of an element. It is a 3-step procedure:

  1. Get the element on the mouse hover location: If it is a cross-reference get the referenced element. If it is a name of a declaration, get the declared element (element means an EObject). This is implemented in AbstractEObjectHover.
  2. Get the documentation for the element in step 1 (see interface IEObjectDocumentationProvider). The default implementation retrieves the documentation from the leading multi line comment (see MultiLineCommentDocumentationProvider). The returned documentation is of type String. Please note that the IEObjectDocumentationProvider interface is contained in Xtext’s non-ui plug-in. It may be useful without the user interface, e.g. generating documents from your model.
  3. Display the documentation of step 2 (see DispatchingEObjectTextHover and IEObjectHoverProvider and DefaultEObjectHoverProvider). The default hover implementation is implemented by a Browser widget. This means the documentation can contain any html formatting and it will be displayed correct (e.g. you can include images). The default implementation adds the type name and the element name in front of the actual documentation.

The hover will appear in content assist as well:

Support of multiple languages

Xtext supports references across different languages (or meta models). A file may can contain references to elements of other languages. What does this mean for hovers? Well, each language can have it’s own type of hover. Therefore an editor has to support different types of hovers. This is supported by utilizing the IGlobalServiceProvider (implemented by Sven). Each language/metamodel can register it’s own IEObjectHoverProvider via a shared module. Look at DispatchingEObjectTextHover for reference. This mechanism is used to display java-doc hovers for references to the JavaTypes meta model.

Java References

You can experience this mechanism in mwe2. Just move your mouse over a java reference. It looks like:

This is the original JDT hover, luckily no code duplication is required to make it available. Code completion works as well:

I expect this to work the same way for the upcoming Xtend2. I’m looking forward to it.

Quick fixes

I’ve also added a quick fix hover as known from JDT. It should work out of the box for any language which is providing quick fixes. Again, no additional configuration is required to make this work for your language.

Summary

That’s it. You get hovers for free with Xtext 2.0. You don’t have to work with the ITextHover interfaces, you can just provide your own IEObjectDocumentationProvider to change the hover content. It supports rich formatting via html. The Guice configuration still allows you to use your own ITextHover implementation where it is appropriate. The JDT javadoc hover is supported out of the box for java references.

Please feel free to add any comments. I would be happy to hear from you.

Finally I would like to thank the Xtext team for supporting me and applying my contribution. I enjoyed to work with you guys!

Advertisements

Written by Christoph Kulla

February 6, 2011 at 1:06 pm

Posted in Uncategorized

9 Responses

Subscribe to comments with RSS.

  1. Great work.

    Is there any way to apply these changes to XText 1.0 until the full version of 2.0 is available?

    Chris Ainsley

    February 17, 2011 at 2:10 am

    • Hi Chris,

      well, there is definitely a way, but you have to put some effort into it. You have to identify the changes from the Xtext git repo and merge them back into the 1.0 stream. There a few API changes and additions in 2.0 which the hovers rely on. Those places need some adoption. Just Let me know if you need more detailed information. What is the reason you want to stick with 1.0? Why not using the latest 2.0 milestone right away?

      Christoph Kulla

      February 17, 2011 at 10:33 am

  2. Is this in the current or next milestone?

    Chris Ainsley

    February 17, 2011 at 7:58 pm

    • It is in Xtext 2.0 M5, which I think is the current milestone.

      Christoph Kulla

      February 18, 2011 at 7:11 am

  3. Great work!
    I have dealt with “xtext hover” some time ago too but now I’m looking foward to upgrade to 2.0. Maybe I’ll write down a short post as a memento before scrapping it… 🙂

    Luong

    May 12, 2011 at 8:18 am

  4. […] efforts, I’ll scrap everything and switch to the new Xtext as soon as possible. Please, read Christoph’s post if you want to know […]

    Hovertext « M. L. B.

    May 18, 2011 at 9:50 pm

  5. Hi , Its greet!
    Thank you so much for this blog, really it helped so much since I started implementation with xtext.
    Today, I am working on Hover cards, i need some more detail information to be able to come over with my task. Can you address where can I find some more detail information or give some more details about your experience for new starters of xtext.

    Caner Kilinc

    July 12, 2011 at 1:38 pm

    • Hi,

      thanks four your comment. There is no other documentation then the source code itself. Just take look at the mentioned classes in Xtext sources.

      Christoph

      Christoph Kulla

      July 24, 2011 at 5:58 pm

  6. […] 2.0 comes with an all new Hover API (see Christoph’s Blog https://ckulla.wordpress.com/2011/02/06/hover-support-in-xtext-2-0/). I want to give a short introduction on how to use what with Xtext’s Greeting […]


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: