Include preview mouse listeners support and bug fixes implemented in legend project.

modules/PreviewAPI/src/main/java/org/gephi/preview/PreviewControllerImpl.java

@@ -43,14 +43,13 @@ package org.gephi.preview;
 
 import java.awt.Dimension;
 import java.awt.Point;
+import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import org.gephi.data.attributes.api.AttributeController;
 import org.gephi.data.attributes.api.AttributeModel;
 import org.gephi.graph.api.*;
 import org.gephi.preview.api.*;
-import org.gephi.preview.spi.ItemBuilder;
+import org.gephi.preview.spi.*;
-import org.gephi.preview.spi.RenderTargetBuilder;
-import org.gephi.preview.spi.Renderer;
 import org.gephi.project.api.ProjectController;
 import org.gephi.project.api.Workspace;
 import org.gephi.project.api.WorkspaceListener;
@@ -150,7 +149,21 @@ public class PreviewControllerImpl implements PreviewController {
             }
         }
 
-        Renderer[] renderers = model.getManagedEnabledRenderers();
+        Renderer[] renderers;
+        if (!mousePressed) {
+            renderers = model.getManagedEnabledRenderers();
+        } else {
+            ArrayList<Renderer> renderersList = new ArrayList<Renderer>();
+            for(Renderer renderer: model.getManagedEnabledRenderers()){
+                //Only mouse responsive renderers will be called while mouse is pressed
+                if(renderer instanceof MouseResponsiveRenderer){
+                    renderersList.add(renderer);
+                }
+            }
+
+            renderers = renderersList.toArray(new Renderer[0]);
+        }
+
         if (renderers == null) {
             renderers = getRegisteredRenderers();
         }
