Changeset 780

Timestamp:

09/06/12 13:14:24 (12 years ago)

Author:

sherbold

Message:

• code documentation

Location:

trunk/quest-core-events/src/main/java/de/ugoe/cs/quest/eventcore

Files:

• IEventTarget.java (modified) (2 diffs)
• IEventType.java (modified) (2 diffs)
• gui/KeyInteractionSorter.java (modified) (4 diffs)

trunk/quest-core-events/src/main/java/de/ugoe/cs/quest/eventcore/IEventTarget.java

@@ +1 @@
+
 package de.ugoe.cs.quest.eventcore;
 
@@ -4 +5 @@
 
 /**
- * 
  * <p>
- * TODO comment
+ * Common interface for event targets. An event target can, e.g., be an element of a GUI or Web
+ * server. A concrete event-driven software platform can define its event targets through the
+ * implementation of this interface.
  * </p>
  * 
- * @version $Revision: $ $Date: Aug 16, 2012$
- * @author 2012, last modified by $Author: sherbold$
+ * @version 1.0
+ * @author Steffen Herbold
  */
 public interface IEventTarget extends Serializable {
 
+    /**
+     * <p>
+     * Returns the name of event-driven software platform to which the target belongs.
+     * </p>
+     * 
+     * @return name of the platform
+     */
     public String getPlatform();
-    
+
+    /**
+     * <p>
+     * Returns a string identifier of the target. This is very convenient for visualizations of
+     * events.
+     * </p>
+     * 
+     * @return target identifier
+     */
     public String getStringIdentifier();
 }

trunk/quest-core-events/src/main/java/de/ugoe/cs/quest/eventcore/IEventType.java

@@ +1 @@
+
 package de.ugoe.cs.quest.eventcore;
 
@@ -5 +6 @@
 /**
  * <p>
- * TODO comment
+ * Common interface for event types. An event type can be, e.g., a mouse click, a keyboard
+ * interactions in case of GUI platforms or a HTTP request in case of a Web application.
  * </p>
  * 
- * @version $Revision: $ $Date: Aug 16, 2012$
- * @author 2012, last modified by $Author: sherbold$
+ * @version 1.0
+ * @author Steffen Herbold
  */
 public interface IEventType extends Serializable {
 
     /**
-     * @return
+     * <p>
+     * Returns the name of the event type.
+     * </p>
+     * 
+     * @return name of the event type
      */
     public String getName();

trunk/quest-core-events/src/main/java/de/ugoe/cs/quest/eventcore/gui/KeyInteractionSorter.java

@@ -14 +14 @@
 
 /**
- * 
  * <p>
- * TODO comment
+ * This class provides the functionality to sort and clean up all key interactions in a log. In
+ * particular:
+ * <ol>
+ * <li>In case a combination key (e.g., shift, alt, control) is held down, multiple
+ * {@link KeyPressed} events are logged, even though only the first one is of importance. This class
+ * removes all {@link KeyPressed} events for combination keys except the first.</li>
+ * <li>In case a normal key is held down, multiple {@link KeyPressed} events are logged, but there
+ * is only one {@link KeyReleased} event. This class adds a {@link KeyReleased} event for all such
+ * {@link KeyPressed} events.</li>
+ * <li>Due to message filtering of applications, it is possible that a {@link KeyReleased} event
+ * without a preceding {@link KeyPressed} event is logged. This class either adds the missing
+ * {@link KeyPressed} right in front of the {@link KeyReleased} or removes the {@link KeyReleased}
+ * depending on the {@link #mode}.
+ * <li>As a result of steps 2-3, we have always a matching {@link KeyPressed}/{@link KeyReleased}
+ * pairs for all normal keys. This class replaces these pairs with a {@link KeyTyped} event at the
+ * position of the {@link KeyPressed} event.</li>
+ * <li>Sometimes combination keys are not released in the same order they have been pressed. This
+ * class ensures that the {@link KeyReleased} are in the opposite order of the {@link KeyPressed}
+ * events for all combination keys.</li>
+ * </ol>
  * </p>
  * 
- * @version $Revision: $ $Date: Sep 4, 2012$
- * @author 2012, last modified by $Author: sherbold$
+ * @version 1.0
+ * @author Steffen Herbold
  */
 public class KeyInteractionSorter {
@@ -29 +47 @@
      * </p>
      * 
-     * @version $Revision: $ $Date: Sep 3, 2012$
-     * @author 2012, last modified by $Author: sherbold$
+     * @version 1.0
+     * @author Steffen Herbold
      */
     public static enum CleanupMode {
-        REMOVAL, ADDITION
+        /**
+         * <p>
+         * Single {@link KeyReleased} are removed from the sequence.
+         * </p>
+         */
+        REMOVAL,
+
+        /**
+         * <p>
+         * {@link KeyPressed} events are added to single {@link KeyReleased} events
+         * </p>
+         */
+        ADDITION
     };
 
+    /**
+     * <p>
+     * 
+     * </p>
+     */
     private final CleanupMode mode;
 
+    /**
+     * <p>
+     * Constructor. Creates a new {@link KeyInteractionSorter} with {@link #mode}=
+     * {@link CleanupMode#ADDITION}.
+     * </p>
+     */
     public KeyInteractionSorter() {
         this(CleanupMode.ADDITION);
     }
 
+    /**
+     * <p>
+     * Constructor. Creates a new {@link KeyInteractionSorter}.
+     * </p>
+     * 
+     * @param mode
+     *            {@link #mode} of the instance
+     */
     public KeyInteractionSorter(CleanupMode mode) {
         this.mode = mode;
     }
 
+    /**
+     * <p>
+     * Sorts and cleans up key interactions according to the class specification (@see
+     * {@link KeyInteractionSorter} class comment).
+     * </p>
+     * <p>
+     * This method returns a sorted copy of a sequence, the sequence itself is not changed.
+     * </p>
+     * 
+     * @param sequence
+     *            sequence which is sorted
+     * @return sorted copy of sequence
+     */
     public List<Event> sortKeyInteractions(final List<Event> sequence) {
         List<Event> sortedSequence = new LinkedList<Event>(sequence);
@@ -55 +117 @@
     }
 
+    /**
+     * <p>
+     * Performs tasks 1-4 defined in the class description. Operations are performed in-place on the
+     * passed sequence.
+     * </p>
+     * 
+     * @param sequence
+     *            sequence which is sorted
+     */
     private void sortCombinationKeyPairs(List<Event> sequence) {
         LinkedList<VirtualKey> pressedCombinationKeys = new LinkedList<VirtualKey>();
@@ -99 +170 @@
     }
 
+    /**
+     * <p>
+     * Performs task 5 defined in the class description. Operations are performed in-place on the
+     * passed sequence.
+     * </p>
+     * 
+     * @param sequence
+     *            sequence which is sorted
+     */
     private void handleIncompleteKeyPairs(List<Event> sequence) {
         Set<VirtualKey> pressedKeys = new HashSet<VirtualKey>();