/*******************************************************************************
* Copyright (c) 2003, 2010, 2012 IBM Corporation, Gerhardt Informatics Kft. and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
* Gerhardt Informatics Kft. - GEFGWT port
*******************************************************************************/
package org.eclipse.gef.rulers;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import org.eclipse.gef.GraphicalViewer;
import org.eclipse.gef.commands.Command;
import org.eclipse.gef.commands.UnexecutableCommand;
import org.eclipse.gef.internal.GEFMessages;
import org.eclipse.swt.accessibility.AccessibleControlEvent;
import org.eclipse.swt.accessibility.AccessibleEvent;
import com.google.gwt.user.client.rpc.GwtTransient;
/**
* This class provides an interface to interact with the ruler/guide feature
* provided in GEF. A <code>RulerProvider</code> represents a ruler (and the
* guides contained within), and provides the necessary information about them.
* <p>
* Clients wishing to utilize this GEF feature should do the following:
* <ul>
* <li>Extend this class and override the necessary methods. Also provide a
* notification mechanism to notify registered <code>RulerChangeListener</code>s
* of changes in ruler properties.</li>
* <li>Set instances of that class as properties on the diagram's graphical
* viewer (PROPERTY_HORIZONTAL_RULER and/or PROPERTY_VERTICAL_RULER)</li>
* <li>Set PROPERTY_RULER_VISIBILITY to be <code>true</code> on the graphical
* viewer.</li>
* </ul>
*
* @author Pratik Shah
* @since 3.0
*/
public abstract class RulerProvider {
/**
* The following property should be set on the graphical viewer.
* PROPERTY_HORIZONTAL_RULER should have a RulerProvider as its value.
*/
public static final String PROPERTY_HORIZONTAL_RULER = "horizontal ruler"; //$NON-NLS-1$
/**
* The following property should be set on the graphical viewer.
* PROPERTY_RULER_VISIBILITY should have a Boolean value.
*/
public static final String PROPERTY_RULER_VISIBILITY = "ruler$visibility"; //$NON-NLS-1$
/**
* The following property should be set on the graphical viewer.
* PROPERTY_VERTICAL_RULER should have a RulerProvider as its value.
*/
public static final String PROPERTY_VERTICAL_RULER = "vertical ruler"; //$NON-NLS-1$
/**
* Constant indicating that the ruler should display centimeters. Note that
* this setting does not affect how a guide's position is interpreted (it is
* always taken as pixels).
*/
public static final int UNIT_CENTIMETERS = 1;
/**
* Constant indicating that the ruler should display inches. Note that this
* setting does not affect how a guide's position is interpreted (it is
* always taken as pixels).
*/
public static final int UNIT_INCHES = 0;
/**
* Constant indicating that the ruler should display pixel count.
*/
public static final int UNIT_PIXELS = 2;
/**
* A list of <code>RulerChangeListener</code>s that have to be notified of
* changes in ruler/guide properties.
*/
@GwtTransient
protected List listeners = new ArrayList();
/**
* The given listener will be notified of changes in ruler properties.
*
* @param listener
* the listener that is to be notified of changes in ruler
* properties
*/
public void addRulerChangeListener(RulerChangeListener listener) {
if (!listeners.contains(listener))
listeners.add(listener);
}
/**
* Return the description of the control or specified child in the
* <code>result</code> field of the event object. Returning an empty string
* tells the client that the control or child does not have a description,
* and returning null tells the client to use the platform description.
*
* @param e
* AccessibleEvent
* @param guide
* The guide whose accessibility information is requested
* @see org.eclipse.swt.accessibility.AccessibleAdapter#getDescription(AccessibleEvent)
*/
public void getAccGuideDescription(AccessibleEvent e, Object guide) {
e.result = GEFMessages.Guide_Desc;
}
/**
* Return the given guide's name/label in the <code>result</code> field of
* the given event.
*
* @param e
* AccessibleEvent
* @param guide
* The guide whose accessibility information is requested
* @see org.eclipse.swt.accessibility.AccessibleAdapter#getName(AccessibleEvent)
*/
public void getAccGuideName(AccessibleEvent e, Object guide) {
e.result = GEFMessages.Guide_Label;
}
/**
* Return the guide's position in the <code>result</code> field of the given
* event.
*
* @param e
* AccessibleEvent
* @param guide
* The guide whose accessibility information is requested
* @see org.eclipse.swt.accessibility.AccessibleControlAdapter#getValue(AccessibleControlEvent)
*/
public void getAccGuideValue(AccessibleControlEvent e, Object guide) {
e.result = "" + getGuidePosition(guide); //$NON-NLS-1$
}
/**
* Returns a List of model objects that are attached to the given guide.
*
* @param guide
* the guide to which the model parts are attached.
* @return list of attached model objects
*/
public List getAttachedModelObjects(Object guide) {
return Collections.EMPTY_LIST;
}
/**
* Returns a List of EditParts that are attached to the given guide.
*
* @param guide
* the guide to which the EditParts are attached.
* @param viewer
* the GraphicalViewer in which these EditParts are shown.
* @return list of attached edit parts
*/
public List getAttachedEditParts(Object guide, GraphicalViewer viewer) {
List attachedModelObjects = getAttachedModelObjects(guide);
List attachedEditParts = new ArrayList(attachedModelObjects.size());
Iterator i = attachedModelObjects.iterator();
while (i.hasNext()) {
Object editPart = viewer.getEditPartRegistry().get(i.next());
if (editPart != null)
attachedEditParts.add(editPart);
}
return attachedEditParts;
}
/**
* Clients should override this method to return a Command to create a new
* guide at the given position.
*
* @param position
* The pixel position where the new guide is to be created
* @return UnexecutableCommand
*/
public Command getCreateGuideCommand(int position) {
return UnexecutableCommand.INSTANCE;
}
/**
* Clients should override this method to return a Command to delete the
* given guide.
*
* @param guide
* The guide that is to be deleted
* @return UnexecutableCommand
*/
public Command getDeleteGuideCommand(Object guide) {
return UnexecutableCommand.INSTANCE;
}
/**
* In most cases, there should be no need for clients to override this
* method.
*
* @param position
* The position of the guide that is to be found
* @return The guide object at the given position; <code>null</code> if no
* guide exists at the given position
*/
public Object getGuideAt(int position) {
List guides = getGuides();
for (int i = 0; i < guides.size(); i++) {
Object guide = guides.get(i);
if (position == getGuidePosition(guide)) {
return guide;
}
}
return null;
}
/**
* Clients should override this method to return a Command to move the given
* guide by the given amount.
*
* @param guide
* The guide that is to be moved
* @param positionDelta
* The amount by which the guide is to be moved
* @return UnexecutableCommand
*/
public Command getMoveGuideCommand(Object guide, int positionDelta) {
return UnexecutableCommand.INSTANCE;
}
/**
* Clients should override this method to return a list of all the guides
* set on this ruler.
*
* @return an empty list
*/
public List getGuides() {
return Collections.EMPTY_LIST;
}
/**
* Clients should override this method to return an array of all the
* positions of all the guides on this ruler.
*
* @return an empty array
*/
public int[] getGuidePositions() {
return new int[0];
}
/**
* Clients should override this method to return the position (in pixels) of
* the given guide.
*
* @param guide
* The guide whose position is to be determined
* @return <code>Integer.MIN_VALUE</code>
*/
public int getGuidePosition(Object guide) {
return Integer.MIN_VALUE;
}
/**
* Clients should override this method to return a model representation of
* the ruler.
*
* @return <code>null</code>
*/
public Object getRuler() {
return null;
}
/**
* Clients should override this method to return the units that the ruler
* should display: one of UNIT_INCHES, UNIT_CENTIMETERS, UNIT_PIXELS.
*
* @return UNIT_INCHES
*/
public int getUnit() {
return UNIT_INCHES;
}
/**
* The given listener will not be notified of changes in the ruler anymore.
*
* @param listener
* the listener that is to be removed
*/
public void removeRulerChangeListener(RulerChangeListener listener) {
listeners.remove(listener);
}
/**
* This method will be invoked when the user requests that the ruler display
* a different measurement. The default implementation ignores the user's
* request.
*
* @param newUnit
* the new unit of measurement; will be one of
* {@link #UNIT_CENTIMETERS}, {@link #UNIT_INCHES}, or
* {@link #UNIT_PIXELS}
*/
public void setUnit(int newUnit) {
}
}