/*
 * @(#)DrawingEditor.java
 *
 * Copyright (c) 1996-2010 by the original authors of JHotDraw and all its
 * contributors. All rights reserved.
 *
 * You may not use, copy or modify this file, except in compliance with the 
 * license agreement you entered into with the copyright holders. For details
 * see accompanying license terms.
 */
package org.jhotdraw.draw;

import edu.umd.cs.findbugs.annotations.Nullable;
import org.jhotdraw.draw.tool.Tool;
import java.awt.*;
import java.beans.*;
import java.util.*;
import javax.swing.ActionMap;
import javax.swing.InputMap;

/**
 * A drawing editor coordinates drawing tools and drawing views.
 * 
 * 

Usage of drawing editor in conjunction with the JHotDraw application framework:

* *
* Design Patterns * *

Framework
* The following interfaces define the contracts of a framework for structured * drawing editors:
* Contract: {@link Drawing}, {@link Figure}, {@link DrawingView}, * {@link DrawingEditor}, {@link org.jhotdraw.draw.handle.Handle} and * {@link org.jhotdraw.draw.tool.Tool}. * *

Mediator
* {@code DrawingEditor} acts as a mediator for coordinating drawing tools * and drawing views:
* Mediator: {@link DrawingEditor}; Colleagues: {@link DrawingView}, * {@link org.jhotdraw.draw.tool.Tool}. * *

Mediator
* {@code DrawingEditor} acts as a mediator for coordinating keyboard input from * {@code Tool}s and Swing action objects:
* Mediator: {@link DrawingEditor}; Colleagues: * {@link org.jhotdraw.draw.tool.Tool}, javax.swing.Action. * *

Model-View-Controller
* The following classes implement together the Model-View-Controller design * pattern:
* Model: {@link Drawing}; View: {@link DrawingView}; Controller: * {@link DrawingEditor}. * *

Observer
* State changes of tools can be observed by other objects. Specifically * {@code DrawingEditor} observes area invalidations of tools and repaints * its active drawing view accordingly.
* Subject: {@link Tool}; * Observer: {@link org.jhotdraw.draw.event.ToolListener}; Event: * {@link org.jhotdraw.draw.event.ToolEvent}; Concrete Observer: {@link DrawingEditor}. * *

Proxy
* To remove the need for null-handling, {@code AbstractTool} makes use of * a proxy for {@code DrawingEditor}.
* Subject: {@link DrawingEditor}; Proxy: {@link DrawingEditorProxy}; * Client: {@link org.jhotdraw.draw.tool.AbstractTool}. *


* * @author Werner Randelshofer * @version $Id: DrawingEditor.java 717 2010-11-21 12:30:57Z rawcoder $ */ public interface DrawingEditor { /** * The property name for the active view property. */ public final static String ACTIVE_VIEW_PROPERTY = "activeView"; /** * The property name for the active tool property. */ public final static String TOOL_PROPERTY = "tool"; /** * The property name for the input map property. */ public final static String INPUT_MAP_PROPERTY = "inputMap"; /** * The property name for the action map property. */ public final static String ACTION_MAP_PROPERTY = "actionMap"; /** * The prefix for default attribute property changes. */ public final static String DEFAULT_ATTRIBUTE_PROPERTY_PREFIX = "defaultAttribute."; /** * Gets the editor's current drawing. * / Drawing getDrawing(); /** * Sets the editor's current drawing. * / void setDrawing(Drawing drawing); */ /** * Adds a drawing view to the editor. * The editor invokes addNotify on the view, and it registers its tool * as an event listener on the view. */ void add(DrawingView view); /** * Removes a drawing view from the editor. * The editor invokes removeNotify on the view, and it unregisters its tool * on the view. */ void remove(DrawingView view); /** * Gets all drawing views associated with this editor. */ Collection getDrawingViews(); /** * Gets the editor's active drawing view. * This can be null, if the editor has no views. */ @Nullable DrawingView getActiveView(); /** * Sets the editor's active drawing view. * This can be set to null, if the editor has no views. */ void setActiveView(@Nullable DrawingView newValue); /** * Calls deactivate on the previously active tool of this drawing editor. * Calls activate on the provided tool. * Forwards all mouse, mouse moation and keyboard events that occur on the * DrawingView to the provided tool. *

* This is a bound property. */ void setTool(Tool t); /** * Gets the current tool. *

* This is a bound property. */ Tool getTool(); /** * Sets the cursor on the view(s) of the drawing editor. */ void setCursor(Cursor c); /** * Finds a drawing view. * This is used by Tool to identify the view of which it has received * an event. */ @Nullable public DrawingView findView(Container c); /** * Sets a default attribute of the editor. * The default attribute will be used by creation tools, to create a new * figure. *

* Fires a property change event with the name of the attribute key, * and the prefix {@code "defaultAttribute."}. */ public void setDefaultAttribute(AttributeKey key, @Nullable T value); /** * Gets a default attribute from the editor. * The default attribute will be used by creation tools, to create a new * figure. */ @Nullable public T getDefaultAttribute(AttributeKey key); /** * Applies the default attributes to the specified figure. */ public void applyDefaultAttributesTo(Figure f); /** * Returns an immutable Map with the default attributes of this editor. */ public Map getDefaultAttributes(); /** * Sets a handle attribute of the editor. * The default attribute will be used by creation tools, to create a new * figure. * * @param key AttributeKey. * @param value Attribute value. */ public void setHandleAttribute(AttributeKey key, T value); /** * Gets a handle attribute from the editor. * The default attribute will be used by creation tools, to create a new * figure. * * @param key AttributeKey. * * @return If the handle attribute has been set, returns the previously * set value. If the handle attribute has not been set, returns key.getDefaultValue(). */ public T getHandleAttribute(AttributeKey key); /** * Sets the input map used by the tool of this drawing editor as a fall back * for handling keyboard events. *

* This is a bound property. */ public void setInputMap(InputMap newValue); /** * Sets the input map used by the tool of this drawing editor as a fall back * for handling keyboard events. *

* {@code Tool}s use the input map of the drawing editor to determine what * to do when a key was pressed that the tool can not handle. *

* This is a bound property. */ public InputMap getInputMap(); /** * Sets the action map used by the tool of this drawing editor as a fall back * for performing actions. *

* This is a bound property. */ public void setActionMap(ActionMap newValue); /** * Gets the action map used by the tool of this drawing editor as a fall back * for performing actions. *

* {@code Tool}s use the action map of the drawing editor to determine what * to do when an action needs to be invoked from the InputMap of the * drawing editor. *

* This is a bound property. */ public ActionMap getActionMap(); /** * Sets the enabled state of the drawing editor. * This is a bound property. */ public void setEnabled(boolean newValue); /** * Gets the enabled state of the drawing editor. */ public boolean isEnabled(); /** * Adds a {@code PropertyChangeListener}. * @param listener */ public void addPropertyChangeListener(PropertyChangeListener listener); /** * Removes a {@code PropertyChangeListener}. * @param listener */ public void removePropertyChangeListener(PropertyChangeListener listener); }

Ads help maintain this website.