uci.gef
Class Editor

java.lang.Object
  |
  +--uci.gef.Editor

public class Editor

extends Object

implements Serializable, MouseListener, MouseMotionListener, KeyListener

This class provides an editor for manipulating graphical documents. The editor is the central class of the graph editing framework, but it does not contain very much code. It can be this small because all the net-level models, graphical objects, layers, editor modes, editor commands, and supporting dialogs and frames are implemented in their own classes.

An Editor's LayerManager has a stack of Layer's. Normally Layers contain Figs. Some Figs are linked to NetPrimitives. When Figs are selected the SelectionManager holds a Selection object. The behavior of the Editor is determined by its current Mode. The Editor's ModeManager keeps track of all the active Modes. Modes interpert user input events and decide how to change the state of the diagram. The Editor acts as a shell for executing Commands that modify the document or the Editor itself.

When Figs change visible state (e.g., color, size, or postition) they tell their Layer that they are damaged and need to be repainted. The Layer tells all Editors that are editing that Layer. Each Editor has a RedrawManager that keeps track of what parts of the screen need to be redrawn, and does the redraws asynchronously. A major goal of GEF is to make it easy to extend the framework for application to a specific domain. It is very important that new functionality can be added without modifying what is already there. The fairly small size of the Editor is a good indicator that it is not a bottleneck for enhancing the framework.

See Also:

Layer, Fig, NetPrimitive, Selection, Mode, Cmd, Serialized Form

Field Summary

protected FigTextEditor	_activeTextEditor Each Editor has a RedrawManager that executes in a separate thread of control to update damaged regions of the display.
protected Fig	_curFig The Fig that the mouse is in.
protected Selection	_curSel The Selection object that the mouse is in.
protected Object	_document This points to the document object that the user is working on.
protected Guide	_guide The grid to snap points to.
protected static Rectangle	_hitRect Temp var used to implement hit() without doing memory allocation.
protected LayerManager	_layerManager The LayerManager for this Editor.
protected ModeManager	_modeManager The user interface mode that the Editor is currently in.
protected SelectionManager	_selectionManager _selections holds the SelectionMultiple object that describes all the selection objects for what the user currently has selected.
static int	GRIP_SIZE Clicking exactly on a small shape is hard for users to do.

Constructor Summary

Editor()

Editor(Diagram d)

Editor(GraphModel gm)

Editor(GraphModel gm, Component awt_comp)
Construct a new Editor to edit the given NetList

Editor(GraphModel gm, Component awt_comp, Layer lay)

Method Summary

