Tutorials
Page tree

Versions Compared

Old Version 8

changes.mady.by.user Unknown User (uru)

Saved on

compared with

New Version Current

changes.mady.by.user Unknown User (uru)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Welcome to this tutorial! We will work our way through installing a proper Eclipse setup and developing a first very basic layout algorithm. The layout algorithm will integrate with KIML (KIELER Infrastructure for Meta-Layout ELK (Eclipse Layout Kernel), our very own framework that connects graphical editors with layout algorithms. Once you're finished, you should be able to write layout algorithms for KIMLELK. And you should have a running Eclipse-based application that should look something like this:

...

Now that the preliminaries are out of the way, it's time to develop your first layout algorithm! It will, however, be a very simple one. This tutorial focuses on creating Eclipse plug-ins and on learning how to develop with KIMLELK.

Adding a New Plug-in

We need to create a new plug-in to implement the layout algorithm in. Switch back to the Java or Plug-in Development perspective and follow these steps:

  1. Click File > New > Other... > Plug-in Development > Plug-in Project.
  2. Enter de.cau.cs.kieler.simplelayout as the project name. Click Next.
  3. Set the execution environment to J2SEJavaSE-1.58. (do this for all plug-ins that you create!)
  4. Uncheck all checkboxes in the Options group and click Finish.
  5. If Eclipse asks you whether the Plug-in Development perspective should be opened, choose either Yes or No. It doesn't make much of a difference anyway.

...

  1. In your new plug-in, open the file META-INF/MANIFEST.MF. The plug-in manifest editor will open. Open its Dependencies tab.
  2. Add dependencies to the following plug-ins:
    • deorg.caueclipse.cselk.kieler.core
    • deorg.caueclipse.cs.kieler.core.kgraphde.cau.cs.kieler.kimlelk.graph
  3. Save the editor.

Layout algorithms interface with KIML ELK by means of a layout provider class that has to be created and registered with KIML.

  1. Right-click the source folder of your plug-in and click New > Class.
  2. Set the package to de.cau.cs.kieler.simplelayout, enter SimpleLayoutProvider as the class name, and select deorg.caueclipse.cselk.kieler.kimlcore.AbstractLayoutProvider as the superclass. (This will only be available through the Browse dialog if you have saved the plug-in manifest editor; if you haven't, Eclipse won't know about the new dependencies yet.)
  3. Select Generate comments and click Finish.

...

  1. Add the following constants:

    Code Block
    languagejava
    /** default value for spacing between nodes. */
private static final float DEFAULT_SPACING = 15.0f;

  2. Use the following code as the skeleton of the doLayoutthe layout(...) method:

    Code Block
    languagejava
    progressMonitor.begin("Simple layouter", 1);
KShapeLayout parentLayout = parentNodelayoutGraph.getData(KShapeLayout.class);

float objectSpacing = parentLayout.getProperty(LayoutOptionsCoreOptions.SPACING_NODE);
if (objectSpacing < 0) {
    objectSpacing = DEFAULT_SPACING;
}

float borderSpacing = parentLayout.getProperty(LayoutOptionsCoreOptions.SPACING_BORDER_SPACING);
if (borderSpacing < 0) {
    borderSpacing = DEFAULT_SPACING;
}

// TODO: Insert actual layout code.

progressMonitor.done();
  3. Press CTRL+SHIFT+O or select Source > Organize Imports from the context menu to add all required imports.
  4. It is now time to write the code that places the nodes.Your code should place them next to each other in a row, as seen in the screenshot at the beginning of the tutorial.

...

Before you can test your layout code, you will have to register your new layout provider with KIML.ELK.

  1. Right-click the de.cau.cs.kieler.simplelayout package and select New > File.
  2. Create a file simple.elkm and double click it to open it.
  3. When asked whether you want to add the Xtext nature, select yes.

  4. The file is used to specify meta information for your layout algorithm. For this, copy the following code snippet into your editor:

    Code Block
    languagejava
    package de.cau.cs.kieler.simplelayout

bundle {
    label "Simple Layout Algoritms"
    metadataClass SimpleMetaDataProvider
}

algorithm simple(SimpleLayoutProvider) {
    label "Simple Test Layouter"
    metadataClass SimpleOptions

    supports org.eclipse.elk.spacing.border
    supports org.eclipse.elk.spacing.node
}
  5. You still have to register the file with Eclipse. Open the META-INF/MANIFEST.MF file again and switch to the Extensions tab.
  6. Add an extension for defor org.caueclipse.cs.kieler.kiml.layoutelk.core.layoutProviders.
  7. Right-click the extension and click New > layoutAlgorithm provider.
  8. Set the name to Simple Test Layouter and the class to your layout bundle's meta data provider class name (use the browse button and enter SimpleLayoutProvider SimpleMetaDataProvider).
  9. Right-click the new layoutAlgorithm and click New > knownOption. Set option to de.cau.cs.kieler.spacing.
  10. Add another knownOption for de.cau.cs.kieler.borderSpacing.
  11. Note that SimpleMetaDataProvider is automatically generated from the .elkm file you created. Its name is specified by the metadataClass keyword in the bundle section. What is also created is the SimpleOptions class, which contains everything you need to access layout options from within your layout algorithm.
  12. Save the editor
  13. Your workspace should look similar to this
    Image Removed

...

  1. Image Added

We will now have to add a new run configuration that will start an Eclipse instance with your layout code loaded into the application, ready to be used.

  1. Click Run > Debug Configurations...
  2. Right-click Eclipse Application and click New. Set the configuration's name to Layout Test.
  3. In the Arguments tab, make sure the the program arguments include -debug and -consoleLog.
  4. On the Plug-ins tab, set Launch with to plug-ins selected below only.
    1. Click Deselect All.
    2. Check the Workspace item in the tree.
    3. Check the following plugins under Target Platform are checked:
      • de.cau.cs.kieler
      .core
      • .kgraph.text.ui
      ,
      • de.cau.cs.kieler.klighd.xtext
      and
      • org.eclipse.ui.ide.application
      plugins under Target Platform
      • org.eclipse.platform
    4. Click Add Required Plug-ins. Press it twice (just to be sure!).
  5. Click Apply to save your changes and then Debug to start an Eclipse instance to test with.

Test the layouter in your new Eclipse instance:

...

  1. Click New > Project... > General > Project and set the project name to something like Test.
  2. Right-click the new project and click New > Other > KGraph > Random KGraph. Enter a meaningful name and click Finish.
  3. Open the diagram. Another view with graphical representations of the nodes should pop up..kgt file. To show up the Diagram vie, select Window > Show View > Other... > Other > Diagram
  4. Open the Layout view through Window > Show View > Other... > KIELER Eclipse Diagram Layout > Layout. Move the view somewhere such that you can see the view and the diagram simultaneously. 
  5. Chose your Simple Test Layouter in the Layout Algorithm section of the Layout View. (If the Layout View shows no properties, click the white background in the Diagram View once.)
  6. You should see something similar to this

...

Once you're done implementing the edge routing code, test it by running your debug configuration again, as before.