android: comment selection related code, rearrange and clean-up

Change-Id: I18c8c4864d074662f85fc5b0e43eb84cc0638fd8

4 files changed, 167 insertions, 31 deletions

diff --git a/android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/GraphicSelection.java b/android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/GraphicSelection.java
index 4439badf2261..1a237a9fd29e 100644
--- a/android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/GraphicSelection.java
+++ b/android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/GraphicSelection.java
@@ -34,12 +34,17 @@ public class GraphicSelection implements CanvasElement {
     private GraphicSelectionHandle mHandles[] = new GraphicSelectionHandle[8];
     private GraphicSelectionHandle mDragHandle = null;
 
+    /**
+     * Construct the graphic selection.
+     */
     public GraphicSelection() {
+        // Create the paint, which is needed at drawing
         mPaint = new Paint();
         mPaint.setStyle(Paint.Style.STROKE);
         mPaint.setColor(Color.BLACK);
         mPaint.setStrokeWidth(2);
 
+        // Create the handles of the selection
         mHandles[0] = new GraphicSelectionHandle(HandlePosition.TOP_LEFT);
         mHandles[1] = new GraphicSelectionHandle(HandlePosition.TOP);
         mHandles[2] = new GraphicSelectionHandle(HandlePosition.TOP_RIGHT);
@@ -50,10 +55,15 @@ public class GraphicSelection implements CanvasElement {
         mHandles[7] = new GraphicSelectionHandle(HandlePosition.BOTTOM_RIGHT);
     }
 
+    /**
+     * Viewport has changed, reposition the selection to the new rectangle.
+     * @param scaledRectangle - rectangle of selection position on the document
+     */
     public void reposition(RectF scaledRectangle) {
         mScaledRectangle = scaledRectangle;
-        mDrawRectangle = scaledRectangle;
+        mDrawRectangle = scaledRectangle; // rectangle that will be draw
 
+        // reposition the handles too
         mHandles[0].reposition(scaledRectangle.left, scaledRectangle.top);
         mHandles[1].reposition(scaledRectangle.centerX(), scaledRectangle.top);
         mHandles[2].reposition(scaledRectangle.right, scaledRectangle.top);
@@ -64,6 +74,10 @@ public class GraphicSelection implements CanvasElement {
         mHandles[7].reposition(scaledRectangle.right, scaledRectangle.bottom);
     }
 
+    /**
+     * Hit test for the selection.
+     * @see org.libreoffice.canvas.CanvasElement#draw(android.graphics.Canvas)
+     */
     @Override
     public boolean contains(float x, float y) {
         // Check if handle was hit
@@ -76,6 +90,7 @@ public class GraphicSelection implements CanvasElement {
     }
 
     /**
+     * Draw the selection on the canvas.
      * @see org.libreoffice.canvas.CanvasElement#draw(android.graphics.Canvas)
      */
     @Override
@@ -86,6 +101,10 @@ public class GraphicSelection implements CanvasElement {
         }
     }
 
+    /**
+     * Dragging on the screen has started.
+     * @param position - position where the dragging started
+     */
     public void dragStart(PointF position) {
         mDragHandle = null;
         mType = DragType.NONE;
@@ -105,6 +124,10 @@ public class GraphicSelection implements CanvasElement {
         mStartDragPosition = position;
     }
 
+    /**
+     * Dragging is in process.
+     * @param position - position of the drag
+     */
     public void dragging(PointF position) {
         if (mType == DragType.MOVE) {
             float deltaX = position.x - mStartDragPosition.x;
@@ -117,6 +140,34 @@ public class GraphicSelection implements CanvasElement {
         }
     }
 
+    /**
+     * Dragging has ended.
+     * @param position - last position of the drag
+     */
+    public void dragEnd(PointF position) {
+        PointF point = new PointF();
+        if (mDragHandle != null) {
+            point.x = mDragHandle.mPosition.x;
+            point.y = mDragHandle.mPosition.y;
+            mDragHandle.reset();
+            mDragHandle = null;
+        } else {
+            point.x = mStartDragPosition.x;
+            point.y = mStartDragPosition.y;
+        }
+        float deltaX = position.x - mStartDragPosition.x;
+        float deltaY = position.y - mStartDragPosition.y;
+        point.offset(deltaX, deltaY);
+
+        sendGraphicSelectionEnd(point);
+
+        mDrawRectangle = mScaledRectangle;
+        mType = DragType.NONE;
+    }
+
+    /**
+     * Adapt the selection depending on which handle was dragged.
+     */
     private void adaptDrawRectangle(float x, float y) {
         mDrawRectangle = new RectF(mScaledRectangle);
         switch(mDragHandle.getHandlePosition()) {
@@ -151,43 +202,41 @@ public class GraphicSelection implements CanvasElement {
         }
     }
 
-    public void dragEnd(PointF position) {
-        PointF point = new PointF();
-        if (mDragHandle != null) {
-            point.x = mDragHandle.mPosition.x;
-            point.y = mDragHandle.mPosition.y;
-            mDragHandle.reset();
-            mDragHandle = null;
-        } else {
-            point.x = mStartDragPosition.x;
-            point.y = mStartDragPosition.y;
-        }
-        float deltaX = position.x - mStartDragPosition.x;
-        float deltaY = position.y - mStartDragPosition.y;
-        point.offset(deltaX, deltaY);
-
-        sendGraphicSelectionEnd(point);
-
-        mDrawRectangle = mScaledRectangle;
-        mType = DragType.NONE;
-    }
-
+    /**
+     * Send graphic selection start event to LOKitTread
+     * @param screenPosition - screen position of the selection
+     */
     private void sendGraphicSelectionStart(PointF screenPosition) {
-        LayerView layerView = LOKitShell.getLayerView();
-        if (layerView != null) {
-            PointF documentPoint = layerView.getLayerClient().convertViewPointToLayerPoint(screenPosition);
-            LOKitShell.sendTouchEvent("GraphicSelectionStart", documentPoint);
-        }
+        sendGraphicSelection("GraphicSelectionStart", screenPosition);
     }
 
+    /**
+     * Send graphic selection end event to LOKitTread
+     * @param screenPosition - screen position of the selection
+     */
     private void sendGraphicSelectionEnd(PointF screenPosition) {
+        sendGraphicSelection("GraphicSelectionEnd", screenPosition);
+    }
+
+    /**
+     * Send graphic selection event to LOKitTread
+     * @param type - type of the graphic selection
+     * @param screenPosition - screen position of the selection
+     */
+    private void sendGraphicSelection(String type, PointF screenPosition)
+    {
         LayerView layerView = LOKitShell.getLayerView();
         if (layerView != null) {
+            // Position is in screen coordinates. We need to convert them to
+            // document coordinates.
             PointF documentPoint = layerView.getLayerClient().convertViewPointToLayerPoint(screenPosition);
             LOKitShell.sendTouchEvent("GraphicSelectionEnd", documentPoint);
         }
     }
 
+    /**
+     * Reset the selection.
+     */
     public void reset() {
         mDragHandle = null;
         for (GraphicSelectionHandle handle : mHandles) {
@@ -195,6 +244,9 @@ public class GraphicSelection implements CanvasElement {
         }
     }
 
+    /**
+     * Type of the selection dragging.
+     */
     public enum DragType {
         NONE,
         MOVE,
diff --git a/android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/GraphicSelectionHandle.java b/android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/GraphicSelectionHandle.java
index a33589fa0698..52b662e4b80d 100644
--- a/android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/GraphicSelectionHandle.java
+++ b/android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/GraphicSelectionHandle.java
@@ -20,6 +20,11 @@ import android.graphics.RectF;
  * touched.
  */
 public class GraphicSelectionHandle implements CanvasElement {
+    /**
+     * The factor used to inflate the hit area.
+     */
+    private final float HIT_AREA_INFLATE_FACTOR = 1.75f;
+
     private final HandlePosition mHandlePosition;
     public PointF mPosition = new PointF();
     private float mRadius = 20.0f;
@@ -29,6 +34,10 @@ public class GraphicSelectionHandle implements CanvasElement {
     private RectF mHitRect = new RectF();
     private boolean mSelected = false;
 
+    /**
+     * Construct the handle - set the handle position on the selection.
+     * @param position - the handle position on the selection
+     */
     public GraphicSelectionHandle(HandlePosition position) {
         mHandlePosition = position;
 
@@ -43,11 +52,17 @@ public class GraphicSelectionHandle implements CanvasElement {
         mSelectedFillPaint.setColor(Color.BLUE);
     }
 
+    /**
+     * The position of the handle
+     * @return
+     */
     public HandlePosition getHandlePosition() {
         return mHandlePosition;
     }
 
     /**
+     * Draws the handle to the canvas.
+     *
      * @see org.libreoffice.canvas.CanvasElement#draw(android.graphics.Canvas)
      */
     @Override
@@ -59,33 +74,58 @@ public class GraphicSelectionHandle implements CanvasElement {
         }
     }
 
+    /**
+     * Draw a filled and stroked circle to the canvas
+     */
     private void drawFilledCircle(Canvas canvas, float x, float y, float radius, Paint strokePaint, Paint fillPaint) {
         canvas.drawCircle(x, y, radius, fillPaint);
         canvas.drawCircle(x, y, radius, strokePaint);
     }
 
+    /**
+     * Viewport has changed, reposition the handle to the input coordinates.
+     */
     public void reposition(float x, float y) {
         mPosition.x = x;
         mPosition.y = y;
-        mHitRect.left = mPosition.x - mRadius * 1.75f;
-        mHitRect.right = mPosition.x + mRadius * 1.75f;
-        mHitRect.top = mPosition.y - mRadius * 1.75f;
-        mHitRect.bottom = mPosition.y + mRadius * 1.75f;
+
+        // inflate the radius by HIT_AREA_INFLATE_FACTOR
+        float inflatedRadius = mRadius * HIT_AREA_INFLATE_FACTOR;
+
+        // reposition the hit area rectangle
+        mHitRect.left = mPosition.x - inflatedRadius;
+        mHitRect.right = mPosition.x + inflatedRadius;
+        mHitRect.top = mPosition.y - inflatedRadius;
+        mHitRect.bottom = mPosition.y + inflatedRadius;
     }
 
+    /**
+     * Hit test for the handle.
+     * @see org.libreoffice.canvas.CanvasElement#draw(android.graphics.Canvas)
+     */
     @Override
     public boolean contains(float x, float y) {
         return mHitRect.contains(x, y);
     }
 
+    /**
+     * Mark the handle as selected.
+     */
     public void select() {
         mSelected = true;
     }
 
+    /**
+     * Reset the selection for the handle.
+     */
     public void reset() {
         mSelected = false;
     }
 
+    /**
+     * All posible handle positions. The selection rectangle has 8 possible
+     * handles.
+     */
     public enum HandlePosition {
         TOP_LEFT,
         TOP,
diff --git a/android/experimental/LOAndroid3/src/java/org/libreoffice/overlay/TextCursorView.java b/android/experimental/LOAndroid3/src/java/org/libreoffice/overlay/TextCursorView.java
index 818dbc478131..af3237ea3bdb 100644
--- a/android/experimental/LOAndroid3/src/java/org/libreoffice/overlay/TextCursorView.java
+++ b/android/experimental/LOAndroid3/src/java/org/libreoffice/overlay/TextCursorView.java
@@ -95,6 +95,10 @@ public class TextCursorView extends View implements View.OnTouchListener {
         }
     }
 
+    /**
+     * Change the cursor position.
+     * @param position - new position of the cursor
+     */
     public void changeCursorPosition(RectF position) {
         LayerView layerView = LOKitShell.getLayerView();
         if (layerView == null) {
@@ -108,6 +112,10 @@ public class TextCursorView extends View implements View.OnTouchListener {
         repositionWithViewport(metrics.viewportRectLeft, metrics.viewportRectTop, metrics.zoomFactor);
     }
 
+    /**
+     * Change the text selection rectangles.
+     * @param selectionRects - list of text selection rectangles
+     */
     public void changeSelections(List<RectF> selectionRects) {
         LayerView layerView = LOKitShell.getLayerView();
         if (layerView == null) {
@@ -121,6 +129,10 @@ public class TextCursorView extends View implements View.OnTouchListener {
         repositionWithViewport(metrics.viewportRectLeft, metrics.viewportRectTop, metrics.zoomFactor);
     }
 
+    /**
+     * Change the graphic selection rectangle.
+     * @param rectangle - new graphic selection rectangle
+     */
     public void changeGraphicSelection(RectF rectangle) {
         LayerView layerView = LOKitShell.getLayerView();
         if (layerView == null) {
@@ -156,6 +168,9 @@ public class TextCursorView extends View implements View.OnTouchListener {
         return cursor;
     }
 
+    /**
+     * Drawing on canvas.
+     */
     @Override
     protected void onDraw(Canvas canvas) {
         super.onDraw(canvas);
@@ -172,6 +187,9 @@ public class TextCursorView extends View implements View.OnTouchListener {
         }
     }
 
+    /**
+     * Cursor animation function. Switch the alpha between opaque and fully transparent.
+     */
     private Runnable cursorAnimation = new Runnable() {
         public void run() {
             if (mCursorVisible) {
@@ -182,26 +200,41 @@ public class TextCursorView extends View implements View.OnTouchListener {
         }
     };
 
+    /**
+     * Show the cursor on the view.
+     */
     public void showCursor() {
         mCursorVisible = true;
         invalidate();
     }
 
+    /**
+     * Hide the cursor.
+     */
     public void hideCursor() {
         mCursorVisible = false;
         invalidate();
     }
 
+    /**
+     * Show text selection rectangles.
+     */
     public void showSelections() {
         mSelectionsVisible = true;
         invalidate();
     }
 
+    /**
+     * Hide text selection rectangles.
+     */
     public void hideSelections() {
         mSelectionsVisible = false;
         invalidate();
     }
 
+    /**
+     * Show the graphic selection on the view.
+     */
     public void showGraphicSelection() {
         mGraphicSelectionVisible = true;
         mGraphicSelectionMove = false;
@@ -209,11 +242,17 @@ public class TextCursorView extends View implements View.OnTouchListener {
         invalidate();
     }
 
+    /**
+     * Hide the graphic selection.
+     */
     public void hideGraphicSelection() {
         mGraphicSelectionVisible = false;
         invalidate();
     }
 
+    /**
+     * Handle the triggered touch event.
+     */
     @Override
     public boolean onTouch(View view, MotionEvent event) {
         switch (event.getActionMasked()) {
diff --git a/android/experimental/LOAndroid3/src/java/org/mozilla/gecko/TextSelection.java b/android/experimental/LOAndroid3/src/java/org/mozilla/gecko/TextSelection.java
index 52aa5554fb4b..7a07742239e0 100644
--- a/android/experimental/LOAndroid3/src/java/org/mozilla/gecko/TextSelection.java
+++ b/android/experimental/LOAndroid3/src/java/org/mozilla/gecko/TextSelection.java
@@ -33,6 +33,11 @@ public class TextSelection extends Layer {
     private float mViewTop;
     private float mViewZoom;
 
+    /**
+     * Construct the TextSelection. Context is needed to get the needed
+     * resources (views) to display all the handles and selections.
+     * @param context - the activity context
+     */
     public TextSelection(Activity context) {
         mStartHandle = (TextSelectionHandle) context.findViewById(R.id.start_handle);
         mMiddleHandle = (TextSelectionHandle) context.findViewById(R.id.middle_handle);