void	add(Fig f) Add a Fig to the diagram being edited.
void	addGraphSelectionListener(GraphSelectionListener listener) Remember to notify listener whenever the selection changes.
void	addModeChangeListener(ModeChangeListener listener) Remember to notify listener whenever the mode changes.
Object	clone() Clone the receiving editor.
Image	createImage(int w, int h) Create an Image (an off-screen bit-map) to be used to reduce flicker in redrawing.
void	damageAll() Mark the entire visible area of this Editor as damaged.
void	damaged(Fig f)
void	damaged(Rectangle r) Calling any one of the following damaged() methods adds a damaged region (rectangle) to this Editor's RedrawManager.
void	damaged(Selection sel)
protected void	defineLayers(GraphModel gm, Layer lay)
Object	document() Get and set document being edited.
void	document(Object d)
void	executeCmd(Cmd c, InputEvent ie) The editor acts as a shell for Cmds.
Enumeration	figs() Returns a collection of all Figs in the layer currently being edited.
Frame	findFrame() Find the AWT Frame that this Editor is being displayed in.
void	finishMode() Set this Editor's current Mode to the next global Mode.
Component	getAwtComponent()
Color	getBackground() Get the backgrund color of the Editor.
GraphEdgeRenderer	getGraphEdgeRenderer() Get the renderer object that decides how to display edges
Graphics	getGraphics() Get the graphics context object that this editor should draw on.
GraphModel	getGraphModel() Return the net under the diagram being edited.
GraphNodeRenderer	getGraphNodeRenderer() Get the renderer object that decides how to display nodes
Guide	getGuide()
LayerManager	getLayerManager() Return the LayerComposite that holds the diagram being edited.
ModeManager	getModeManager()
SelectionManager	getSelectionManager() Reply the current SelectionManager of this Editor.
Fig	hit(int x, int y)
Fig	hit(int x, int y, int w, int h)
Fig	hit(Point p) Reply the top Fig in the current layer that contains the given point.
Fig	hit(Rectangle r)
void	keyPressed(KeyEvent ke) Invoked when a key has been pressed.
void	keyReleased(KeyEvent ke) Invoked when a key has been released.
void	keyTyped(KeyEvent ke) Invoked when a key has been pressed and released.
void	mode(Mode m) Set the current user interface mode to the given Mode instance.
void	mouseClicked(MouseEvent me) Invoked after the mouse has been pressed and released.
void	mouseDragged(MouseEvent me) Invoked when a mouse button is pressed in the Editor and then dragged.
void	mouseEntered(MouseEvent me) Invoked when the mouse enters the Editor.
void	mouseExited(MouseEvent me) Invoked when the mouse exits the Editor.
void	mouseMoved(MouseEvent me) Invoked when the mouse button has been moved (with no buttons no down).
void	mousePressed(MouseEvent me) Invoked when a mouse button has been pressed.
void	mouseReleased(MouseEvent me) Invoked when a mouse button has been released.
void	paint(Graphics g) Paints the graphs nodes by calling paint() on layers, selections, and mode.
void	postLoad() Called after the Editor is loaded from a file.
void	postSave() Called after the Editor is saved to a file.
void	preSave() Called before the Editor is saved to a file.
void	print(Graphics g)
void	remove(Fig f) Remove a Fig from the diagram being edited.
void	removed(Fig f) The given Fig was removed from the diagram this Editor is showing.
void	removeGraphSelectionListener(GraphSelectionListener listener) Stop notifing listener of selection changes.
void	removeModeChangeListener(ModeChangeListener listener) Stop notifing listener of mode changes.
void	repairDamage() Tell my RedrawManager to repair all outstanding damaged regions now.
void	scrollToShow(int x, int y) Scroll the JGraph so that the given point is visible.
void	setActiveTextEditor(FigTextEditor fte)
void	setAwtComponent(Component c)
void	setCursor(Cursor c)
void	setGraphEdgeRenderer(GraphEdgeRenderer rend)
void	setGraphModel(GraphModel gm)
void	setGraphNodeRenderer(GraphNodeRenderer rend)
void	setGuide(Guide g)
protected void	setUnderMouse(MouseEvent me) Find the Fig under the mouse, and the node it represents, if any
void	snap(Point p) Modify the given point to be on the guideline (In this case, a gridline).

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GRIP_SIZE

public static final int GRIP_SIZE

Clicking exactly on a small shape is hard for users to do. GRIP_MARGIN gives them a chance to have the mouse outside a Fig by a few pixels and still hit it.

_modeManager

protected ModeManager _modeManager

The user interface mode that the Editor is currently in. Generally Modes that the user has to think about are a bad idea. But even in a very easy to use editor there are plenty of "spring-loaded" modes that change the way the system interperts input. For example, when placing a new node, the editor is in ModePlace, and when dragging a handle of an object the editor is in ModeModify. In each case moving or dragging the mouse has a different effect.

See Also:

ModeModify, ModeSelect, ModePlace

_document

protected Object _document

This points to the document object that the user is working on. At this point the framework does not have a very strong concept of document and there is no class Document. For now the meaning of this pointer is in the hands of the person applying this framework to an application.

_selectionManager

protected SelectionManager _selectionManager

_selections holds the SelectionMultiple object that describes all the selection objects for what the user currently has selected.

_layerManager

protected LayerManager _layerManager

The LayerManager for this Editor.

_guide

protected Guide _guide

The grid to snap points to.

_curFig

protected Fig _curFig

The Fig that the mouse is in.

_curSel

