[Tynstep-svn] r99 - in trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client: service/eventbus service/refdata toolkit toolkit/scripture toolkit/timeline
ChrisBurrell at crosswire.org
ChrisBurrell at crosswire.org
Mon Mar 8 12:43:41 MST 2010
Author: ChrisBurrell
Date: 2010-03-08 12:43:41 -0700 (Mon, 08 Mar 2010)
New Revision: 99
Modified:
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/service/eventbus/StepEventBus.java
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/service/refdata/ModuleName.java
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/service/refdata/ModuleRefData.java
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/HasSource.java
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/HtmlList.java
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/SimpleListBox.java
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/SourceListBox.java
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/scripture/ScriptureDisplayConstants.java
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/scripture/VerseLabel.java
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/TimeEvent.java
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/TimeEventDescriptor.java
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/TimeScale.java
trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/Timeline.java
Log:
toolkit and service packages documented
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/service/eventbus/StepEventBus.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/service/eventbus/StepEventBus.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/service/eventbus/StepEventBus.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -1,14 +1,21 @@
package com.tyndalehouse.step.web.client.service.eventbus;
+import net.customware.gwt.presenter.client.DefaultEventBus;
+
import com.allen_sauer.gwt.log.client.Log;
import com.google.gwt.event.shared.GwtEvent;
-import net.customware.gwt.presenter.client.DefaultEventBus;
-
+/**
+ * Default Step event bus to be used. Provides extra logging and in flight
+ * monitoring capability later
+ *
+ * @author cjburrell
+ *
+ */
public class StepEventBus extends DefaultEventBus {
@Override
- public void fireEvent(GwtEvent<?> event) {
+ public void fireEvent(final GwtEvent<?> event) {
Log.debug("StepEventBus:: firing event " + event.toDebugString());
super.fireEvent(event);
}
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/service/refdata/ModuleName.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/service/refdata/ModuleName.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/service/refdata/ModuleName.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -1,12 +1,34 @@
package com.tyndalehouse.step.web.client.service.refdata;
+/**
+ * Bean representing a module and its direct parent (if there is a hierarchy
+ *
+ * @author cjburrell
+ *
+ */
public class ModuleName {
+ /**
+ * Module name
+ */
private String moduleName;
+
+ /**
+ * Parent if applicable of the module
+ */
private String parent;
+ /**
+ * Cosntructs a module with a given name and parent
+ *
+ * @param moduleName module name
+ * @param parent parent may be null
+ */
public ModuleName(final String moduleName, final String parent) {
this.moduleName = moduleName;
- this.parent = parent;
+
+ if (parent == null) {
+ this.parent = "Module";
+ }
}
/**
@@ -17,25 +39,23 @@
}
/**
- * @param moduleName
- * the moduleName to set
+ * @return the parent
*/
- public void setModuleName(String moduleName) {
- this.moduleName = moduleName;
+ public String getParent() {
+ return parent;
}
/**
- * @return the parent
+ * @param moduleName the moduleName to set
*/
- public String getParent() {
- return parent;
+ public void setModuleName(final String moduleName) {
+ this.moduleName = moduleName;
}
/**
- * @param parent
- * the parent to set
+ * @param parent the parent to set
*/
- public void setParent(String parent) {
+ public void setParent(final String parent) {
this.parent = parent;
}
}
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/service/refdata/ModuleRefData.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/service/refdata/ModuleRefData.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/service/refdata/ModuleRefData.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -3,19 +3,43 @@
import java.util.ArrayList;
import java.util.List;
-//TODO: internationalise
-public class ModuleRefData {
- private List<ModuleName> moduleNames;
- private final List<String> depths;
+//TODO: remove singleton pattern and use @Singleton and Gin instead.
+/**
+ * Client side service to serve the reference data to the user
+ */
+public final class ModuleRefData {
+ /**
+ * This class is a singleton, so this is the unique private instance
+ */
private static ModuleRefData instance;
/**
- * @return the depths
+ * @return the instance
*/
- public List<String> getDepths() {
- return depths;
+ public static synchronized ModuleRefData getInstance() {
+ if (instance == null) {
+ instance = new ModuleRefData();
+ }
+
+ return instance;
}
+ /**
+ * List of depths populating the Depth dropdown (level at which the user
+ * wants to see articles)
+ */
+ private final List<String> depths;
+
+ /**
+ * List of module names to be displayed in the drop downs
+ */
+ private final List<ModuleName> moduleNames;
+
+ /**
+ * Private constructor setting up all modules, and their hierarchies For
+ * e.g. People, Events and Eras come under History TODO: This needs
+ * internationalising
+ */
private ModuleRefData() {
moduleNames = new ArrayList<ModuleName>();
@@ -32,6 +56,7 @@
moduleNames.add(new ModuleName("Google Maps", "Geography"));
// Main modules
+ // TODO: tidy up and send to paremeter files
moduleNames.add(new ModuleName("History", "Module"));
moduleNames.add(new ModuleName("Geography", "Module"));
moduleNames.add(new ModuleName("Language", "Module"));
@@ -48,25 +73,27 @@
depths.add("Scholarly Details");
}
+ /**
+ * @return the depths
+ */
+ public List<String> getDepths() {
+ return depths;
+ }
+
+ /**
+ * Returns a list of modules given a parent module
+ *
+ * @param parentModule parent module, or "Module" if none
+ * @return the list of available modules
+ */
public List<String> getListOfModules(final String parentModule) {
- List<String> subset = new ArrayList<String>();
+ final List<String> subset = new ArrayList<String>();
- for (ModuleName mn : moduleNames) {
+ for (final ModuleName mn : moduleNames) {
if (mn.getParent().equals(parentModule)) {
subset.add(mn.getModuleName());
}
}
return subset;
}
-
- /**
- * @return the instance
- */
- public static synchronized ModuleRefData getInstance() {
- if (instance == null) {
- instance = new ModuleRefData();
- }
-
- return instance;
- }
}
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/HasSource.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/HasSource.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/HasSource.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -1,8 +1,24 @@
package com.tyndalehouse.step.web.client.toolkit;
+/**
+ * Indicates that the view (generally) has got a source, a dropdown list for
+ * e.g.) and can be set
+ *
+ * @author cjburrell
+ *
+ * @param <T> The type of data it is expecting
+ */
public interface HasSource<T> {
+ /**
+ * Clears the source, i.e. resets to an empty list
+ */
+ void clearSource();
+
+ /**
+ * Settings the data
+ *
+ * @param source source of the data
+ */
void setSource(T source);
- void clearSource();
-
}
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/HtmlList.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/HtmlList.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/HtmlList.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -10,31 +10,80 @@
import com.google.gwt.user.client.Event;
import com.google.gwt.user.client.ui.Widget;
+/**
+ * A HTML list, taken partially from the web This can be ordered or unordered
+ *
+ * @author cjburrell
+ */
public class HtmlList extends Widget {
- private final Map<Element, Command> listItems = new HashMap<Element, Command>();
-
+ /**
+ * Two types of list, ordered or undered
+ *
+ * @author cjburrell
+ *
+ */
public static enum ListType {
- UNORDERED {
+ /**
+ * An ordered list
+ */
+ ORDERED {
+ /**
+ * Creates an UL element on the DOM
+ *
+ * @return the element created
+ */
+ @Override
public Element createElement() {
- return Document.get().createULElement();
+ return Document.get().createOLElement();
}
},
- ORDERED {
+ /**
+ * An unordered list
+ */
+ UNORDERED {
+ /**
+ * Creates an UL element on the DOM
+ *
+ * @return the element created
+ */
+ @Override
public Element createElement() {
return Document.get().createULElement();
}
};
+ /**
+ * Creates an UL element on the DOM
+ *
+ * @return the element created
+ */
public abstract Element createElement();
}
- public HtmlList(ListType listType) {
+ /**
+ * list of items to be mapped in the list. And whether they should launch
+ * Commands on selected
+ */
+ private final Map<Element, Command> listItems = new HashMap<Element, Command>();
+
+ /**
+ * Constructor to create a HTML unordered or ordered list
+ *
+ * @param listType whether an ordered or unordered list should be created
+ */
+ public HtmlList(final ListType listType) {
setElement(listType.createElement());
setStylePrimaryName("html-list");
}
- public void addItem(String text, Command command) {
- LIElement liElement = Document.get().createLIElement();
+ /**
+ * Adds an item to the HtmlList
+ *
+ * @param text the text next to the bullet/numbered point
+ * @param command the command to be executed if a user clicks on it
+ */
+ public void addItem(final String text, final Command command) {
+ final LIElement liElement = Document.get().createLIElement();
liElement.setInnerText(text);
getElement().appendChild(liElement);
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/SimpleListBox.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/SimpleListBox.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/SimpleListBox.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -4,6 +4,13 @@
import com.google.gwt.user.client.ui.ListBox;
+/**
+ * An extension to the GWT ListBox, mainly to allow the setSource method
+ * exposure, and hide implementation details of the ListBox from the presenter
+ *
+ * @author cjburrell
+ *
+ */
public class SimpleListBox extends ListBox implements HasSource<List<String>> {
@Override
@@ -13,9 +20,9 @@
}
@Override
- public void setSource(List<String> source) {
+ public void setSource(final List<String> source) {
clearSource();
- for (String key : source) {
+ for (final String key : source) {
addItem(key);
}
}
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/SourceListBox.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/SourceListBox.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/SourceListBox.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -4,6 +4,12 @@
import com.google.gwt.user.client.ui.ListBox;
+/**
+ * Similar to @see {@link SimpleListBox}, but the source is given as a HashMap
+ *
+ * @author cjburrell
+ *
+ */
public class SourceListBox extends ListBox implements HasSource<SortedMap<String, String>> {
@Override
@@ -13,9 +19,9 @@
}
@Override
- public void setSource(SortedMap<String, String> source) {
+ public void setSource(final SortedMap<String, String> source) {
clearSource();
- for (String key : source.keySet()) {
+ for (final String key : source.keySet()) {
addItem(source.get(key), key);
}
}
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/scripture/ScriptureDisplayConstants.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/scripture/ScriptureDisplayConstants.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/scripture/ScriptureDisplayConstants.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -1,7 +1,22 @@
package com.tyndalehouse.step.web.client.toolkit.scripture;
-public class ScriptureDisplayConstants {
+/**
+ * Scripture display module constants
+ *
+ * @author cjburrell
+ *
+ */
+public final class ScriptureDisplayConstants {
+ /**
+ * To emphasis text in the module, for e.g. when a user clicks on a word
+ */
public static final String EMPHASISE = "scripture-emphasise";
+ /**
+ * making constructor private
+ */
+ private ScriptureDisplayConstants() {
+
+ }
}
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/scripture/VerseLabel.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/scripture/VerseLabel.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/scripture/VerseLabel.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -12,14 +12,54 @@
import com.google.gwt.user.client.ui.Label;
import com.tyndalehouse.step.web.client.event.LemmaClickedEvent;
+/**
+ * Composite wrapper around a portion of scriptural text. The wrapper contains
+ * data retrieved from the server such as lemmas (Strong numbers), morphological
+ * data and an alternative word in the case of an interlinear
+ *
+ * @author cjburrell
+ *
+ */
public class VerseLabel extends Composite {
+ /**
+ * if there is an interlinear, then this is where the alternative word is
+ * stored
+ */
+ private Label alternativeWord;
+
+ /**
+ * TODO: this should be removed into the presenter the event bus to fire off
+ * events
+ */
+ private final EventBus eventBus;
+
+ /**
+ * Flow panel for display
+ */
+ private final FlowPanel fp;
+
+ /**
+ * List of Strong numbers associated to this portion of text
+ */
private List<String> lemmas;
+
+ /**
+ * The main word(s) to be displayed
+ */
+ private final Label mainWord;
+
+ /**
+ * list of morphs associated to this wrapper of text
+ */
private List<String> morphs;
- private EventBus eventBus;
- private Label mainWord;
- private Label alternativeWord;
- private FlowPanel fp;
+ /**
+ * This constructors initialises an instance of the composite wrapper and
+ * sets up the panel, css, etc.
+ *
+ * @param text the text to be wrapped
+ * @param eventBus the event bus if events are to be fired
+ */
public VerseLabel(final String text, final EventBus eventBus) {
fp = new FlowPanel();
@@ -42,9 +82,32 @@
}
/**
- * @param lemma
- * the lemma to set
+ * @return the morph
*/
+ public List<String> getMorph() {
+ return morphs;
+ }
+
+ /**
+ * sets the alternative word. This could be a Hebrew word, but for a classic
+ * interlinear it could also be a English word, where the main word is the
+ * Hebrew
+ *
+ * @param originalWord an original word (for e.g. a hebrew translation)
+ */
+ public void setAlternativeWord(final String originalWord) {
+ if (alternativeWord != null) {
+ alternativeWord.setText(originalWord);
+ return;
+ }
+
+ alternativeWord = new Label(originalWord);
+ fp.add(alternativeWord);
+ }
+
+ /**
+ * @param lemma the lemma to set
+ */
public void setLemmas(final List<String> lemma) {
this.lemmas = lemma;
@@ -53,7 +116,7 @@
mainWord.addClickHandler(new ClickHandler() {
@Override
- public void onClick(ClickEvent event) {
+ public void onClick(final ClickEvent event) {
Log.error("Firing event");
eventBus.fireEvent(new LemmaClickedEvent(lemma));
}
@@ -62,27 +125,9 @@
}
/**
- * @return the morph
+ * @param morph the morph to set
*/
- public List<String> getMorph() {
- return morphs;
- }
-
- /**
- * @param morph
- * the morph to set
- */
- public void setMorphs(List<String> morph) {
+ public void setMorphs(final List<String> morph) {
this.morphs = morph;
}
-
- public void setAlternativeWord(final String originalWord) {
- if (alternativeWord != null) {
- alternativeWord.setText(originalWord);
- return;
- }
-
- alternativeWord = new Label(originalWord);
- fp.add(alternativeWord);
- }
}
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/TimeEvent.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/TimeEvent.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/TimeEvent.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -25,8 +25,14 @@
*/
private String description;
+ /**
+ * If this event is a duration, this captures the width to be displayed
+ */
private int durationWidth;
+ /**
+ * The master div containing all the relevant DOM elements representing it
+ */
private Element eventDiv;
/**
@@ -35,13 +41,29 @@
*/
private String eventType;
+ /**
+ * The picture if appropriate, displaying the type of event
+ */
private Element icon;
/**
* id of the event
*/
private int id;
+
+ /**
+ * whether the time event has been rendered on to the DOM yet
+ */
private boolean isRendered = false;
+
+ /**
+ * The label containing the text going with the event
+ */
private Element label;
+
+ /**
+ * The left-most position at which the event is located, in relation to the
+ * timeband
+ */
private int leftPixelPosition;
/**
* the end date of a duration event
@@ -59,8 +81,24 @@
*/
private boolean showText;
+ /**
+ * A representation of the total width occupied by the event, including the
+ * text next to it. This is particularly important for events that are
+ * single point in time, where the text will be much wider than the icon
+ *
+ */
private int totalWidth;
+ /**
+ * The
+ *
+ * @param id id of the event
+ * @param description a description to be displayed
+ * @param minDate a minimum date
+ * @param maxDate a maximum date, optional, in case of single point in time
+ * events
+ * @param tb the timeband
+ */
public TimeEvent(final int id, final String description, final Long minDate, final Long maxDate,
final Timeband tb) {
this.id = id;
@@ -72,14 +110,27 @@
setupEventSpecificOptions();
}
+ /*
+ * (non-Javadoc)
+ *
+ * @see java.lang.Object#equals(java.lang.Object)
+ */
@Override
public boolean equals(final Object obj) {
- if (obj == null || !(obj instanceof TimeEvent)) {
+ if (this == obj) {
+ return true;
+ }
+ if (obj == null) {
return false;
}
-
- final TimeEvent e = (TimeEvent) obj;
- return e.getId() == getId();
+ if (getClass() != obj.getClass()) {
+ return false;
+ }
+ final TimeEvent other = (TimeEvent) obj;
+ if (id != other.getId()) {
+ return false;
+ }
+ return true;
}
/**
@@ -140,6 +191,24 @@
return totalWidth;
}
+ /*
+ * (non-Javadoc)
+ *
+ * @see java.lang.Object#hashCode()
+ */
+ @Override
+ public int hashCode() {
+ final int prime = 31;
+ int result = 1;
+ result = prime * result + id;
+ return result;
+ }
+
+ /**
+ * returns whether this event is a duration or point in time event
+ *
+ * @return true if this is a duration event
+ */
public boolean isDuration() {
return maxDate == null;
}
@@ -160,6 +229,8 @@
/**
* the main responsible culprit for painting events on the timeband
+ *
+ * @param track the track on which the event will be painted
*/
public synchronized void paint(final TapeTrack track) {
// all we do is attach it to the parent if need be.
@@ -170,6 +241,9 @@
}
}
+ /**
+ * ensures the event gets rendered next time paint() is called
+ */
public void reset() {
isRendered = false;
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/TimeEventDescriptor.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/TimeEventDescriptor.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/TimeEventDescriptor.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -1,7 +1,5 @@
package com.tyndalehouse.step.web.client.toolkit.timeline;
-import java.util.HashMap;
-
import com.extjs.gxt.ui.client.core.El;
import com.google.gwt.event.dom.client.MouseEvent;
import com.google.gwt.user.client.DOM;
@@ -9,24 +7,37 @@
import com.tyndalehouse.step.web.client.toolkit.timeline.components.TimelineConstants;
/**
- * There is only one timeline descriptor for the timeline module. This shows
- * some content driven from the TimeEvent bean
+ * There is only one TimeEvent descriptor for the timeline module. This is the
+ * hover over the time event on the timeline module. For e.g. a user might over
+ * a point in time event, and get a description of what/when it represents
*
* @author cjburrell
*
*/
public class TimeEventDescriptor {
+
/**
- * Singleton-like pattern keyed on timeline object
+ * DOM Element containing the time event description
*/
- private static HashMap<Timeline, TimeEventDescriptor> descriptors = new HashMap<Timeline, TimeEventDescriptor>();
- private Element div;
- private El divWrapper;
+ private final Element div;
/**
- * private constructor initialising the descriptor
+ * a wrapper (div) around the main element
*/
- private TimeEventDescriptor(Timeline timeline) {
+ private final El divWrapper;
+
+ /**
+ * The timeline component on which to draw the popup
+ */
+ private final Timeline timeline;
+
+ /**
+ * public constructor initialising the descriptor
+ *
+ * @param timeline the timeline on which the popup is to be displayed
+ */
+ public TimeEventDescriptor(final Timeline timeline) {
+ this.timeline = timeline;
div = DOM.createDiv();
divWrapper = new El(div);
@@ -38,43 +49,34 @@
}
/**
- * No need to synchronise here, since javascript is single threaded
- *
- * @param te
- * TimeEvent is used to find the timeline div if need is to
- * initialise Could pass in timeline, but not need here...
+ * @return the divWrapper
*/
- private static TimeEventDescriptor instance(Timeline tl) {
- if (!descriptors.containsKey(tl)) {
- descriptors.put(tl, new TimeEventDescriptor(tl));
- }
- return descriptors.get(tl);
+ public El getDivWrapper() {
+ return divWrapper;
}
/**
+ * Hides the timeline
+ */
+ public void hide() {
+ getDivWrapper().setDisplayed(false);
+ }
+
+ /**
* Given a timed event, this shows the description in a div
*
- * @param te
+ * @param te the TimeEvent to be displayed
+ * @param me the mouse event that was triggered, contains details of pixel
+ * positions
*/
- public static void show(Timeline tl, TimeEvent te, MouseEvent me) {
- El divWrapper = instance(tl).getDivWrapper();
+ public void show(final TimeEvent te, final MouseEvent<?> me) {
+ final El divWrapper = getDivWrapper();
divWrapper.setInnerHtml(te.getId() + " - " + te.getDescription());
divWrapper.setDisplayed(true);
// Log.debug("x: " + me.getX());
// Log.debug("y: " + me.getY());
- divWrapper.setLeft(tl.getAbsoluteLeft() + me.getX());
- divWrapper.setTop(tl.getAbsoluteTop() + me.getY() - TimelineConstants.SPACE_BELOW_POPUP);
+ divWrapper.setLeft(timeline.getAbsoluteLeft() + me.getX());
+ divWrapper.setTop(timeline.getAbsoluteTop() + me.getY() - TimelineConstants.SPACE_BELOW_POPUP);
}
-
- public static void hide(Timeline tl) {
- instance(tl).getDivWrapper().setDisplayed(false);
- }
-
- /**
- * @return the divWrapper
- */
- public El getDivWrapper() {
- return divWrapper;
- }
}
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/TimeScale.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/TimeScale.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/TimeScale.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -8,16 +8,38 @@
import com.tyndalehouse.step.web.client.toolkit.timeline.helpers.TimeConversionUtil;
import com.tyndalehouse.step.web.shared.timeline.Unit;
+/**
+ * time scale, in charge of drawing the different columns on the timeband at
+ * various lengths, dependant on the uni of the timeband
+ *
+ * @author CJBurrell
+ *
+ */
public class TimeScale {
+ /**
+ * timeband on which the TimeScale resides
+ */
private final Timeband band;
+
+ /**
+ * true if time scale rendered
+ */
private boolean isRendered = false;
+
+ /**
+ * Maps of all timescales that have been drawn on the timeband
+ */
private final HashMap<Integer, Element> paintedTimescaleBands;
+
+ /**
+ * DOM element containing the scale columns
+ */
private Element scaleBand;
/**
* A timescale is attached to a timeband
*
- * @param band
+ * @param band timeband to attach the scale on
*/
public TimeScale(final Timeband band) {
this.band = band;
@@ -59,10 +81,20 @@
paint();
}
+ /**
+ * resets to redraw
+ */
public void reset() {
isRendered = false;
}
+ /**
+ * draws the segments on the TimeScale DOM element
+ *
+ * @param firstVisibleSegmentPixel first visible pixel, left most, of the
+ * band
+ * @param numberOfVisibleSegments number of segments to draw
+ */
private synchronized void drawSegments(final long firstVisibleSegmentPixel,
final long numberOfVisibleSegments) {
final El gxtScaleBand = new El(scaleBand);
@@ -96,13 +128,19 @@
gxtUn.setHeight("100%");
paintedTimescaleBands.put(key, un);
- } else {
- // Log.debug("Segment not drawn as already painted");
}
+ // else {
+ // TODO: log should come in next
+ // Log.debug("Segment not drawn as already painted");
+ // }
relativeLeft += pixelsPerUnit;
}
}
+ /**
+ * paints the visible segments (columns) on to the band This method mainly
+ * sets up all the relevant mathematics, and passes down
+ */
private void paintVisibleScale() {
final long visibleLeft = band.getMinVisibleDate();
final long visibleRight = band.getMaxVisibleDate();
Modified: trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/Timeline.java
===================================================================
--- trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/Timeline.java 2010-03-06 19:45:10 UTC (rev 98)
+++ trunk/step-web-app/src/main/java/com/tyndalehouse/step/web/client/toolkit/timeline/Timeline.java 2010-03-08 19:43:41 UTC (rev 99)
@@ -47,25 +47,69 @@
*
*/
public class Timeline extends Widget {
- private native static void disableSelection(Element e) /*-{
- e.ondrag = function() { return false; };
- e.onselectstart = function() { return false; };
- e.style.MozUserSelect = "none";
- }-*/;
+ /**
+ * Client X records the last X-axis mouse position
+ */
private int clientX;
+
+ /**
+ * Map of hover over popups that describe an event
+ */
+ private final TimeEventDescriptor descriptor;
+
+ /**
+ * keeps track of whether the mouse button is up or down
+ */
private boolean downStatus;
+
+ /**
+ * The event bus on which to fire events
+ */
private final EventBus eventBus;
+
+ /**
+ * the current height of the timeline module
+ */
private int height;
+
+ /**
+ * whether the timeline is displayed horizontally or vertically (vertically
+ * is not currently supported)
+ */
private boolean isHorizontal;
+
+ /**
+ * whether the timeline module has been rendered
+ */
private boolean isRendered = false;
+
+ /**
+ * The list of timebands
+ */
private final List<Timeband> timebands;
+ /**
+ * The container for the timeline module, a DOM element wrapping the whole
+ * lot this is for styling and makes it easier
+ */
private final Element timelineContainer;
+
+ /**
+ * the timeline div, in which everything gets done.
+ */
private final Element timelineDiv;
+ /**
+ * The current width of the timeline module when rendered
+ */
private int width;
+ /**
+ * Default constructor
+ *
+ * @param eventBus the event bus to fire events on
+ */
public Timeline(final EventBus eventBus) {
this.eventBus = eventBus;
timebands = new ArrayList<Timeband>();
@@ -77,11 +121,19 @@
timelineDiv.setClassName("step-timeline");
setElement(timelineDiv);
+ // set up hover over
+ descriptor = new TimeEventDescriptor(this);
+
paint();
addEventHandlers(eventBus);
disableSelection(getElement());
}
+ /**
+ * Adds a band to a timeline module
+ *
+ * @param band the timeband to be added
+ */
public synchronized void addBand(final Timeband band) {
timebands.add(band);
band.paint();
@@ -128,6 +180,14 @@
}
}
+ /**
+ * returns a band to the caller based on the band id
+ *
+ * @param bandId the band id of the band to be returned
+ * @return the relevant timeband
+ * @throws TimeBandNotFoundException thrown if bandId is not part of this
+ * timeline module
+ */
public Timeband getBand(final int bandId) throws TimeBandNotFoundException {
// do a linear search - we're not going to have lots of timebands
for (final Timeband t : timebands) {
@@ -139,14 +199,30 @@
throw new TimeBandNotFoundException("Timeband " + bandId + " was not found.");
}
+ /**
+ * Returns the number of bands to the caller
+ *
+ * @return the number of bands on the timeline module
+ */
public int getBandCount() {
return timebands.size();
}
+ /**
+ * returns the list of the timeband. This is rather dangerous, and probably
+ * should be protected
+ *
+ * @return the list of timebands
+ */
public List<Timeband> getBands() {
return timebands;
}
+ /**
+ * returns the stats for all timebands to the caller
+ *
+ * @return a list containing lots of @see {@link CurrentBandStats}
+ */
public List<CurrentBandStats> getCurrentBandStats() {
final List<CurrentBandStats> stats = new ArrayList<CurrentBandStats>();
for (final Timeband band : timebands) {
@@ -159,19 +235,6 @@
return stats;
}
- public Timeband getFiredBand(final MouseMoveEvent e) throws UnknownFiredElement {
- final EventTarget et = e.getNativeEvent().getEventTarget();
- final Element targetElement = et.cast();
-
- for (final Timeband b : timebands) {
- if (b.getBandDiv().isOrHasChild(targetElement)) {
- return b;
- }
- }
-
- throw new UnknownFiredElement();
- }
-
/**
* @return the height
*/
@@ -193,6 +256,12 @@
return width;
}
+ /**
+ * handles the mouse event, by alerting all the various bands to capture the
+ * position of the mouse on them
+ *
+ * @param e mouse event
+ */
public void handle(final MouseDownEvent e) {
downStatus = true;
clientX = e.getClientX();
@@ -210,13 +279,21 @@
// cursor: hand; /* ? */ TODO
}
+ /**
+ * handles a move of the mouse, Ensures we know what timeband has been fired
+ * then if the mouse is down, then tells timebands to move across else,
+ * perhaps we're mouse hovering over something, and a popup needs to be
+ * shown
+ *
+ * @param e the mouse move event
+ */
public void handle(final MouseMoveEvent e) {
if (timebands.size() != 0) {
Timeband firedBand;
try {
firedBand = getFiredBand(e);
} catch (final UnknownFiredElement e1) {
- Log.debug("Unknown element was fired");
+ Log.warn("Unknown element was fired");
firedBand = timebands.get(0);
}
@@ -250,26 +327,44 @@
// ignore if no timebands, as it is not fully rendered
}
+ /**
+ * Sets the down status to false, simulating a mouse up, recording whether
+ * the mouse is up or down, to false
+ *
+ * @param event mouse out event
+ */
public void handle(final MouseOutEvent event) {
downStatus = false;
}
+ /**
+ * on mouse over event, we call handleMouseOverTimeEvent to work out which
+ * TimeEvent fired the event if at all
+ *
+ * @param e mouse over event
+ */
public void handle(final MouseOverEvent e) {
handleMouseOverTimeEvent(e);
}
+ /**
+ * on mouse up, we set the down status to false, and update the mouse icon
+ *
+ * @param e mouse up event
+ */
public void handle(final MouseUpEvent e) {
downStatus = false;
new El(timelineDiv).setStyleName("step-letgo", true);
}
/**
- * An awful lot of events are going to fired and captured and discarded and
- * one wonders if this is really the best way to do it
+ * handles the display or remove of the popup An awful lot of events are
+ * going to fired and captured and discarded and one wonders if this is
+ * really the best way to do it
*
- * @param me
+ * @param e move over event
*/
- public void handleMouseOverTimeEvent(final MouseEvent e) {
+ public void handleMouseOverTimeEvent(final MouseEvent<?> e) {
final EventTarget et = e.getNativeEvent().getEventTarget();
final Element targetElement = et.cast();
@@ -281,14 +376,14 @@
if (te.getEventDiv().isOrHasChild(targetElement)) {
// Log.debug("Found event:" + te.getId() + " " +
// te.getDescription());
- TimeEventDescriptor.show(this, te, e);
+ this.descriptor.show(te, e);
return;
}
}
}
// if no events found, then hide description:
- TimeEventDescriptor.hide(this);
+ this.descriptor.hide();
}
/**
@@ -318,10 +413,22 @@
}
}
+ /**
+ * removes a band from the timeline
+ *
+ * @param bandId band id of the timeband to be removed
+ */
public void removeBand(final String bandId) {
timebands.remove(bandId);
}
+ /**
+ * Repaints a particular timeband
+ *
+ * @param originDate date at which to start
+ * @param unit unit to be used on the timeband
+ * @param timebandId the timeband id
+ */
public void repaint(final Long originDate, final Unit unit, final int timebandId) {
// remove all the timebands from the timeline widget
// TODO: HERE all we want to do is set the corect timeband with that
@@ -381,6 +488,11 @@
}
}
+ /**
+ * adds event handlers to capture mouse movements, clicks, etc
+ *
+ * @param eventBus event bus on which to register some handlers
+ */
// TODO: investigate pushing the handlers in to the handler!!!
private void addEventHandlers(final EventBus eventBus) {
final TimelineMouseHandler tmh = new TimelineMouseHandler(this);
@@ -409,6 +521,39 @@
}
/**
+ * Disables the user selection on the timeline widget, to ensure the user
+ * gets a good experience
+ *
+ * @param e the DOM element on which to perform these javascript operations
+ */
+ private native void disableSelection(final Element e) /*-{
+ e.ondrag = function() { return false; };
+ e.onselectstart = function() { return false; };
+ e.style.MozUserSelect = "none";
+ }-*/;
+
+ /**
+ * returns the fired timeband band, given a mouse move event
+ *
+ * @param e the mouse band
+ * @return the timeband that was fired
+ * @throws UnknownFiredElement thrown if we do not know which timeband was
+ * fired
+ */
+ private Timeband getFiredBand(final MouseMoveEvent e) throws UnknownFiredElement {
+ final EventTarget et = e.getNativeEvent().getEventTarget();
+ final Element targetElement = et.cast();
+
+ for (final Timeband b : timebands) {
+ if (b.getBandDiv().isOrHasChild(targetElement)) {
+ return b;
+ }
+ }
+
+ throw new UnknownFiredElement();
+ }
+
+ /**
* if the band corresponds to the correct timeband id, then set unit,
* otherwise revert back to the original state...
*
More information about the Tynstep-svn
mailing list