[longomatch] Refactor properties and add documentation



commit 8b728aa00174ae9515ba14c1cab424ae5966a04a
Author: Andoni Morales Alastruey <ylatuya gmail com>
Date:   Tue Apr 21 12:39:31 2015 +0200

    Refactor properties and add documentation

 LongoMatch.Drawing/Canvas.cs                  |   85 ++++++++++++++++++------
 LongoMatch.Drawing/Widgets/Blackboard.cs      |   87 +++++++++++++++++++++----
 LongoMatch.Drawing/Widgets/DashboardCanvas.cs |    2 +-
 LongoMatch.Drawing/Widgets/Timerule.cs        |    2 +-
 4 files changed, 138 insertions(+), 38 deletions(-)
---
diff --git a/LongoMatch.Drawing/Canvas.cs b/LongoMatch.Drawing/Canvas.cs
index 3c14a46..c629587 100644
--- a/LongoMatch.Drawing/Canvas.cs
+++ b/LongoMatch.Drawing/Canvas.cs
@@ -16,14 +16,12 @@
 //  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
 //
 using System;
-using System.Linq;
 using System.Collections.Generic;
-using LongoMatch.Core.Interfaces.Drawing;
-using LongoMatch.Core.Interfaces;
+using System.Linq;
 using LongoMatch.Core.Common;
+using LongoMatch.Core.Interfaces.Drawing;
 using LongoMatch.Core.Store.Drawables;
 using LongoMatch.Drawing.CanvasObjects;
-using LongoMatch.Drawing.CanvasObjects.Dashboard;
 
 namespace LongoMatch.Drawing
 {
@@ -64,7 +62,6 @@ namespace LongoMatch.Drawing
 
                protected virtual void Dispose (bool disposing)
                {
-                       // FIXME: Should we check if we are disposed already ?
                        IgnoreRedraws = true;
                        if (disposing) {
                                ClearObjects ();
@@ -132,7 +129,8 @@ namespace LongoMatch.Drawing
                }
 
                /// <summary>
-               /// Defines a clip region
+               /// Defines a clip region, any drawing outside this region
+               /// will not be drawn.
                /// </summary>
                protected Area ClipRegion {
                        get;
@@ -256,9 +254,6 @@ namespace LongoMatch.Drawing
        /// </summary>
        public class SelectionCanvas: Canvas
        {
-               protected bool moving, moved;
-               protected Point start;
-               protected CanvasObject highlighted;
 
                uint lastTime;
                Selection clickedSel;
@@ -346,6 +341,40 @@ namespace LongoMatch.Drawing
                }
 
                /// <summary>
+               /// The object that is currently highlited (mouse is over the object)
+               /// </summary>
+               public CanvasObject HighlightedObject {
+                       get;
+                       set;
+               }
+
+               /// <summary>
+               /// The start point from which the object was moved.
+               /// It can be used to determine the distance of the move action.
+               /// </summary>
+               public Point MoveStart {
+                       get;
+                       set;
+               }
+
+               /// <summary>
+               /// When set to <c>true</c> it indicates an object has been moved
+               /// between the clik pressed + mouse move + click released.
+               /// </summary>
+               public bool Moved {
+                       get;
+                       set;
+               }
+
+               /// <summary>
+               /// When set to <c>true</c> it indicates when in the middle of a move action.
+               /// </summary>
+               public bool Moving {
+                       get;
+                       set;
+               }
+
+               /// <summary>
                /// Called when the cursor is being moved.
                /// Highlights objects when the cursor passes over them. 
                /// </summary>
@@ -362,14 +391,14 @@ namespace LongoMatch.Drawing
                                current = sel.Drawable as CanvasObject;
                        }
 
-                       if (current != highlighted) {
-                               if (highlighted != null) {
-                                       highlighted.Highlighted = false;
+                       if (current != HighlightedObject) {
+                               if (HighlightedObject != null) {
+                                       HighlightedObject.Highlighted = false;
                                }
                                if (current != null) {
                                        current.Highlighted = true;
                                }
-                               highlighted = current;
+                               HighlightedObject = current;
                        }
                }
 
@@ -532,10 +561,10 @@ namespace LongoMatch.Drawing
                                }
                        } else {
                                ClearSelection ();
-                               start = coords;
+                               MoveStart = coords;
                                UpdateSelection (sel);
                                StartMove (sel);
-                               moving = Selections.Count > 0 && ObjectsCanMove;
+                               Moving = Selections.Count > 0 && ObjectsCanMove;
                        }
                }
 
