From bb2d8bbc02eef9b4683d9529b5d60296a985c495 Mon Sep 17 00:00:00 2001
From: Jordan
Date: Thu, 5 Mar 2015 16:28:42 -0500
Subject: [PATCH] Added documentation to the PlotRender class and updated some
of its code to make it more customizable. Also made a method private, hence
the change to MultiPlot in which I simplified some code.
Created a sub-class of it called ParaViewPlotRender. It does nothing
special yet.
Signed-off-by: Jordan
---
.../viz/service/paraview/ParaViewPlot.java | 18 +-
.../service/paraview/ParaViewPlotRender.java | 38 +++
.../eclipse/ice/viz/service/MultiPlot.java | 39 +--
.../eclipse/ice/viz/service/PlotRender.java | 239 ++++++++++++++----
4 files changed, 240 insertions(+), 94 deletions(-)
create mode 100644 src/org.eclipse.ice.viz.service.paraview/src/org/eclipse/ice/viz/service/paraview/ParaViewPlotRender.java
diff --git a/src/org.eclipse.ice.viz.service.paraview/src/org/eclipse/ice/viz/service/paraview/ParaViewPlot.java b/src/org.eclipse.ice.viz.service.paraview/src/org/eclipse/ice/viz/service/paraview/ParaViewPlot.java
index 387a99d41..8d6f73503 100644
--- a/src/org.eclipse.ice.viz.service.paraview/src/org/eclipse/ice/viz/service/paraview/ParaViewPlot.java
+++ b/src/org.eclipse.ice.viz.service.paraview/src/org/eclipse/ice/viz/service/paraview/ParaViewPlot.java
@@ -67,23 +67,7 @@ public Map getPlotTypes() throws Exception {
*/
@Override
protected PlotRender createPlotRender(Composite parent) {
- // TODO We need a custom PlotRender.
- return new PlotRender(parent, this) {
- @Override
- protected Composite createPlotComposite(Composite parent, int style) {
- return new Composite(parent, style);
- }
-
- @Override
- protected void updatePlotComposite(Composite plotComposite)
- throws Exception {
- int seed = (getPlotCategory() + getPlotType()).hashCode();
- Random r = new Random(seed);
- plotComposite.setBackground(new Color(plotComposite
- .getDisplay(), r.nextInt(255), r.nextInt(255), r
- .nextInt(255)));
- }
- };
+ return new ParaViewPlotRender(parent, this);
}
/*
diff --git a/src/org.eclipse.ice.viz.service.paraview/src/org/eclipse/ice/viz/service/paraview/ParaViewPlotRender.java b/src/org.eclipse.ice.viz.service.paraview/src/org/eclipse/ice/viz/service/paraview/ParaViewPlotRender.java
new file mode 100644
index 000000000..755c5d051
--- /dev/null
+++ b/src/org.eclipse.ice.viz.service.paraview/src/org/eclipse/ice/viz/service/paraview/ParaViewPlotRender.java
@@ -0,0 +1,38 @@
+package org.eclipse.ice.viz.service.paraview;
+
+import java.util.Random;
+
+import org.eclipse.ice.viz.service.PlotRender;
+import org.eclipse.swt.graphics.Color;
+import org.eclipse.swt.widgets.Composite;
+
+public class ParaViewPlotRender extends PlotRender {
+
+ public ParaViewPlotRender(Composite parent, ParaViewPlot plot) {
+ super(parent, plot);
+
+ }
+
+ @Override
+ protected Composite createPlotComposite(Composite parent, int style)
+ throws Exception {
+ // TODO Hook this up to the ParaView widgets.
+ return new Composite(parent, style);
+ }
+
+ @Override
+ protected void updatePlotComposite(Composite plotComposite)
+ throws Exception {
+ // TODO Hook this up to the ParaView widgets.
+ int seed = (getPlotCategory() + getPlotType()).hashCode();
+ Random r = new Random(seed);
+ plotComposite.setBackground(new Color(plotComposite.getDisplay(), r
+ .nextInt(255), r.nextInt(255), r.nextInt(255)));
+ }
+
+ @Override
+ protected void disposePlotComposite(Composite plotComposite) {
+ // Nothing to do yet.
+ }
+
+}
diff --git a/src/org.eclipse.ice.viz.service/src/org/eclipse/ice/viz/service/MultiPlot.java b/src/org.eclipse.ice.viz.service/src/org/eclipse/ice/viz/service/MultiPlot.java
index 916af5aad..0c2a63b18 100644
--- a/src/org.eclipse.ice.viz.service/src/org/eclipse/ice/viz/service/MultiPlot.java
+++ b/src/org.eclipse.ice.viz.service/src/org/eclipse/ice/viz/service/MultiPlot.java
@@ -9,7 +9,6 @@
import org.eclipse.swt.SWT;
import org.eclipse.swt.SWTException;
import org.eclipse.swt.widgets.Composite;
-import org.eclipse.swt.widgets.Display;
/**
* This class provides a basic plot capable of drawing in multiple parent
@@ -107,41 +106,19 @@ public void draw(String category, String plotType, Composite parent)
+ "Cannot draw plot inside disposed Composite.");
}
- final PlotRender plotRender;
+ // Get the PlotRender associated with the parent Composite.
+ PlotRender plotRender = plotRenders.get(parent);
- // If necessary, create the PlotRender.
- if (!plotRenders.containsKey(parent)) {
- // Create it and save it in the map.
+ // Create the PlotRender and associate it with the parent as necessary.
+ if (plotRender == null) {
plotRender = createPlotRender(parent);
plotRenders.put(parent, plotRender);
-
- // Send the new plot category and type to the PlotRender.
- plotRender.setPlotCategory(category);
- plotRender.setPlotType(plotType);
-
- // If we are not on the UI thread, create its content asynchronously
- // on the UI thread.
- if (Display.getCurrent() == null) {
- parent.getDisplay().asyncExec(new Runnable() {
- @Override
- public void run() {
- plotRender.createPlotContent(SWT.NONE);
- }
- });
- }
- // If we are on the UI thread, create the content synchronously.
- else {
- plotRender.createPlotContent(SWT.NONE);
- }
- } else {
- // Get the existing PlotCopmosite.
- plotRender = plotRenders.get(parent);
-
- // Send the new plot category and type to the PlotRender.
- plotRender.setPlotCategory(category);
- plotRender.setPlotType(plotType);
}
+ // Send the new plot category and type to the PlotRender.
+ plotRender.setPlotCategory(category);
+ plotRender.setPlotType(plotType);
+
// Trigger the appropriate update to the PlotRender's content.
updatePlotRender(plotRender);
diff --git a/src/org.eclipse.ice.viz.service/src/org/eclipse/ice/viz/service/PlotRender.java b/src/org.eclipse.ice.viz.service/src/org/eclipse/ice/viz/service/PlotRender.java
index 08c344581..20a104130 100644
--- a/src/org.eclipse.ice.viz.service/src/org/eclipse/ice/viz/service/PlotRender.java
+++ b/src/org.eclipse.ice.viz.service/src/org/eclipse/ice/viz/service/PlotRender.java
@@ -1,10 +1,9 @@
package org.eclipse.ice.viz.service;
-import java.util.Random;
-
+import org.eclipse.ice.client.widgets.viz.service.IPlot;
import org.eclipse.swt.SWT;
+import org.eclipse.swt.SWTException;
import org.eclipse.swt.custom.StackLayout;
-import org.eclipse.swt.graphics.Color;
import org.eclipse.swt.graphics.Image;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
@@ -12,12 +11,42 @@
import org.eclipse.swt.widgets.Display;
import org.eclipse.swt.widgets.Label;
+/**
+ * This class manages a single rendering of an {@link IPlot}.
+ *
+ * After creating a {@code PlotRender}, its content will need to be created via
+ * {@link #createRenderContent(int)}. It can be updated later by calling
+ * {@link #refresh()}.
+ *
+ *
+ * Sub-classes should implement the required methods to populate/update the
+ * {@link #plotComposite} and may also override the methods that populate/update
+ * the {@link #infoComposite} to add extra informational features as necessary.
+ *
+ *
+ * @author Jordan
+ *
+ */
public abstract class PlotRender {
+ // TODO We may want to add a ToolBar
+
+ /**
+ * The parent {@code Composite} that contains the plot render.
+ */
public final Composite parent;
- public final MultiPlot plot;
+ /**
+ * The rendered {@code IPlot}. This cannot be changed.
+ */
+ public final IPlot plot;
+ /**
+ * The current plot category.
+ */
private String category;
+ /**
+ * The current plot type.
+ */
private String type;
// ---- UI Widgets ---- //
@@ -47,37 +76,70 @@ public abstract class PlotRender {
// -------------------- //
- public PlotRender(Composite parent, MultiPlot plot) {
+ /**
+ * The default constructor.
+ *
+ * @param parent
+ * The parent {@code Composite} that contains the plot render.
+ * @param plot
+ * The rendered {@code IPlot}. This cannot be changed.
+ */
+ public PlotRender(Composite parent, IPlot plot) {
+ // Check the parameters.
+ if (parent == null || plot == null) {
+ throw new NullPointerException("PlotRender error: "
+ + "Cannot render a plot that is null or "
+ + "inside a null parent Composite.");
+ }
this.parent = parent;
this.plot = plot;
- }
-
- public void createPlotContent(int style) {
-
- // Create the container for the info and plot Composites.
- stackComposite = new Composite(parent, style);
- stackComposite.setFont(parent.getFont());
- stackComposite.setBackground(parent.getBackground());
- stackComposite.setLayout(new StackLayout());
-
- refresh();
return;
}
+ /**
+ * Sets the current plot category.
+ *
+ * Note: A subsequent call to {@link #refresh()} will be necessary to
+ * sync the UI with this call's changes.
+ *
+ *
+ * @param category
+ * The new plot category.
+ */
public void setPlotCategory(String category) {
this.category = category;
}
+ /**
+ * Sets the current plot type.
+ *
+ * Note: A subsequent call to {@link #refresh()} will be necessary to
+ * sync the UI with this call's changes.
+ *
+ *
+ * @param type
+ * The new plot type.
+ */
public void setPlotType(String type) {
this.type = type;
}
+ /**
+ * Gets the current plot category.
+ *
+ * @return The current plot category.
+ */
public String getPlotCategory() {
return category;
}
+ /**
+ * Gets the current plot type.
+ *
+ * @return The current plot type.
+ */
public String getPlotType() {
return type;
}
@@ -91,22 +153,22 @@ public String getPlotType() {
*
*/
protected void refresh() {
- if (stackComposite != null && !stackComposite.isDisposed()) {
- // If we are not on the UI thread, update the UI asynchronously on
- // the UI thread.
- if (Display.getCurrent() == null) {
- stackComposite.getDisplay().asyncExec(new Runnable() {
- @Override
- public void run() {
- refreshUI();
- }
- });
- }
- // If we are on the UI thread, update the UI synchronously.
- else {
- refreshUI();
- }
+
+ // If we are not on the UI thread, update the UI asynchronously on
+ // the UI thread.
+ if (Display.getCurrent() == null) {
+ parent.getDisplay().asyncExec(new Runnable() {
+ @Override
+ public void run() {
+ refreshUI();
+ }
+ });
}
+ // If we are on the UI thread, update the UI synchronously.
+ else {
+ refreshUI();
+ }
+
return;
}
@@ -116,6 +178,11 @@ public void run() {
* {@link #refresh()}.
*/
private void refreshUI() {
+ // Create the basic content if necessary.
+ if (stackComposite == null) {
+ createBasicContent();
+ }
+
// Get the StackLayout from the plot Composite.
final StackLayout stackLayout = (StackLayout) stackComposite
.getLayout();
@@ -133,7 +200,7 @@ private void refreshUI() {
disposeInfoComposite(infoComposite);
infoComposite = null;
}
-
+
// Update the stack layout, putting the plotComposite in front.
if (stackLayout.topControl != plotComposite) {
stackLayout.topControl = plotComposite;
@@ -151,7 +218,7 @@ private void refreshUI() {
disposePlotComposite(plotComposite);
plotComposite = null;
}
-
+
// Update the stack layout, putting the infoComposite in front.
if (stackLayout.topControl != infoComposite) {
stackLayout.topControl = infoComposite;
@@ -162,6 +229,45 @@ private void refreshUI() {
return;
}
+ /**
+ * Creates the most basic content for the {@code PlotRender}.
+ *
+ * Note: This method should only called from the UI
+ * thread ONCE via {@link #refresh()}.
+ *
+ */
+ private void createBasicContent() throws SWTException {
+
+ // Create the container for the info and plot Composites.
+ stackComposite = new Composite(parent, SWT.NONE);
+ stackComposite.setFont(parent.getFont());
+ stackComposite.setBackground(parent.getBackground());
+ stackComposite.setLayout(new StackLayout());
+
+ return;
+ }
+
+ /**
+ * Creates the informational {@code Composite} that is shown when an
+ * exception occurs during calls to {@link #updatePlotComposite(Composite)}.
+ *
+ * The default {@link #infoComposite} contains an icon label to the left and
+ * a {@code Composite} on the right with a default {@code GridLayout} and a
+ * message label. The label will show the message from the plot update
+ * exception.
+ *
+ *
+ * Note: If overridden, be sure to either call this super method or
+ * also override {@link #updateInfoComposite(Composite, String)}.
+ *
+ *
+ * @param parent
+ * The parent in which the info {@code Composite} should be
+ * created.
+ * @param style
+ * The style to use for the info {@code Composite}.
+ * @return The new info {@code Composite}.
+ */
protected Composite createInfoComposite(Composite parent, int style) {
Composite infoComposite = new Composite(parent, style);
@@ -186,6 +292,16 @@ protected Composite createInfoComposite(Composite parent, int style) {
return infoComposite;
}
+ /**
+ * Updates the information contained in the specified informational
+ * {@code Composite}.
+ *
+ *
+ * @param infoComposite
+ * The info {@code Composite} to update.
+ * @param message
+ * The message to display in its message label.
+ */
protected void updateInfoComposite(Composite infoComposite,
final String message) {
// Set the message and icon based on the state of the connection.
@@ -202,25 +318,56 @@ protected void updateInfoComposite(Composite infoComposite,
return;
}
+ /**
+ * Disposes the specified info {@code Composite} and any related resources.
+ *
+ * @param infoComposite
+ * The info {@code Composite} to dispose.
+ */
protected void disposeInfoComposite(Composite infoComposite) {
infoComposite.dispose();
iconLabel = null;
msgLabel = null;
}
-
- protected Composite createPlotComposite(Composite parent, int style)
- throws Exception {
- return new Composite(parent, style);
- }
- protected void updatePlotComposite(Composite plotComposite)
- throws Exception {
- int seed = (category + type).hashCode();
- Random r = new Random(seed);
- plotComposite.setBackground(new Color(plotComposite.getDisplay(), r
- .nextInt(255), r.nextInt(255), r.nextInt(255)));
- }
-
+ /**
+ * Creates the plot {@code Composite} that is shown when the associated
+ * {@link #plot}, {@link #category}, and {@link #type} are all valid.
+ *
+ * @param parent
+ * The parent in which the plot {@code Composite} should be
+ * created.
+ * @param style
+ * The style to use for the plot {@code Composite}.
+ * @return The new plot {@code Composite}.
+ * @throws Exception
+ * If the plot is in an invalid state or otherwise cannot be
+ * rendered, this throws an exception with an informative
+ * message.
+ */
+ protected abstract Composite createPlotComposite(Composite parent, int style)
+ throws Exception;
+
+ /**
+ * Updates the plot rendering contained in the specified plot
+ * {@code Composite}.
+ *
+ * @param plotComposite
+ * The plot {@code Composite} to update.
+ * @throws Exception
+ * If the plot is in an invalid state or otherwise cannot be
+ * rendered, this throws an exception with an informative
+ * message.
+ */
+ protected abstract void updatePlotComposite(Composite plotComposite)
+ throws Exception;
+
+ /**
+ * Disposes the specified plot {@code Composite} and any related resources.
+ *
+ * @param plotComposite
+ * The plot {@code Composite} to dispose.
+ */
protected void disposePlotComposite(Composite plotComposite) {
// Nothing to do.
}