Merge "Bug 385193: JavaDoc completed, online docu added, filesystem example added to docu"
diff --git a/examples/org.eclipse.graphiti.doc/resources/docu/advanced/Patterns.htm b/examples/org.eclipse.graphiti.doc/resources/docu/advanced/Patterns.htm
index ba80018..b9dfcb9 100644
--- a/examples/org.eclipse.graphiti.doc/resources/docu/advanced/Patterns.htm
+++ b/examples/org.eclipse.graphiti.doc/resources/docu/advanced/Patterns.htm
@@ -328,5 +328,28 @@
what you would also need to implement for the features of a
connection.
</p>
+ <div id="idpatterns"></div>
+ <h2>ID Patterns</h2>
+ <p>
+ ID patterns are a special kind of pattern that allow clients to easily
+ tag parts of their shapes (both <i>PictogramElements</i> and <i>GraphicsAlgorithms</i>)
+ with IDs. These IDs are simple strings that can in other methods of
+ the pattern be used to identify the shape. The ID pattern base class
+ itself already does that to a wide extend; on e.g. layout or update
+ the pattern checks if the affected shape has an ID and if yes
+ delegates to a special ID Pattern method that can use the passed ID
+ information and simply do the intended job without having to care
+ about finding the shape or checking the relevance of the shape first.
+ This makes client coding much shorter and effective and spares clients
+ the tedious writing of such boilerplate code.
+ </p>
+ <p>The are two examples for ID Patterns within the Graphiti
+ Filesystem example: <i>File</i> objects are a basic example of the ID pattern
+ usage, while <i>Folder</i>s are a more advanced example that also shows
+ nesting a list of children (files in the example).</p>
+ <p class="Note"><b>Note:</b> The ID Pattern type is still experimental, the API
+ might still evolve and/or change without prior notice! Nevertheless,
+ we try to keep the API stable and encourage you to use this new
+ pattern type and give feedback.</p>
</body>
</html>
diff --git a/examples/org.eclipse.graphiti.doc/resources/docu/examples/Filesystem.htm b/examples/org.eclipse.graphiti.doc/resources/docu/examples/Filesystem.htm
new file mode 100644
index 0000000..37fe84e
--- /dev/null
+++ b/examples/org.eclipse.graphiti.doc/resources/docu/examples/Filesystem.htm
@@ -0,0 +1,50 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+
+<head>
+<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
+<title>Filesystem Example</title>
+<link href="../book.css" rel="Stylesheet" type="text/css">
+<link href="../code.css" rel="Stylesheet" type="text/css">
+</head>
+
+<body>
+
+ <h1>Filesystem Example</h1>
+ <p>
+ The filesystem example provided along with the SDK download of
+ Graphiti illustrates how one can use patterns for building Graphiti
+ editors. It registers an editor for this that allows the user to
+ create a filesystem with files and folders. Most of the functionality
+ is build using <a href="../advanced/Patterns.htm">patterns</a> and <a
+ href="../advanced/Patterns.htm#idpatterns">ID patterns</a>.
+ </p>
+ <img alt="Screensshot of Filesystem Example Editor"
+ src="images/FilesystemEditor.png" width="600px">
+ <h2>Filesystem Example Plugin</h2>
+ <p>
+ The example plugin <i>org.eclipse.graphiti.examples.filesystem</i> is
+ available as executable but also as source in the SDK download and
+ within our repository under the examples folder. While the example is
+ easy enough for quickly understanding it, it allows to demonstrate
+ some features of Graphiti that are not explained in the tutorial.
+ </p>
+ <h2>EMF Model</h2>
+ <p>
+ The examples plugin <i>org.eclipse.graphiti.examples.filesystem.mm</i>
+ contains a small EMF model to define the filesystem model.
+ </p>
+ <img alt="The EMF model defined for the Filesystem Example"
+ src="images/FilesystemModel.png" width="600px">
+ <h2>Special Graphiti Features</h2>
+ <p>The following special Graphiti features are shown in the
+ Filesystem example:</p>
+ <ul>
+ <li>The filesystem object itself is implemented using Graphiti
+ patterns.</li>
+ <li>The file object is a simple example of a Graphiti ID pattern.</li>
+ <li>The folder object is a more advanced example for a Graphiti
+ ID pattern using nesting of a list of objects.</li>
+ </ul>
+</body>
+</html>
diff --git a/examples/org.eclipse.graphiti.doc/resources/docu/examples/Tutorial.htm b/examples/org.eclipse.graphiti.doc/resources/docu/examples/Tutorial.htm
new file mode 100644
index 0000000..534320d
--- /dev/null
+++ b/examples/org.eclipse.graphiti.doc/resources/docu/examples/Tutorial.htm
@@ -0,0 +1,27 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+
+<head>
+<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
+<title>Tutorial</title>
+<link href="../book.css" rel="Stylesheet" type="text/css">
+<link href="../code.css" rel="Stylesheet" type="text/css">
+</head>
+
+<body>
+
+ <h1>Tutorial</h1>
+ <p>The tutorial example provided along with the SDK download of
+ Graphiti contains the final version of the Graphiti editor that is
+ created in the Graphiti tutorial.</p>
+ <h2>Tutorial Plugin</h2>
+ <p>
+ The example plugin <i>org.eclipse.graphiti.examples.tutorial</i> is
+ available as executable but also as source in the SDK download and
+ within our repository under the examples folder.
+ </p>
+ <h2>EMF Model</h2>
+ <p>The tutorial uses the ECore model itself as domain model.
+ Therefore there is no special model defined here.</p>
+</body>
+</html>
diff --git a/examples/org.eclipse.graphiti.doc/resources/docu/examples/images/FilesystemEditor.png b/examples/org.eclipse.graphiti.doc/resources/docu/examples/images/FilesystemEditor.png
new file mode 100644
index 0000000..3ef749d
--- /dev/null
+++ b/examples/org.eclipse.graphiti.doc/resources/docu/examples/images/FilesystemEditor.png
Binary files differ
diff --git a/examples/org.eclipse.graphiti.doc/resources/docu/examples/images/FilesystemModel.png b/examples/org.eclipse.graphiti.doc/resources/docu/examples/images/FilesystemModel.png
new file mode 100644
index 0000000..bcc3930
--- /dev/null
+++ b/examples/org.eclipse.graphiti.doc/resources/docu/examples/images/FilesystemModel.png
Binary files differ
diff --git a/examples/org.eclipse.graphiti.doc/toc.xml b/examples/org.eclipse.graphiti.doc/toc.xml
index 9f214ed..498e24e 100644
--- a/examples/org.eclipse.graphiti.doc/toc.xml
+++ b/examples/org.eclipse.graphiti.doc/toc.xml
Binary files differ
diff --git a/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/AbstractPattern.java b/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/AbstractPattern.java
index 8afe75d..aad5d41 100644
--- a/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/AbstractPattern.java
+++ b/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/AbstractPattern.java
@@ -881,10 +881,10 @@
* .
*
* @param value
- * The new vlue to check
+ * The new value to check
* @param context
* A context object describing the direct edit request.
- * @return <code>null</code> in case of a vlid value, a string describing
+ * @return <code>null</code> in case of a valid value, a string describing
* the reason for being not valid otherwise.
*/
public String checkValueValid(String value, IDirectEditingContext context) {
@@ -999,7 +999,7 @@
/**
* Provides the initial value for display in the newly opened text editing
- * UI component. Corresponds to the methdo
+ * UI component. Corresponds to the method
* {@link AbstractDirectEditingFeature#getInitialValue(IDirectEditingContext)}
* . The default implementation always returns an empty string.
*
diff --git a/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/id/IdLayoutContext.java b/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/id/IdLayoutContext.java
index 5cb593b..6aba3b8 100644
--- a/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/id/IdLayoutContext.java
+++ b/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/id/IdLayoutContext.java
@@ -20,6 +20,13 @@
import org.eclipse.graphiti.mm.pictograms.PictogramElement;
/**
+ * This class represents a special {@link LayoutContext} suitable for usage
+ * within an {@link IdPattern}. Besides the usual {@link LayoutContext} options
+ * this context object also stores the associated {@link GraphicsAlgorithm} for
+ * the {@link PictogramElement} of the context and the root
+ * {@link PictogramElement} of the pattern. The latter may be of use for easier
+ * finding a certain child within a pattern representation.
+ *
* @since 0.10
* @experimental This API is in an experimental state and should be used by
* clients only with care, as it not final and can be removed or
@@ -30,6 +37,20 @@
private GraphicsAlgorithm graphicsAlgorithm;
private PictogramElement rootPictogramElement;
+ /**
+ * Creates a new {@link IdLayoutContext} instance holding the given
+ * pictogram model instances.
+ *
+ * @param pictogramElement
+ * The {@link PictogramElement} that shall be layouted, see
+ * {@link LayoutContext}.
+ * @param graphicsAlgorithm
+ * The associated {@link GraphicsAlgorithm} for the
+ * {@link PictogramElement}
+ * @param rootPictogramElement
+ * The root pictogram element, this is the one that holds the ID
+ * property for the pattern
+ */
public IdLayoutContext(PictogramElement pictogramElement, GraphicsAlgorithm graphicsAlgorithm,
PictogramElement rootPictogramElement) {
super(pictogramElement);
@@ -37,18 +58,42 @@
this.rootPictogramElement = rootPictogramElement;
}
+ /**
+ * Returns the stored {@link GraphicsAlgorithm}.
+ *
+ * @return The instance of the {@link GraphicsAlgorithm} for the
+ * {@link PictogramElement} to layout.
+ */
public GraphicsAlgorithm getGraphicsAlgorithm() {
return graphicsAlgorithm;
}
+ /**
+ * Sets a new {@link GraphicsAlgorithm} for the {@link PictogramElement} to
+ * layout.
+ *
+ * @param graphicsAlgorithm
+ * The new instance to set.
+ */
public void setGraphicsAlgorithm(GraphicsAlgorithm graphicsAlgorithm) {
this.graphicsAlgorithm = graphicsAlgorithm;
}
+ /**
+ * Returns the stored root {@link PictogramElement}.
+ *
+ * @return The instance of the root {@link PictogramElement}.
+ */
public PictogramElement getRootPictogramElement() {
return rootPictogramElement;
}
+ /**
+ * Sets a new root {@link PictogramElement}.
+ *
+ * @param rootPictogramElement
+ * The new instance to set.
+ */
public void setRootPictogramElement(PictogramElement rootPictogramElement) {
this.rootPictogramElement = rootPictogramElement;
}
diff --git a/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/id/IdPattern.java b/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/id/IdPattern.java
index 456225b..ee6692d 100644
--- a/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/id/IdPattern.java
+++ b/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/id/IdPattern.java
@@ -23,7 +23,9 @@
import org.eclipse.graphiti.features.context.IUpdateContext;
import org.eclipse.graphiti.features.context.impl.LayoutContext;
import org.eclipse.graphiti.features.context.impl.UpdateContext;
+import org.eclipse.graphiti.features.impl.AbstractDirectEditingFeature;
import org.eclipse.graphiti.features.impl.Reason;
+import org.eclipse.graphiti.func.IDirectEditing;
import org.eclipse.graphiti.mm.Property;
import org.eclipse.graphiti.mm.PropertyContainer;
import org.eclipse.graphiti.mm.algorithms.GraphicsAlgorithm;
@@ -841,13 +843,39 @@
* Direct editing functionality
*/
+ /**
+ * The Graphiti framework calls this method to decide which UI to show up
+ * for direct editing. Corresponds to the method
+ * {@link AbstractDirectEditingFeature#getEditingType()}. The default
+ * implementation return {@link IDirectEditing#TYPE_NONE}, other valid type
+ * are defined by the TYPE_* constants in {@link IDirectEditing}.
+ *
+ * @return The desired editing type
+ */
@Override
public int getEditingType() {
// TODO how to use different editing types for different parts of the
// pattern? No context to identify id...
- return TYPE_TEXT;
+ return super.getEditingType();
}
+ /**
+ * Clients can override this method to indicate that the pattern allows
+ * direct editing for the shape described in the passed
+ * {@link IDirectEditingContext}, but the recommended method to override for
+ * {@link IdPattern} is
+ * {@link #canDirectEdit(IDirectEditingContext, String)}. Corresponds to the
+ * method
+ * {@link AbstractDirectEditingFeature#canDirectEdit(IDirectEditingContext)}
+ * . The default implementation checks if the pattern is responsible for the
+ * shape and an ID is set; in that case it delegates to
+ * {@link #canDirectEdit(IDirectEditingContext, String)}.
+ *
+ * @param context
+ * A context object describing the direct edit request.
+ * @return <code>true</code> in case direct editing shall be allowed,
+ * <code>false</code> otherwise.
+ */
@Override
public boolean canDirectEdit(IDirectEditingContext context) {
PictogramElement pictogramElement = context.getPictogramElement();
@@ -868,10 +896,37 @@
return false;
}
+ /**
+ * Clients can override this method to indicate that the pattern allows
+ * direct editing for the shape described in the passed
+ * {@link IDirectEditingContext} holding the given ID. Corresponds to the
+ * method
+ * {@link AbstractDirectEditingFeature#canDirectEdit(IDirectEditingContext)}
+ * . The default implementation simply returns <code>false</code>.
+ *
+ * @param context
+ * A context object describing the direct edit request.
+ * @param id
+ * The ID to check direct editing for
+ * @return <code>true</code> in case direct editing shall be allowed,
+ * <code>false</code> otherwise.
+ */
protected boolean canDirectEdit(IDirectEditingContext context, String id) {
return false;
}
+ /**
+ * Provides the initial value for display in the newly opened text editing
+ * UI component. Corresponds to the method
+ * {@link AbstractDirectEditingFeature#getInitialValue(IDirectEditingContext)}
+ * . The default implementation checks if the pattern is responsible for the
+ * shape and an ID is set; in that case it delegates to
+ * {@link #getInitialValue(IDirectEditingContext, String)}.
+ *
+ * @param context
+ * A context object describing the direct edit request.
+ * @return The initial string value to be displayed for editing by the user.
+ */
@Override
public String getInitialValue(IDirectEditingContext context) {
PictogramElement pictogramElement = context.getPictogramElement();
@@ -889,13 +944,44 @@
}
}
}
- return null;
+ return "";
}
+ /**
+ * Provides the initial value for display in the newly opened text editing
+ * UI component. Corresponds to the method
+ * {@link AbstractDirectEditingFeature#getInitialValue(IDirectEditingContext)}
+ * . The default implementation always returns an empty string.
+ *
+ * @param context
+ * A context object describing the direct edit request.
+ * @param id
+ * The ID of the shape to get the initial value for
+ * @return The initial string value to be displayed for editing by the user.
+ */
protected String getInitialValue(IDirectEditingContext context, String id) {
- return null;
+ return "";
}
+ /**
+ * This method will be called by the framework to check if the passed String
+ * is valid as new value for the shape. This method's response time should
+ * be small since the method is queried after each change of the value in
+ * the direct edit UI. In case of a not valid value, the returned string
+ * shall indicate the reason why the value is not valid. Corresponds to the
+ * method
+ * {@link AbstractDirectEditingFeature#checkValueValid(String, IDirectEditingContext)}
+ * . The default implementation checks if the pattern is responsible for the
+ * shape and an ID is set; in that case it delegates to
+ * {@link #checkValueValid(String, IDirectEditingContext, String)}.
+ *
+ * @param value
+ * The new value to check
+ * @param context
+ * A context object describing the direct edit request.
+ * @return <code>null</code> in case of a valid value, a string describing
+ * the reason for being not valid otherwise.
+ */
@Override
public String checkValueValid(String value, IDirectEditingContext context) {
PictogramElement pictogramElement = context.getPictogramElement();
@@ -916,10 +1002,43 @@
return null;
}
+ /**
+ * This method will be called by the framework to check if the passed String
+ * is valid as new value for the shape. This method's response time should
+ * be small since the method is queried after each change of the value in
+ * the direct edit UI. The default implementation simply returns null to
+ * indicate that all values are valid. In case of a not valid value, the
+ * returned string shall indicate the reason why the value is not valid.
+ * Corresponds to the method
+ * {@link AbstractDirectEditingFeature#checkValueValid(String, IDirectEditingContext)}
+ * .
+ *
+ * @param value
+ * The new value to check
+ * @param context
+ * A context object describing the direct edit request.
+ * @param id
+ * The ID of the shape to check the value for
+ * @return <code>null</code> in case of a valid value, a string describing
+ * the reason for being not valid otherwise.
+ */
protected String checkValueValid(String value, IDirectEditingContext context, String id) {
return null;
}
+ /**
+ * Set the new value after direct editing is finished. The value comes from
+ * the text editing UI component. Corresponds to the method
+ * {@link AbstractDirectEditingFeature#setValue(String, IDirectEditingContext)}
+ * . The default implementation checks if the pattern is responsible for the
+ * shape and an ID is set; in that case it delegates to
+ * {@link #setValue(String, IDirectEditingContext, String)}.
+ *
+ * @param value
+ * The new value to be set
+ * @param context
+ * A context object describing the direct edit request.
+ */
@Override
public void setValue(String value, IDirectEditingContext context) {
PictogramElement pictogramElement = context.getPictogramElement();
@@ -939,6 +1058,19 @@
}
}
+ /**
+ * Set the new value after direct editing is finished. The value comes from
+ * the text editing UI component. Corresponds to the method
+ * {@link AbstractDirectEditingFeature#setValue(String, IDirectEditingContext)}
+ * . The default implementation does nothing.
+ *
+ * @param value
+ * The new value to be set
+ * @param context
+ * A context object describing the direct edit request.
+ * @param id
+ * The ID of the shape to set the value for
+ */
protected void setValue(String value, IDirectEditingContext context, String id) {
}
}
diff --git a/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/id/IdUpdateContext.java b/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/id/IdUpdateContext.java
index 9a32cb0..22c3e34 100644
--- a/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/id/IdUpdateContext.java
+++ b/plugins/org.eclipse.graphiti.pattern/src/org/eclipse/graphiti/pattern/id/IdUpdateContext.java
@@ -20,6 +20,14 @@
import org.eclipse.graphiti.mm.pictograms.PictogramElement;
/**
+ * This class represents a special {@link UpdateContext} suitable for usage
+ * within an {@link IdPattern}. Besides the usual {@link UpdateContext} options
+ * this context object also stores the associated {@link GraphicsAlgorithm} for
+ * the {@link PictogramElement} of the context, the root
+ * {@link PictogramElement} of the pattern and the linked domain object. The
+ * second may be of use for easier finding a certain child within a pattern
+ * representation.
+ *
* @since 0.10
* @experimental This API is in an experimental state and should be used by
* clients only with care, as it not final and can be removed or
@@ -31,6 +39,23 @@
private PictogramElement rootPictogramElement;
private Object domainObject;
+ /**
+ * Creates a new {@link IdUpdateContext} instance holding the given
+ * pictogram model instances and domain object instance.
+ *
+ * @param pictogramElement
+ * The {@link PictogramElement} that shall be updated, see
+ * {@link UpdateContext}.
+ * @param graphicsAlgorithm
+ * The associated {@link GraphicsAlgorithm} for the
+ * {@link PictogramElement}
+ * @param rootPictogramElement
+ * The root pictogram element, this is the one that holds the ID
+ * property for the pattern
+ * @param domainObject
+ * The domain object that is linked with the pattern root
+ * pictogram element.
+ */
public IdUpdateContext(PictogramElement pictogramElement, GraphicsAlgorithm graphicsAlgorithm,
PictogramElement rootPictogramElement, Object domainObject) {
super(pictogramElement);
@@ -39,6 +64,11 @@
this.setDomainObject(domainObject);
}
+ /**
+ * Returns the stored {@link PictogramElement}.
+ *
+ * @return The instance of the {@link PictogramElement} to layout.
+ */
@Override
public PictogramElement getPictogramElement() {
/*
@@ -49,26 +79,61 @@
return super.getPictogramElement();
}
+ /**
+ * Returns the stored {@link GraphicsAlgorithm}.
+ *
+ * @return The instance of the {@link GraphicsAlgorithm} for the
+ * {@link PictogramElement} to update.
+ */
public GraphicsAlgorithm getGraphicsAlgorithm() {
return graphicsAlgorithm;
}
+ /**
+ * Sets a new {@link GraphicsAlgorithm} for the {@link PictogramElement} to
+ * update.
+ *
+ * @param graphicsAlgorithm
+ * The new instance to set.
+ */
public void setGraphicsAlgorithm(GraphicsAlgorithm graphicsAlgorithm) {
this.graphicsAlgorithm = graphicsAlgorithm;
}
+ /**
+ * Returns the stored root {@link PictogramElement}.
+ *
+ * @return The instance of the root {@link PictogramElement}.
+ */
public PictogramElement getRootPictogramElement() {
return rootPictogramElement;
}
+ /**
+ * Sets a new root {@link PictogramElement}.
+ *
+ * @param rootPictogramElement
+ * The new instance to set.
+ */
public void setRootPictogramElement(PictogramElement rootPictogramElement) {
this.rootPictogramElement = rootPictogramElement;
}
+ /**
+ * Returns the stored domain object instance.
+ *
+ * @return The stored instance of the domain object.
+ */
public Object getDomainObject() {
return domainObject;
}
+ /**
+ * Sets a new domain object instance.
+ *
+ * @param domainObject
+ * The new instance to set.
+ */
public void setDomainObject(Object domainObject) {
this.domainObject = domainObject;
}