@@ -554,27 +583,27 @@ namespace LongoMatch.Drawing
                        Point userCoords;
 
                        userCoords = ToUserCoords (coords);
-                       if (moving && Selections.Count != 0) {
+                       if (Moving && Selections.Count != 0) {
                                sel = Selections [0];
-                               sel.Drawable.Move (sel, userCoords, start);  
+                               sel.Drawable.Move (sel, userCoords, MoveStart);  
                                widget.ReDraw (sel.Drawable);
                                SelectionMoved (sel);
-                               moved = true;
+                               Moved = true;
                        } else {
                                CursorMoved (userCoords);
                        }
-                       start = ToUserCoords (coords);
+                       MoveStart = ToUserCoords (coords);
                }
 
                void HandleButtonReleasedEvent (Point coords, ButtonType type, ButtonModifier modifier)
                {
-                       moving = false;
+                       Moving = false;
                        if (clickedSel != null) {
                                (clickedSel.Drawable as ICanvasSelectableObject).ClickReleased ();
                                clickedSel = null;
                        }
-                       StopMove (moved);
-                       moved = false;
+                       StopMove (Moved);
+                       Moved = false;
                }
 
                void HandleButtonPressEvent (Point coords, uint time, ButtonType type, ButtonModifier 
modifier)
@@ -607,6 +636,10 @@ namespace LongoMatch.Drawing
                {
                }
 
+               /// <summary>
+               /// Sets the background image of the canvas.
+               /// This property is not optional
+               /// </summary>
                public Image Background {
                        set {
                                background = value;
@@ -617,6 +650,11 @@ namespace LongoMatch.Drawing
                        }
                }
 