protected Selection _curSel

The Selection object that the mouse is in.

_activeTextEditor

protected transient FigTextEditor _activeTextEditor

Each Editor has a RedrawManager that executes in a separate thread of control to update damaged regions of the display.

_hitRect

protected static Rectangle _hitRect

Temp var used to implement hit() without doing memory allocation.

Constructor Detail

Editor

public Editor(GraphModel gm,
              Component awt_comp)

Construct a new Editor to edit the given NetList

Editor

public Editor(GraphModel gm)

Editor

public Editor()

Editor

public Editor(Diagram d)

Editor

public Editor(GraphModel gm,
              Component awt_comp,
              Layer lay)

Method Detail

defineLayers

protected void defineLayers(GraphModel gm,
                            Layer lay)

preSave

public void preSave()

Called before the Editor is saved to a file.

postSave

public void postSave()

Called after the Editor is saved to a file.

postLoad

public void postLoad()

Called after the Editor is loaded from a file.

clone

public Object clone()

Clone the receiving editor. Called from ActionSpawn. Subclasses of Editor should override this method.

Overrides:

clone in class Object

getModeManager

public ModeManager getModeManager()

mode

public void mode(Mode m)

Set the current user interface mode to the given Mode instance.

finishMode

public void finishMode()

Set this Editor's current Mode to the next global Mode.

getLayerManager

public LayerManager getLayerManager()

Return the LayerComposite that holds the diagram being edited.

getGraphModel

public GraphModel getGraphModel()

Return the net under the diagram being edited.

setGraphModel

public void setGraphModel(GraphModel gm)

getGraphNodeRenderer

public GraphNodeRenderer getGraphNodeRenderer()

Get the renderer object that decides how to display nodes

setGraphNodeRenderer

public void setGraphNodeRenderer(GraphNodeRenderer rend)

getGraphEdgeRenderer

public GraphEdgeRenderer getGraphEdgeRenderer()

Get the renderer object that decides how to display edges

setGraphEdgeRenderer

public void setGraphEdgeRenderer(GraphEdgeRenderer rend)

figs

public Enumeration figs()

Returns a collection of all Figs in the layer currently being edited.

add

public void add(Fig f)

Add a Fig to the diagram being edited.

remove

public void remove(Fig f)

Remove a Fig from the diagram being edited.

hit

public final Fig hit(Point p)

Reply the top Fig in the current layer that contains the given point. This is used in determining what the user clicked on, among other uses.

hit

public final Fig hit(int x,
                     int y)

hit

public final Fig hit(int x,
                     int y,
                     int w,
                     int h)

hit

public Fig hit(Rectangle r)

setUnderMouse

protected void setUnderMouse(MouseEvent me)

Find the Fig under the mouse, and the node it represents, if any

document

public Object document()

Get and set document being edited. There are no deep semantics here yet, a "document" is up to you to define.

document

public void document(Object d)

snap

public void snap(Point p)

Modify the given point to be on the guideline (In this case, a gridline).

getGuide

public Guide getGuide()

setGuide

public void setGuide(Guide g)

damaged

public void damaged(Rectangle r)

Calling any one of the following damaged() methods adds a damaged region (rectangle) to this Editor's RedrawManager.

damaged

public void damaged(Fig f)

damaged

public void damaged(Selection sel)

damageAll

public void damageAll()

Mark the entire visible area of this Editor as damaged. Currently called when a LayerGrid is adjusted. This will be useful for ActionRefresh if I get around to it. Also some Actions may perfer to do this instead of keeping track of all modified objects, but only in cases where most of the visible area is expected to change anyway.

repairDamage

public void repairDamage()

Tell my RedrawManager to repair all outstanding damaged regions now. Generally, you should not call this method explicitly. It already gets called periodically from another thread of control. You should call it if you need a very tight user interface feedback loop...

paint

public void paint(Graphics g)

Paints the graphs nodes by calling paint() on layers, selections, and mode. Whenever their is a change to the screen, this method will eventually be called from the RedrawManager.

See Also:

RedrawManager

print