@@ -250,14 +263,11 @@ public class PreviewControllerImpl implements PreviewController {
 
     @Override
     public void render(RenderTarget target, Renderer[] renderers, Workspace workspace) {
-        render(target, renderers, getModel(workspace));
+        render(target, renderers != null ? renderers : getModel(workspace).getManagedEnabledRenderers(), getModel(workspace));
     }
 
     private synchronized void render(RenderTarget target, Renderer[] renderers, PreviewModelImpl previewModel) {
         if (previewModel != null) {
-            if (renderers == null) {
-                renderers = getRegisteredRenderers();
-            }
             PreviewProperties properties = previewModel.getProperties();
 
             //Progress
@@ -265,10 +275,12 @@ public class PreviewControllerImpl implements PreviewController {
             if (target instanceof AbstractRenderTarget) {
                 int tasks = 0;
                 for (Renderer r : renderers) {
-                    for (String type : previewModel.getItemTypes()) {
+                    if (!mousePressed || r instanceof MouseResponsiveRenderer) {
-                        for (Item item : previewModel.getItems(type)) {
+                        for (String type : previewModel.getItemTypes()) {
-                            if (r.isRendererForitem(item, properties)) {
+                            for (Item item : previewModel.getItems(type)) {
-                                tasks++;
+                                if (r.isRendererForitem(item, properties)) {
+                                    tasks++;
+                                }
                             }
                         }
                     }
@@ -280,14 +292,16 @@ public class PreviewControllerImpl implements PreviewController {
 
             //Render items
             for (Renderer r : renderers) {
-                for (String type : previewModel.getItemTypes()) {
+                if (!mousePressed || r instanceof MouseResponsiveRenderer) {
-                    for (Item item : previewModel.getItems(type)) {
+                    for (String type : previewModel.getItemTypes()) {
-                        if (r.isRendererForitem(item, properties)) {
+                        for (Item item : previewModel.getItems(type)) {
-                            r.render(item, target, properties);
+                            if (r.isRendererForitem(item, properties)) {
-                            Progress.progress(progressTicket);
+                                r.render(item, target, properties);
-                            if (target instanceof AbstractRenderTarget) {
+                                Progress.progress(progressTicket);
-                                if (((AbstractRenderTarget) target).isCancelled()) {
+                                if (target instanceof AbstractRenderTarget) {
-                                    return;
+                                    if (((AbstractRenderTarget) target).isCancelled()) {
+                                        return;
+                                    }
                                 }
                             }
                         }
@@ -373,4 +387,46 @@ public class PreviewControllerImpl implements PreviewController {
         }
         return anyPluginRendererRegistered;
     }
+    private boolean mousePressed = false;
+    
+    @Override
+    public boolean sendMouseEvent(PreviewMouseEvent event){
+        return sendMouseEvent(event, Lookup.getDefault().lookup(ProjectController.class).getCurrentWorkspace());
+    }
+
+    @Override
+    public boolean sendMouseEvent(PreviewMouseEvent event, Workspace workspace) {
+        if(workspace == null){
+            return false;
+        }
+        
+        PreviewModel previewModel = getModel(workspace);
+        
+        //Avoid drag events arriving to listeners if they did not consume previous press event.
+        if ((event.type != PreviewMouseEvent.Type.DRAGGED && event.type != PreviewMouseEvent.Type.RELEASED) || mousePressed) {
+            for (PreviewMouseListener listener : previewModel.getEnabledMouseListeners()) {
+                switch (event.type) {
+                    case CLICKED:
+                        listener.mouseClicked(event, previewModel.getProperties(), workspace);
+                        break;
+                    case PRESSED:
+                        mousePressed = true;
+                        listener.mousePressed(event, previewModel.getProperties(), workspace);
+                        break;
+                    case DRAGGED:
+                        listener.mouseDragged(event, previewModel.getProperties(), workspace);
+                        break;
+                    case RELEASED:
+                        mousePressed = false;
+                        listener.mouseReleased(event, previewModel.getProperties(), workspace);
+                }
+                if (event.isConsumed()) {
+                    return true;
+                }
+            }
+        }
+
+        mousePressed = false;//Avoid drag events arriving to listeners if they did not consume previous press event.
+        return false;
+    }
 }

modules/PreviewAPI/src/main/java/org/gephi/preview/ProcessingApplet.java

@@ -45,15 +45,11 @@ import java.awt.Color;
 import java.awt.Dimension;
 import java.awt.Font;
 import java.awt.Point;
-import java.awt.event.MouseWheelEvent;
+import java.awt.event.*;
-import java.awt.event.MouseWheelListener;
 import java.util.HashMap;
 import java.util.Timer;
 import java.util.TimerTask;
-import org.gephi.preview.api.PreviewController;
+import org.gephi.preview.api.*;
-import org.gephi.preview.api.PreviewModel;
-import org.gephi.preview.api.PreviewProperty;
-import org.gephi.preview.api.RenderTarget;
 import org.openide.util.Lookup;
 import processing.core.PApplet;
 import processing.core.PFont;
@@ -143,24 +139,90 @@ public class ProcessingApplet extends PApplet implements MouseWheelListener {
             super.resizeRenderer(i, i1);
         }
     }
+    
+    private PVector screenPositionToModelPosition(PVector screenPos) {
+        PVector center = new PVector(width / 2f, height / 2f);
+        PVector scaledCenter = PVector.mult(center, scaling);
+        PVector scaledTrans = PVector.sub(center, scaledCenter);
 
-    @Override
+        PVector modelPos = new PVector(screenPos.x, screenPos.y);
-    public void mousePressed() {
+        modelPos.sub(scaledTrans);
-        ref.set(mouseX, mouseY, 0);
+        modelPos.div(scaling);
+        modelPos.sub(trans);
+        return modelPos;
+    }
+    
+    private PVector getMouseModelPosition(){
+        return screenPositionToModelPosition(new PVector(mouseX, mouseY));
+    }
+    
+    private PreviewMouseEvent buildPreviewMouseEvent(PreviewMouseEvent.Type type){
+        PVector pos = getMouseModelPosition();
+        PreviewMouseEvent.Button button;
+        
+        switch(mouseButton){
+            case CENTER:
+                button = PreviewMouseEvent.Button.MIDDLE;
+                break;
+            case RIGHT:
+                button = PreviewMouseEvent.Button.RIGHT;
+                break;
+            case LEFT:
+            default:
+                button = PreviewMouseEvent.Button.LEFT;
+        }
+        
+        return new PreviewMouseEvent((int)pos.x, (int)pos.y, type, button, keyEvent);
     }
 
+    @Override
+    public void mouseClicked() {
+        if (previewController.sendMouseEvent(buildPreviewMouseEvent(PreviewMouseEvent.Type.CLICKED))) {
+            previewController.refreshPreview();
+            redraw();
+        }
+    }
+
+    @Override
+    public void mousePressed() {
+        previewController.sendMouseEvent(buildPreviewMouseEvent(PreviewMouseEvent.Type.PRESSED));
+        
+        previewController.refreshPreview();
+        handleMousePress();
+        redraw();
+    }
+    
     @Override
     public void mouseDragged() {
-        setMoving(true);
+        if (!previewController.sendMouseEvent(buildPreviewMouseEvent(PreviewMouseEvent.Type.DRAGGED))) {
-        trans.set(mouseX, mouseY, 0);
+            handleMouseDrag();
-        trans.sub(ref);
+        }
-        trans.div(scaling); // ensure const. moving speed whatever the zoom is
-        trans.add(lastMove);
         redraw();
     }
 
     @Override
     public void mouseReleased() {
+        if (!previewController.sendMouseEvent(buildPreviewMouseEvent(PreviewMouseEvent.Type.RELEASED))) {
+            handleMouseRelease();
+        }
+        
+        previewController.refreshPreview();
+        redraw();
+    }
+    
+    private void handleMousePress(){
+        ref.set(mouseX, mouseY, 0);
+    }
+    
+    private void handleMouseDrag(){
+        setMoving(true);
+        trans.set(mouseX, mouseY, 0);
+        trans.sub(ref);
+        trans.div(scaling); // ensure const. moving speed whatever the zoom is
+        trans.add(lastMove);
+    }
+    
+    private void handleMouseRelease() {
         lastMove.set(trans);
         setMoving(false);
         redraw();

modules/PreviewAPI/src/main/java/org/gephi/preview/api/PreviewController.java

@@ -169,4 +169,19 @@ public interface PreviewController {
      * @return True if any plugin renderer is found in the system
      */
     public boolean isAnyPluginRendererRegistered();
+    
+    /**
+     * Sends a <code>PreviewMouseEvent</code> to the current workspace, if any.
+     * @param event PreviewMouseEvent
+     * @return True if the event was consumed, false otherwise
+     */
+    public boolean sendMouseEvent(PreviewMouseEvent event);
+    
+    /**
+     * Sends a <code>PreviewMouseEvent</code> to the given workspace.
+     * @param event PreviewMouseEvent
+     * @param workspace
+     * @return True if the event was consumed, false otherwise
+     */
+    public boolean sendMouseEvent(PreviewMouseEvent event, Workspace workspace);
 }

modules/PreviewAPI/src/main/java/org/gephi/preview/api/PreviewModel.java

@@ -1,43 +1,43 @@
 /*
-Copyright 2008-2011 Gephi
+ Copyright 2008-2011 Gephi
-Authors : Yudi Xue <yudi.xue@usask.ca>, Mathieu Bastian
+ Authors : Yudi Xue <yudi.xue@usask.ca>, Mathieu Bastian
-Website : http://www.gephi.org
+ Website : http://www.gephi.org
 
-This file is part of Gephi.
+ This file is part of Gephi.
 
-DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+ DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 
-Copyright 2011 Gephi Consortium. All rights reserved.
+ Copyright 2011 Gephi Consortium. All rights reserved.
 
-The contents of this file are subject to the terms of either the GNU
+ The contents of this file are subject to the terms of either the GNU
-General Public License Version 3 only ("GPL") or the Common
+ General Public License Version 3 only ("GPL") or the Common
-Development and Distribution License("CDDL") (collectively, the
+ Development and Distribution License("CDDL") (collectively, the
-"License"). You may not use this file except in compliance with the
+ "License"). You may not use this file except in compliance with the
-License. You can obtain a copy of the License at
+ License. You can obtain a copy of the License at
-http://gephi.org/about/legal/license-notice/
+ http://gephi.org/about/legal/license-notice/
-or /cddl-1.0.txt and /gpl-3.0.txt. See the License for the
+ or /cddl-1.0.txt and /gpl-3.0.txt. See the License for the
-specific language governing permissions and limitations under the
+ specific language governing permissions and limitations under the
-License.  When distributing the software, include this License Header
+ License.  When distributing the software, include this License Header
-Notice in each file and include the License files at
+ Notice in each file and include the License files at
-/cddl-1.0.txt and /gpl-3.0.txt. If applicable, add the following below the
+ /cddl-1.0.txt and /gpl-3.0.txt. If applicable, add the following below the
-License Header, with the fields enclosed by brackets [] replaced by
+ License Header, with the fields enclosed by brackets [] replaced by
-your own identifying information:
+ your own identifying information:
-"Portions Copyrighted [year] [name of copyright owner]"
+ "Portions Copyrighted [year] [name of copyright owner]"
 
-If you wish your version of this file to be governed by only the CDDL
+ If you wish your version of this file to be governed by only the CDDL
-or only the GPL Version 3, indicate your decision by adding
+ or only the GPL Version 3, indicate your decision by adding
-"[Contributor] elects to include this software in this distribution
+ "[Contributor] elects to include this software in this distribution
-under the [CDDL or GPL Version 3] license." If you do not indicate a
+ under the [CDDL or GPL Version 3] license." If you do not indicate a
-single choice of license, a recipient has the option to distribute
+ single choice of license, a recipient has the option to distribute
-your version of this file under either the CDDL, the GPL Version 3 or
+ your version of this file under either the CDDL, the GPL Version 3 or
-to extend the choice of license to its licensees as provided above.
+ to extend the choice of license to its licensees as provided above.
-However, if you add GPL Version 3 code and therefore, elected the GPL
+ However, if you add GPL Version 3 code and therefore, elected the GPL
-Version 3 license, then the option applies only if the new code is
+ Version 3 license, then the option applies only if the new code is
-made subject to such option by the copyright holder.
+ made subject to such option by the copyright holder.
 
-Contributor(s):
+ Contributor(s):
 
-Portions Copyrighted 2011 Gephi Consortium.
+ Portions Copyrighted 2011 Gephi Consortium.
  */
 package org.gephi.preview.api;
 
@@ -47,19 +47,15 @@ import org.gephi.graph.api.Edge;
 import org.gephi.graph.api.Graph;
 import org.gephi.graph.api.Node;
 import org.gephi.preview.spi.ItemBuilder;
+import org.gephi.preview.spi.PreviewMouseListener;
 import org.gephi.preview.spi.Renderer;
 
 /**
- * The Preview Model contains all items and all preview properties.
+ * The Preview Model contains all items and all preview properties. <p> Items are the visual elements built from the {@link Graph} by {@link ItemBuilder} implementations and can be retrieved from this
- * <p>
+ * class. Each item has a type and default types are {@link Item#NODE}, {@link Item#EDGE}, {@link Item#NODE_LABEL} and {@link Item#EDGE_LABEL}. <p> A preview model is attached to it's workspace and
- * Items are the visual elements built from the {@link Graph} by {@link ItemBuilder} 
+ * can be retrieved from the
- * implementations and can be retrieved from this class. Each item has a type and
- * default types are {@link Item#NODE}, {@link Item#EDGE}, {@link Item#NODE_LABEL}
- * and {@link Item#EDGE_LABEL}.
- * <p>
- * A preview model is attached to it's workspace and can be retrieved from the
  * {@link PreviewController}.
- * 
+ *
  * @author Yudi Xue, Mathieu Bastian
  * @see Item
  * @see Renderer
@@ -68,78 +64,88 @@ public interface PreviewModel {
 
     /**
      * Returns the preview properties attached to this model.
+     *
      * @return the preview properties
      */
     public PreviewProperties getProperties();
 
     /**
-     * Returns all items with <code>type</code> as type.
+     * Returns all items with
-     * <p>
+     * <code>type</code> as type. <p> Default types are {@link Item#NODE}, {@link Item#EDGE}, {@link Item#NODE_LABEL} and {@link Item#EDGE_LABEL}.
-     * Default types are {@link Item#NODE}, {@link Item#EDGE}, {@link Item#NODE_LABEL}
+     *
-     * and {@link Item#EDGE_LABEL}.
      * @param type the item's type
      * @return all items from this type
      */
     public Item[] getItems(String type);
 
     /**
-     * Returns all items attached to <code>source</code>.
+     * Returns all items attached to
-     * <p>
+     * <code>source</code>. <p> The source is the graph object behind the item (e.g.
-     * The source is the graph object behind the item (e.g.
+     * {@link Node} or {@link Edge}). Multiple items can be created from the same source object. For instance both
-     * {@link Node} or {@link Edge}). Multiple items can be created from the same
+     * <code>Item.NODE</code> and
-     * source object. For instance both <code>Item.NODE</code> and
      * <code>Item.NODE_LABEL</code> have the node object as source.
+     *
      * @param source the item's source
-     * @return all items with <code>source</code> as source
+     * @return all items with
+     * <code>source</code> as source
      */
     public Item[] getItems(Object source);
 
     /**
-     * Returns the item attached to <code>source</code> and with the type
+     * Returns the item attached to
-     * <code>type</code>. 
+     * <code>source</code> and with the type
-     * <p>
+     * <code>type</code>. <p> The source is the graph object behind the item (e.g.
-     * The source is the graph object behind the item (e.g.
+     * {@link Node} or {@link Edge}) and the type a default or a custom type. <p> Default types are {@link Item#NODE}, {@link Item#EDGE}, {@link Item#NODE_LABEL} and {@link Item#EDGE_LABEL}.
-     * {@link Node} or {@link Edge}) and the type a default or a custom type.
+     *
-     * <p>
-     * Default types are {@link Item#NODE}, {@link Item#EDGE}, {@link Item#NODE_LABEL}
-     * and {@link Item#EDGE_LABEL}.
      * @param type the item's type
      * @param source the item's source object
-     * @return the item or <code>null</code> if not found
+     * @return the item or
+     * <code>null</code> if not found
      */
     public Item getItem(String type, Object source);
-    
+
     /**
-     * <p>Returns currently managed renderers, or null.</p>
+     * <p>Returns currently managed renderers, or null.</p> <p>If
-     * <p>If <code>managedRenderers</code> is set to null, all renderers will be executed when rendering, in default implementation order.</p>
+     * <code>managedRenderers</code> is set to null, all renderers will be executed when rendering, in default implementation order.</p>
+     *
      * @return Enabled renderers or null
      */
     public ManagedRenderer[] getManagedRenderers();
 
     /**
-     * <p>Sets an user-defined array of managed renderers to use when rendering.</p>
+     * <p>Sets an user-defined array of managed renderers to use when rendering.</p> <p><b>Only</b> the renderers marked as enabled will be executed when rendering, and <b>respecting the array
-     * <p><b>Only</b> the renderers marked as enabled will be executed when rendering, and <b>respecting the array order</b></p>
+     * order</b></p> <p>If the input array does not contain a managed renderer for some renderer existing implementation, a new not enabled managed renderer will be added to the end of the input
-     * <p>If the input array does not contain a managed renderer for some renderer existing implementation, a new not enabled managed renderer will be added to the end of the input array</p>
+     * array</p> <p>If
-     * <p>If <code>managedRenderers</code> is set to null, all renderers will be executed when rendering, in default implementation order.</p>
+     * <code>managedRenderers</code> is set to null, all renderers will be executed when rendering, in default implementation order.</p>
+     *
      * @param managedRenderers Managed renderers for future renderings
      */
     public void setManagedRenderers(ManagedRenderer[] managedRenderers);
-    
+
     /**
-     * Returns <code>managedRenderers</code> Renderers that are enabled, or null if <code>managedRenderers</code> is null.
+     * Returns
+     * <code>managedRenderers</code> Renderers that are enabled, or null if
+     * <code>managedRenderers</code> is null.
+     *
      * @return Enabled renderers or null
      */
     public Renderer[] getManagedEnabledRenderers();
 
+    /*
+     * Returns <code>managedPreviewMouseListeners</code> containing the <code>PreviewMouseListeners</code> that are declared by the current enabled managed renderers.
+     */
+    public PreviewMouseListener[] getEnabledMouseListeners();
+
     /**
      * Returns the width and height of the graph in the graph coordinates.
+     *
      * @return the graph dimensions
      */
     public Dimension getDimensions();
 
     /**
-     * Returns the top left position in the graph coordinate (i.e. not the preview
+     * Returns the top left position in the graph coordinate (i.e. not the preview coordinates).
-     * coordinates).
+     *
      * @return the top left position point
      */
     public Point getTopLeftPosition();

modules/PreviewAPI/src/main/java/org/gephi/preview/api/PreviewMouseEvent.java

@@ -0,0 +1,94 @@
+/*
+ Copyright 2008-2012 Gephi
+ Authors : Eduardo Ramos
+ Website : http://www.gephi.org
+
+ This file is part of Gephi.
+
+ DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+
+ Copyright 2011 Gephi Consortium. All rights reserved.
+
+ The contents of this file are subject to the terms of either the GNU
+ General Public License Version 3 only ("GPL") or the Common
+ Development and Distribution License("CDDL") (collectively, the
+ "License"). You may not use this file except in compliance with the
+ License. You can obtain a copy of the License at
+ http://gephi.org/about/legal/license-notice/
+ or /cddl-1.0.txt and /gpl-3.0.txt. See the License for the
+ specific language governing permissions and limitations under the
+ License.  When distributing the software, include this License Header
+ Notice in each file and include the License files at
+ /cddl-1.0.txt and /gpl-3.0.txt. If applicable, add the following below the
+ License Header, with the fields enclosed by brackets [] replaced by
+ your own identifying information:
+ "Portions Copyrighted [year] [name of copyright owner]"
+
+ If you wish your version of this file to be governed by only the CDDL
+ or only the GPL Version 3, indicate your decision by adding
+ "[Contributor] elects to include this software in this distribution
+ under the [CDDL or GPL Version 3] license." If you do not indicate a
+ single choice of license, a recipient has the option to distribute
+ your version of this file under either the CDDL, the GPL Version 3 or
+ to extend the choice of license to its licensees as provided above.
+ However, if you add GPL Version 3 code and therefore, elected the GPL
+ Version 3 license, then the option applies only if the new code is
+ made subject to such option by the copyright holder.
+
+ Contributor(s):
+
+ Portions Copyrighted 2012 Gephi Consortium.
+ */
+package org.gephi.preview.api;
+
+import java.awt.event.KeyEvent;
+
+/**
+ * <p>Mouse event for preview. Contains the event type and graph coordinates for the event.
+ * If you attend a <code>PreviewMouseEvent</code>, it should be marked as consumed.</p>
+ * <p>The public keyEvent field contains the keyboard state for the given mouse event. Can be null.</p>
+ * @author Eduardo Ramos<eduramiba@gmail.com>
+ */
+public class PreviewMouseEvent {
+
+    public enum Type {
+        CLICKED,
+        PRESSED,
+        RELEASED,
+        DRAGGED
+    }
+    
+    public enum Button{
+        LEFT,
+        RIGHT,
+        MIDDLE
+    }
+    
+    public final Type type;
+    public final Button button;
+    public final int x;
+    public final int y;
+    private boolean consumed;
+    
+    /**
+     * Contains the keyboard state for the given mouse event. Can be null.
+     */
+    public final KeyEvent keyEvent;
+
+    public PreviewMouseEvent(int x, int y, Type type, Button button, KeyEvent keyEvent) {
+        this.x = x;
+        this.y = y;
+        this.type = type;
+        this.button = button;
+        this.keyEvent = keyEvent;
+        consumed = false;
+    }
+
+    public boolean isConsumed() {
+        return consumed;
+    }
+
+    public void setConsumed(boolean consumed) {
+        this.consumed = consumed;
+    }
+}

modules/PreviewAPI/src/main/java/org/gephi/preview/spi/MouseResponsiveRenderer.java

@@ -0,0 +1,51 @@
+/*
+ Copyright 2008-2012 Gephi
+ Authors : Eduardo Ramos
+ Website : http://www.gephi.org
+
+ This file is part of Gephi.
+
+ DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+
+ Copyright 2011 Gephi Consortium. All rights reserved.
+
+ The contents of this file are subject to the terms of either the GNU
+ General Public License Version 3 only ("GPL") or the Common
+ Development and Distribution License("CDDL") (collectively, the
+ "License"). You may not use this file except in compliance with the
+ License. You can obtain a copy of the License at
+ http://gephi.org/about/legal/license-notice/
+ or /cddl-1.0.txt and /gpl-3.0.txt. See the License for the
+ specific language governing permissions and limitations under the
+ License.  When distributing the software, include this License Header
+ Notice in each file and include the License files at
+ /cddl-1.0.txt and /gpl-3.0.txt. If applicable, add the following below the
+ License Header, with the fields enclosed by brackets [] replaced by
+ your own identifying information:
+ "Portions Copyrighted [year] [name of copyright owner]"
+
+ If you wish your version of this file to be governed by only the CDDL
+ or only the GPL Version 3, indicate your decision by adding
+ "[Contributor] elects to include this software in this distribution
+ under the [CDDL or GPL Version 3] license." If you do not indicate a
+ single choice of license, a recipient has the option to distribute
+ your version of this file under either the CDDL, the GPL Version 3 or
+ to extend the choice of license to its licensees as provided above.
+ However, if you add GPL Version 3 code and therefore, elected the GPL
+ Version 3 license, then the option applies only if the new code is
+ made subject to such option by the copyright holder.
+
+ Contributor(s):
+
+ Portions Copyrighted 2012 Gephi Consortium.
+ */
+package org.gephi.preview.spi;
+
+/**
+ * <b>Optionally</b> implement this interface in a <code>Renderer</code> that needs to be responsive to mouse events.
+ * Only renderers that implement this interface will be drawn while mouse events are being attended (such as dragging).
+ * @author Eduardo Ramos<eduramiba@gmail.com>
+ */
+public interface MouseResponsiveRenderer {
+    public boolean needsPreviewMouseListener(PreviewMouseListener previewMouseListener);
+}

modules/PreviewAPI/src/main/java/org/gephi/preview/spi/PreviewMouseListener.java

@@ -0,0 +1,89 @@
+/*
+ Copyright 2008-2012 Gephi
+ Authors : Eduardo Ramos
+ Website : http://www.gephi.org
+
+ This file is part of Gephi.
+
+ DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+
+ Copyright 2011 Gephi Consortium. All rights reserved.
+
+ The contents of this file are subject to the terms of either the GNU
+ General Public License Version 3 only ("GPL") or the Common
+ Development and Distribution License("CDDL") (collectively, the
+ "License"). You may not use this file except in compliance with the
+ License. You can obtain a copy of the License at
+ http://gephi.org/about/legal/license-notice/
+ or /cddl-1.0.txt and /gpl-3.0.txt. See the License for the
+ specific language governing permissions and limitations under the
+ License.  When distributing the software, include this License Header
+ Notice in each file and include the License files at
+ /cddl-1.0.txt and /gpl-3.0.txt. If applicable, add the following below the
+ License Header, with the fields enclosed by brackets [] replaced by
+ your own identifying information:
+ "Portions Copyrighted [year] [name of copyright owner]"
+
+ If you wish your version of this file to be governed by only the CDDL
+ or only the GPL Version 3, indicate your decision by adding
+ "[Contributor] elects to include this software in this distribution
+ under the [CDDL or GPL Version 3] license." If you do not indicate a
+ single choice of license, a recipient has the option to distribute
+ your version of this file under either the CDDL, the GPL Version 3 or
+ to extend the choice of license to its licensees as provided above.
+ However, if you add GPL Version 3 code and therefore, elected the GPL
+ Version 3 license, then the option applies only if the new code is
+ made subject to such option by the copyright holder.
+
+ Contributor(s):
+
+ Portions Copyrighted 2012 Gephi Consortium.
+ */
+package org.gephi.preview.spi;
+
+import org.gephi.preview.api.PreviewMouseEvent;
+import org.gephi.preview.api.PreviewProperties;
+import org.gephi.project.api.Workspace;
+
+/**
+ * <p>Listener for mouse events in Preview.</p>
+ * <p>Listeners will <b>always</b> receive left mouse button events. Right button is reserved for zooming and moving the canvas</p>
+ * 
+ * <p>In order to enable a <code>PreviewMouseListener</code>, annotate it with <code>ServiceProvider</code> annotation and implement <code>MouseResponsiveRenderer</code> 
+ * in a <code>Renderer</code> and return true for the listener in the <code>needsPreviewMouseListener</code> method.</p>
+ * @author Eduardo Ramos<eduramiba@gmail.com>
+ */
+public interface PreviewMouseListener {
+    
+    /**
+     * A single click event.
+     * @param event Mouse event
+     * @param properties Preview properties for the workspace
+     * @param workspace  Current workspace
+     */
+    public void mouseClicked(PreviewMouseEvent event, PreviewProperties properties, Workspace workspace);
+    
+    /**
+     * A mouse press event. If your listener needs to receive drag or release events, you <b>must</b> mark the previous press event as consumed.
+     * @param event Mouse event
+     * @param properties Preview properties for the workspace
+     * @param workspace  Current workspace
+     */
+    public void mousePressed(PreviewMouseEvent event, PreviewProperties properties, Workspace workspace);
+    
+    /**
+     * If your listener needs to receive drag events, you <b>must</b> mark the previous press event as consumed.
+     * @param event Mouse event
+     * @param properties Preview properties for the workspace
+     * @param workspace  Current workspace
+     */
+    public void mouseDragged(PreviewMouseEvent event, PreviewProperties properties, Workspace workspace);
+    
+    /**
+     * If your listener needs to receive release events, you <b>must</b> mark the previous press event as consumed.
+     * @param event Mouse event
+     * @param properties Preview properties for the workspace
+     * @param workspace  Current workspace
+     */
+    public void mouseReleased(PreviewMouseEvent event, PreviewProperties properties, Workspace workspace);
+}

modules/PreviewAPI/src/main/resources/org/gephi/preview/spi/package.html

@@ -1,62 +1,69 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
+<html>
-    <body bgcolor="white">
+    <body bgcolor="white">
-        Interfaces for creating new renderers, item builders and render targets.
+        Interfaces for creating new renderers, item builders and render targets.
-        <h3>Create a new Item Builder</h3>
+        <h3>Create a new Item Builder</h3>
-        <ol><li>Create a new module and set <code>Preview API</code>, 
+        <ol><li>Create a new module and set <code>Preview API</code>, 
-                <code>Graph API</code>, <code>AttributesAPI</code> and 
+                <code>Graph API</code>, <code>AttributesAPI</code> and 
-                <code>Lookup</code> as dependencies.</li>
+                <code>Lookup</code> as dependencies.</li>
-            <li>Create a new item class which implements <code>Item</code> or 
+            <li>Create a new item class which implements <code>Item</code> or 
-                extends <code>AbstractItem</code>. The <code>AbstractItem</code>
+                extends <code>AbstractItem</code>. The <code>AbstractItem</code>
-                class is located in the <code>PreviewPlugin</code> module so add
+                class is located in the <code>PreviewPlugin</code> module so add
-                it as dependency first. An item should be very simple but has a
+                it as dependency first. An item should be very simple but has a
-                unique identifier returned by its <code>getType()</code> method.</li>
+                unique identifier returned by its <code>getType()</code> method.</li>
-            <li>Create a new builder class that implements <code>ItemBuilder</code></li>
+            <li>Create a new builder class that implements <code>ItemBuilder</code></li>
-            <li>Implement the <code>getType()</code> method and returns the <b>same</b>
+            <li>Implement the <code>getType()</code> method and returns the <b>same</b>
-                identifier than the <code>Item</code> you created earlier.</li>
+                identifier than the <code>Item</code> you created earlier.</li>
-            <li>Implement the <code>getItems()</code> method by retrieving objects
+            <li>Implement the <code>getItems()</code> method by retrieving objects
-                from the given graph.</li>
+                from the given graph.</li>
-            <li>Add <b>@ServiceProvider</b> annotation to your builder, that it can
+            <li>Add <b>@ServiceProvider</b> annotation to your builder, that it can
-                be found by the system. Set <code>ItemBuilder</code> as the
+                be found by the system. Set <code>ItemBuilder</code> as the
-                annotation parameter.</li>
+                annotation parameter.</li>
-        </ol>
+        </ol>
-        <h3>Create a new Renderer</h3>
+        <h3>Create a new Renderer</h3>
-        <ol><li>Create a new module and set <code>Preview API</code>, 
+        <ol><li>Create a new module and set <code>Preview API</code>, 
-                <code>GraphAPI</code>, <code>Processing Wrapper</code>, 
+                <code>GraphAPI</code>, <code>Processing Wrapper</code>, 
-                <code>iText Wrapper</code> and <code>Lookup</code> as dependencies.</li>
+                <code>iText Wrapper</code> and <code>Lookup</code> as dependencies.</li>
-            <li>Create a new class that implements <code>Renderer</code>.</li>
+            <li>Create a new class that implements <code>Renderer</code>.</li>
-            <li>Implement the renderer methods. </li>
+            <li>Implement the renderer methods. </li>
-            <li>Add <b>@ServiceProvider</b> annotation to your builder, that it can
+            <li>Add <b>@ServiceProvider</b> annotation to your builder, that it can
-                be found by the system. Set <code>Renderer</code> as the
+                be found by the system. Set <code>Renderer</code> as the
-                annotation parameter.</li>
+                annotation parameter.</li>
-        </ol>
+        </ol>
-        <h3>Add data to an existing item</h3>
+        <h3>Add data to an existing item</h3>
-        To add an additional data attribute to a Node or Edge item, you need to create
+        To add an additional data attribute to a Node or Edge item, you need to create
-        a new item builder for the specific type. For instance if one want to add
+        a new item builder for the specific type. For instance if one want to add
-        a new attribute to nodes create a new <code>ItemBuilder</code> for the
+        a new attribute to nodes create a new <code>ItemBuilder</code> for the
-        type <code>Item.Node</code>. Simply return item objects with the data you
+        type <code>Item.Node</code>. Simply return item objects with the data you
-        want to add. The system will automatically merge your new data to node items.
+        want to add. The system will automatically merge your new data to node items.
-        <h3>Override a Renderer</h3>
+        <h3>Extend or replace an existing renderer</h3>
-        Default renderers can be completely replaced by custom implementations. The
+        <p>To extend or completely replace a default Renderer by your own implementation, 
-        implementation needs to customize its <code>@ServiceProvider</code> annotation
+        create a new Renderer and set the annotation like below. In addition add Preview Plugin module as a dependency.
-        with the renderer path it is overriding:
+        </p><p><code>
-        <ul>
+        @ServiceProvider(service=Renderer.class, position=XXX)
-            <li><pre>@ServiceProvider(service=Renderer.class, supersedes="org.gephi.preview.plugin.renderers.NodeRenderer")</pre></li>
+        public class MyRenderer extends NodeRenderer
-            <li><pre>@ServiceProvider(service=Renderer.class, supersedes="org.gephi.preview.plugin.renderers.EdgeRenderer")</pre></li>
+        </code>
-            <li><pre>@ServiceProvider(service=Renderer.class, supersedes="org.gephi.preview.plugin.renderers.NodeLabelRenderer")</pre></li>
+        </p><p>Being XXX the new position of the renderer
-            <li><pre>@ServiceProvider(service=Renderer.class, supersedes="org.gephi.preview.plugin.renderers.EdgeLabelRenderer")</pre></li>
+        Then you can reuse parts of the base class or just override them.
-            <li><pre>@ServiceProvider(service=Renderer.class, supersedes="org.gephi.preview.plugin.renderers.ArrowRenderer")</pre></li>
+        </p><p>Default renderers are:
-        </ul>
+        </p>
-        <h3>Add a new PreviewUI settings panel</h3>
+        <ul>
-        Plug-ins can add UI components to the Preview Settings module. Additional components are placed in new tabs and have access to the
+            <li> org.gephi.preview.plugin.renderers.NodeRenderer</li>
-        current <code>PreviewModel</code> and therefore <code>PreviewProperties</code>.
+            <li> org.gephi.preview.plugin.renderers.EdgeRenderer</li>
-        <ol><li>Create a new module and set <code>Preview API</code> and 
+            <li> org.gephi.preview.plugin.renderers.NodeLabelRenderer</li>
-                <code>Lookup</code> as dependencies.</li>
+            <li> org.gephi.preview.plugin.renderers.EdgeLabelRenderer</li>
-            <li>Create a new class that implements <code>PreviewUI</code> and implements
+            <li> org.gephi.preview.plugin.renderers.ArrowRenderer</li>
-                methods.</li>
+        </ul>
-            <li>Add <b>@ServiceProvider</b> annotation to your builder, that it can
+        <h3>Add a new PreviewUI settings panel</h3>
-                be found by the system. Set <code>PreviewUI</code> as the
+        Plug-ins can add UI components to the Preview Settings module. Additional components are placed in new tabs and have access to the
-                'service' annotation parameter.</li>
+        current <code>PreviewModel</code> and therefore <code>PreviewProperties</code>.
-        </ol>
+        <ol><li>Create a new module and set <code>Preview API</code> and 
-    </body>
+                <code>Lookup</code> as dependencies.</li>
+            <li>Create a new class that implements <code>PreviewUI</code> and implements
+                methods.</li>
+            <li>Add <b>@ServiceProvider</b> annotation to your builder, that it can
+                be found by the system. Set <code>PreviewUI</code> as the
+                'service' annotation parameter.</li>
+        </ol>
+    </body>
 </html>

src/main/javadoc/overview.html

@@ -19,6 +19,8 @@
         <h2>API Changes</h2>
 		<p>
         <ul>
+            <li>(December 07 2012) Add support for mouse listeners in Preview plugins. Create a <code>PreviewMouseListener</code> and implement <code>MouseResponsiveRenderer</code> interface in the renderers that use the listener.
+			</li>
 			<li>(April 10 2012) Add a <code>getShortDescription()</code> method to the <code>StatisticsUI</code> API. It enables to get a short description of statistics (used to display tooltips).
 			</li>
             <li>(March 26 2012) Add a <code>needsItemBuilder</code> method to <code>Renderer</code> in Preview API.