+               /// <summary>
+               /// Defines an area with the region of interest, which can
+               /// be used to zoom into the canvas.
+               /// </summary>
+               /// <value>The region of interest.</value>
                public Area RegionOfInterest {
                        set {
                                regionOfInterest = value;
@@ -637,6 +675,7 @@ namespace LongoMatch.Drawing
                                double scaleX, scaleY;
                                Point translation;
 
+                               /* Add black borders to the canvas to keep the DAR of the background image */
                                background.ScaleFactor ((int)widget.Width, (int)widget.Height, out scaleX,
                                        out scaleY, out translation);
                                ClipRegion = new Area (new Point (translation.X, translation.Y),
@@ -644,6 +683,8 @@ namespace LongoMatch.Drawing
                                ScaleX = scaleX;
                                ScaleY = scaleY;
                                Translation = translation;
+
+                               /* If there is a region of interest set, combine the transformation */
                                if (RegionOfInterest != null) {
                                        ScaleX *= background.Width / RegionOfInterest.Width;
                                        ScaleY *= background.Height / RegionOfInterest.Height;
diff --git a/LongoMatch.Drawing/Widgets/Blackboard.cs b/LongoMatch.Drawing/Widgets/Blackboard.cs
index afb3b76..ef6d706 100644
--- a/LongoMatch.Drawing/Widgets/Blackboard.cs
+++ b/LongoMatch.Drawing/Widgets/Blackboard.cs
@@ -15,16 +15,21 @@
 //  along with this program; if not, write to the Free Software
 //  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
 //
+using System;
 using System.Linq;
 using LongoMatch.Core.Common;
 using LongoMatch.Core.Handlers;
 using LongoMatch.Core.Interfaces.Drawing;
 using LongoMatch.Core.Store;
 using LongoMatch.Core.Store.Drawables;
-using System;
 
 namespace LongoMatch.Drawing.Widgets
 {
+
+       /// <summary>
+       /// A canvas that can be used as a blackboard in which objects are drawn
+       /// over the image set in <see cref="BackgroundCanvas.Background"/>.
+       /// </summary>
        public class Blackboard: BackgroundCanvas
        {
        
@@ -62,6 +67,9 @@ namespace LongoMatch.Drawing.Widgets
                        base.Dispose (disposing);
                }
 
+               /// <summary>
+               /// Sets the frame drawings in the canvas.
+               /// </summary>
                public FrameDrawing Drawing {
                        set {
                                Clear (false);
@@ -82,41 +90,72 @@ namespace LongoMatch.Drawing.Widgets
                        }
                }
 
+               /// <summary>
+               /// Sets the color used for newly created objects or
+               /// changes it for the current selection.
+               /// </summary>
                public Color Color {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// Sets the text color used for newly created objects or
+               /// changes it for the current selection.
+               /// </summary>
                public Color TextColor {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// Sets the text background color used for newly created objects or
+               /// changes it for the current selection.
+               /// </summary>
                public Color TextBackgroundColor {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// Sets the font size used for newly created objects or
+               /// changes it for the current selection.
+               /// </summary>
                public int FontSize {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// Sets the line style used for newly created objects or
+               /// changes it for the current selection.
+               /// </summary>
                public LineStyle LineStyle {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// Sets the line type used for newly created objects or
+               /// changes it for the current selection.
+               /// </summary>
                public LineType LineType {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// Sets the line width used for newly created objects or
+               /// changes it for the current selection.
+               /// </summary>
                public int LineWidth {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// Changes the current drawing tool used.
+               /// </summary>
                public DrawTool Tool {
                        get {
                                return tool;
@@ -128,11 +167,17 @@ namespace LongoMatch.Drawing.Widgets
                        }
                }
 
+               /// <summary>
+               /// Sets the maximum zoom allowed
+               /// </summary>
                public double MaxZoom {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// Deletes the current selection from the frame drawing.
+               /// </summary>
                public void DeleteSelection ()
                {
                        foreach (ICanvasDrawableObject o in Selections.Select (s => s.Drawable)) {
@@ -144,6 +189,9 @@ namespace LongoMatch.Drawing.Widgets
                        widget.ReDraw ();
                }
 
+               /// <summary>
+               /// Clears the drawing.
+               /// </summary>
                public void Clear (bool resetDrawing = true)
                {
                        ClearSelection ();
@@ -162,6 +210,9 @@ namespace LongoMatch.Drawing.Widgets
                        widget.ReDraw ();
                }
 
+               /// <summary>
+               /// Saves the current canvas to an <see cref="Image"/>
+               /// </summary>
                public Image Save ()
                {
                        ClearSelection ();
@@ -169,6 +220,9 @@ namespace LongoMatch.Drawing.Widgets
                        return tk.Copy (this, Background.Width, Background.Height);
                }
 
+               /// <summary>
+               /// Saves the current canvas to a file
+               /// </summary>
                public void Save (string filename)
                {
                        Area area;
@@ -181,6 +235,11 @@ namespace LongoMatch.Drawing.Widgets
                        tk.Save (this, area, filename);
                }
 
+               /// <summary>
+               /// Zoom into the image and center it in the click.
+               /// </summary>
+               /// <param name="zoom">New zoom value.</param>
+               /// <param name="center">Mew image center.</param>
                public void Zoom (double zoom, Point center = null)
                {
                        Area roi;
@@ -248,33 +307,33 @@ namespace LongoMatch.Drawing.Widgets
                                
                        switch (Tool) {
                        case DrawTool.Line:
-                               drawable = new Line (start, new Point (start.X + 1, start.Y + 1),
+                               drawable = new Line (MoveStart, new Point (MoveStart.X + 1, MoveStart.Y + 1),
                                        LineType, LineStyle);
                                drawable.FillColor = Color;
                                pos = SelectionPosition.LineStop;
                                break;
                        case DrawTool.Cross:
-                               drawable = new Cross (start, new Point (start.X + 1, start.Y + 1),
+                               drawable = new Cross (MoveStart, new Point (MoveStart.X + 1, MoveStart.Y + 1),
                                        LineStyle);
                                break;
                        case DrawTool.Ellipse:
-                               drawable = new Ellipse (start, 2, 2);
+                               drawable = new Ellipse (MoveStart, 2, 2);
                                break;
                        case DrawTool.Rectangle:
-                               drawable = new Rectangle (start, 2, 2);
+                               drawable = new Rectangle (MoveStart, 2, 2);
                                break;
                        case DrawTool.CircleArea:
-                               drawable = new Ellipse (start, 2, 2);
+                               drawable = new Ellipse (MoveStart, 2, 2);
                                drawable.FillColor = Color.Copy ();
                                drawable.FillColor.A = byte.MaxValue / 2;
                                break;
                        case DrawTool.RectangleArea:
-                               drawable = new Rectangle (start, 2, 2);
+                               drawable = new Rectangle (MoveStart, 2, 2);
                                drawable.FillColor = Color.Copy ();
                                drawable.FillColor.A = byte.MaxValue / 2;
                                break;
                        case DrawTool.Counter:
-                               drawable = new Counter (start, 3 * LineWidth, 0);
+                               drawable = new Counter (MoveStart, 3 * LineWidth, 0);
                                drawable.FillColor = Color.Copy ();
                                (drawable as Counter).TextColor = Color.Grey2;
                                resize = false;
@@ -283,7 +342,7 @@ namespace LongoMatch.Drawing.Widgets
                        case DrawTool.Player:
                                {
                                        int width, heigth;
-                                       Text text = new Text (start, 1, 1, "");
+                                       Text text = new Text (MoveStart, 1, 1, "");
                                        if (ConfigureObjectEvent != null) {
                                                ConfigureObjectEvent (text, Tool);
                                        }
@@ -292,7 +351,7 @@ namespace LongoMatch.Drawing.Widgets
                                        }
                                        Config.DrawingToolkit.MeasureText (text.Value, out width, out heigth,
                                                Config.Style.Font, FontSize, FontWeight.Normal);
-                                       text.Update (new Point (start.X - width / 2, start.Y - heigth / 2),
+                                       text.Update (new Point (MoveStart.X - width / 2, MoveStart.Y - heigth 
/ 2),
                                                width, heigth);
                                        text.TextColor = TextColor.Copy ();
                                        text.FillColor = text.StrokeColor = TextBackgroundColor.Copy ();
@@ -306,7 +365,7 @@ namespace LongoMatch.Drawing.Widgets
                                handdrawing = true;
                                break;
                        case DrawTool.Zoom:
-                               Zoom (Math.Min (currentZoom + 0.1, MaxZoom), start);
+                               Zoom (Math.Min (currentZoom + 0.1, MaxZoom), MoveStart);
                                break;
                        }
 
@@ -388,7 +447,7 @@ namespace LongoMatch.Drawing.Widgets
                protected override void CursorMoved (Point coords)
                {
                        if (inZooming && RegionOfInterest != null) {
-                               Point diff = coords - start;
+                               Point diff = coords - MoveStart;
                                RegionOfInterest.Start -= diff;
                                ClipRoi (RegionOfInterest);
                                RegionOfInterest = RegionOfInterest;
@@ -405,7 +464,7 @@ namespace LongoMatch.Drawing.Widgets
                                        } else {
                                                tk.StrokeColor = tk.FillColor = Color;
                                        }
-                                       tk.DrawLine (start, coords);
+                                       tk.DrawLine (MoveStart, coords);
                                        tk.End ();
                                }
                                widget.ReDraw ();
@@ -413,7 +472,7 @@ namespace LongoMatch.Drawing.Widgets
                                base.CursorMoved (coords);
                                if (Tool == DrawTool.Selection) {
                                        DrawTool moveTool = currentZoom == 1 ? DrawTool.None : 
DrawTool.CanMove;
-                                       if (highlighted == null) {
+                                       if (HighlightedObject == null) {
                                                widget.SetCursorForTool (moveTool);
                                        } else {
                                                widget.SetCursorForTool (DrawTool.Selection);
diff --git a/LongoMatch.Drawing/Widgets/DashboardCanvas.cs b/LongoMatch.Drawing/Widgets/DashboardCanvas.cs
index 7424951..f2beb63 100644
--- a/LongoMatch.Drawing/Widgets/DashboardCanvas.cs
+++ b/LongoMatch.Drawing/Widgets/DashboardCanvas.cs
@@ -231,7 +231,7 @@ namespace LongoMatch.Drawing.Widgets
                                LinkAnchorObject anchor = null;
                                Selection destSel;
 
-                               destSel = GetSelection (start, true, true);
+                               destSel = GetSelection (MoveStart, true, true);
                                if (destSel != null && destSel.Drawable is LinkAnchorObject) { 
                                        anchor = destSel.Drawable as LinkAnchorObject;
                                }
diff --git a/LongoMatch.Drawing/Widgets/Timerule.cs b/LongoMatch.Drawing/Widgets/Timerule.cs
index a3aa25c..58a9c08 100644
--- a/LongoMatch.Drawing/Widgets/Timerule.cs
+++ b/LongoMatch.Drawing/Widgets/Timerule.cs
@@ -161,7 +161,7 @@ namespace LongoMatch.Drawing.Widgets
                        
                        /* Draw position triangle */
                        needle.TimelineHeight = height;
-                       if (!moving) {
+                       if (!Moving) {
                                tpos = Utils.TimeToPos (CurrentTime, SecondsPerPixel);
                                tpos -= Scroll;
                                needle.X = tpos;


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]