public void print(Graphics g)

scrollToShow

public void scrollToShow(int x,
                         int y)

Scroll the JGraph so that the given point is visible. This is used when the user wants to drag an object a long distance. This is commented out right now because it causes too many out of memory errors and the size of the JGraphInternalPanel is not set properly.

getSelectionManager

public SelectionManager getSelectionManager()

Reply the current SelectionManager of this Editor.

getAwtComponent

public Component getAwtComponent()

setAwtComponent

public void setAwtComponent(Component c)

setActiveTextEditor

public void setActiveTextEditor(FigTextEditor fte)

setCursor

public void setCursor(Cursor c)

getGraphics

public Graphics getGraphics()

Get the graphics context object that this editor should draw on.

findFrame

public Frame findFrame()

Find the AWT Frame that this Editor is being displayed in. This is needed to open a dialog box.

createImage

public Image createImage(int w,
                         int h)

Create an Image (an off-screen bit-map) to be used to reduce flicker in redrawing.

getBackground

public Color getBackground()

Get the backgrund color of the Editor. Often, none of the background will be visible because LayerGrid covers the entire drawing area.

addGraphSelectionListener

public void addGraphSelectionListener(GraphSelectionListener listener)

Remember to notify listener whenever the selection changes.

removeGraphSelectionListener

public void removeGraphSelectionListener(GraphSelectionListener listener)

Stop notifing listener of selection changes.

addModeChangeListener

public void addModeChangeListener(ModeChangeListener listener)

Remember to notify listener whenever the mode changes.

removeModeChangeListener

public void removeModeChangeListener(ModeChangeListener listener)

Stop notifing listener of mode changes.

mouseClicked

public void mouseClicked(MouseEvent me)

Invoked after the mouse has been pressed and released. All events are passed on the SelectionManager and then ModeManager.

Specified by:

mouseClicked in interface MouseListener

mousePressed

public void mousePressed(MouseEvent me)

Invoked when a mouse button has been pressed.

Specified by:

mousePressed in interface MouseListener

mouseReleased

public void mouseReleased(MouseEvent me)

Invoked when a mouse button has been released.

Specified by:

mouseReleased in interface MouseListener

mouseEntered

public void mouseEntered(MouseEvent me)

Invoked when the mouse enters the Editor.

Specified by:

mouseEntered in interface MouseListener

mouseExited

public void mouseExited(MouseEvent me)

Invoked when the mouse exits the Editor.

Specified by:

mouseExited in interface MouseListener

mouseDragged

public void mouseDragged(MouseEvent me)

Invoked when a mouse button is pressed in the Editor and then dragged. Mouse drag events will continue to be delivered to the Editor where the first originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the Editor). BTW, this makes drag and drop editing almost impossible.

Specified by:

mouseDragged in interface MouseMotionListener

mouseMoved

public void mouseMoved(MouseEvent me)

Invoked when the mouse button has been moved (with no buttons no down).

Specified by:

mouseMoved in interface MouseMotionListener

keyTyped

public void keyTyped(KeyEvent ke)

Invoked when a key has been pressed and released. The KeyEvent has its keyChar ivar set to something, keyCode ivar is junk.

Specified by:

keyTyped in interface KeyListener

keyPressed

public void keyPressed(KeyEvent ke)

Invoked when a key has been pressed. The KeyEvent has its keyCode ivar set to something, keyChar ivar is junk.

Specified by:

keyPressed in interface KeyListener

keyReleased

public void keyReleased(KeyEvent ke)

Invoked when a key has been released. This is not very useful, so I ignore it.

Specified by:

keyReleased in interface KeyListener

executeCmd

public void executeCmd(Cmd c,
                       InputEvent ie)

The editor acts as a shell for Cmds. This method executes the given Cmd in response to the given event (some Cmds look at the Event that invoke them, even though this is discouraged). The Editor executes the Cmd in a safe environment so that buggy actions cannot crash the whole Editor.

removed

public void removed(Fig f)

The given Fig was removed from the diagram this Editor is showing. Now update the display.