MPS 2019.1ヘルプ

説明コメント

We are going to learn how to leverage the capability of adding attributes to nodes. This feature is fully described in the 属性 section of the 構造 chapter. In this cookbook we'll create a simple addition to the 電卓 tutorial language that will allow the input and output fields of the calculator definitions to have descriptive comments attached to them. These descriptive comments will be propagated into the generated Java code in the form of "pop-up tooltips" attached to the Swing text fields corresponding to the input and output fields.

The Calculator language

We chose the Calculator tutorial(英語) language as a testbed for our experiments. You can find the calculator-tutorial project included in the set of sample projects that comes with the MPS distribution. I recommend you skimmed through the tutorial to familiarize yourself with the language before we continue.

Changes to the fields

Let's start building the machinery for adding descriptive comments to input and output fields. Our approach will be based on annotations that when added to nodes will have impact on their visual appearance as well as on the generated code. There are several vital components that will enable our desired functionality:

  • A marker interface that indicates, which nodes can hold the description comments

  • The annotation itself to indicate whether a node holds the description comment and what the description is

  • An action providing a keyboard shortcut to quickly add and remove the description comment to/from a node under caret

  • Updating the code generation process in order to generate the visual "tooltips" for the described components

We start with a new interface to mark all commentable nodes:

DC1

Now both InputField and OutputField concepts have to implement the new ICanHaveDescription interface.

DC3

The DescriptionAnnotation concept

We are still missing the core pice of our puzzle - the actual annotation that will be attributed to input and output fields to specify the description comment. Let's create it now:

DC4


Once you make the concept extend NodeAttribute , MPS will hint you to provide further information detailing the attribution. Invoking a quick-fix through Alt + Enter will add the necessary information for you to customize:

DC5


You need to specify additional qualities of the new annotation by setting values for role as well as attributed concepts. We set the role for the annotation as descriptionComment. This is the name to use in queries in order to find out, whether a node has been annotated with DescriptionAnnotation or not. We also indicate that the annotation can only be attributed to nodes implementing ICanHaveDescription , which in our case is InputField and OutputField .

DC6

The DescriptionAnnotation also has to store the actual text of the description - we'll use a string property descriptionText for this:

DC7

The editor of DescriptionAnnotation is the key element in defining the visual behavior of nodes with description comments attached to them. We prepend the annotated node with a "described" constant and append the actual description text wrapped in parentheses. The attributed node cell represents the editor of the actual node - the node that the attribute is attached to.

DC8

Further editor enhancements

To toggle the description comment of a node on and off, we will create new KeyMap .

DC20

To edit the code we will use concepts from BaseLanguage and smodel, which should be available by default. If not, import them through Control/Cmd + L. We will also need the actions language in order to create initialized nodes easily. This one will most likely need to be imported explicitly ( コントロール+ L ).

DC10

Now we can complete the action:


DC13

Whenever Control + Alt + Shift + D is pressed on a node implementing ICanHaveDescription , the action will add or remove the DescriptionAnnotation to/from the node.

The KeyMap now needs to be added to all fields that should react to Control + Alt + Shift + D . This is to InputField and OutputField in our case. The editor cells that should react to the Control + Alt + Shift + D key combination must have the key map specified in the keycap property.

DC12

How are we doing so far?

After compilation you are able to use Control + Alt + Shift + D both on input fields and output fields to toggle the description comment:

DC14


Updating the generator

The DescriptionAnnotation is currently lost during the generation process. Instead, we would like to generate the Swing "tooltips" for the text fields that represent the commented input and output fields.

DC21

When generating code we currently simply take all input or output fields in the calculator and generate JTextFields for them. In the constructor we also generate initialization code for each generated JTextField - this is the place, where we can attach a Swing "tooltip" the the JTextFields that represent an input or output fields with description comments.

DC15

The $IF$ node macro will ensure that a "tooltip" is only generated for nodes with the DescriptionComment annotation attached.

DC16

The property macro of the text of the "tooltip" will set the descriptionText of the DescriptionAnnotation attached to the current node:

DC17

After rebuilding the language and the sandbox solution, the generated Calculator form will have "tooltips" attached to the fields that have been marked with the DescriptionAnnotation :

DC21

要約

We can finish our tour here. Both input fields and output fields can be described with DescriptionAnnotation and the generated code contains a "tooltip" for each such description.

最終更新日: 2019年4月12日