[longomatch] Document Canvas and cleanup API



commit 496f9b27ce9f9d881c857cf1d873571f13f51215
Author: Andoni Morales Alastruey <ylatuya gmail com>
Date:   Mon Apr 13 11:55:58 2015 +0200

    Document Canvas and cleanup API

 LongoMatch.Drawing/Canvas.cs                     |  170 +++++++++++++++++++---
 LongoMatch.Drawing/CanvasObjects/ButtonObject.cs |   30 ++--
 LongoMatch.Drawing/Widgets/Blackboard.cs         |    2 +-
 LongoMatch.Drawing/Widgets/DashboardCanvas.cs    |   17 ++-
 4 files changed, 176 insertions(+), 43 deletions(-)
---
diff --git a/LongoMatch.Drawing/Canvas.cs b/LongoMatch.Drawing/Canvas.cs
index 530d3ef..3d44b7c 100644
--- a/LongoMatch.Drawing/Canvas.cs
+++ b/LongoMatch.Drawing/Canvas.cs
@@ -26,13 +26,13 @@ using LongoMatch.Drawing.CanvasObjects;
 
 namespace LongoMatch.Drawing
 {
+       /// <summary>
+       /// A canvas stores <see cref="ICanvasObjects"/>'s and draws them.
+       /// </summary>
        public class Canvas: ICanvas
        {
                protected IDrawingToolkit tk;
                protected IWidget widget;
-               protected double scaleX, scaleY;
-               protected Point translation;
-               protected bool ignoreRedraws;
                bool disposed;
 
                public Canvas (IWidget widget)
@@ -42,9 +42,9 @@ namespace LongoMatch.Drawing
                        Objects = new List<ICanvasObject> ();
                        widget.DrawEvent += Draw;
                        widget.SizeChangedEvent += HandleSizeChangedEvent;
-                       scaleX = 1;
-                       scaleY = 1;
-                       translation = new Point (0, 0);
+                       ScaleX = 1;
+                       ScaleY = 1;
+                       Translation = new Point (0, 0);
                }
 
                ~ Canvas ()
@@ -64,7 +64,7 @@ namespace LongoMatch.Drawing
                protected virtual void Dispose (bool disposing)
                {
                        // FIXME: Should we check if we are disposed already ?
-                       ignoreRedraws = true;
+                       IgnoreRedraws = true;
                        if (disposing) {
                                ClearObjects ();
                                Objects = null;
@@ -72,6 +72,9 @@ namespace LongoMatch.Drawing
                        }
                }
 
+               /// <summary>
+               /// Removes all the objects from the canvas.
+               /// </summary>
                protected virtual void ClearObjects ()
                {
                        if (Objects != null) {
@@ -83,50 +86,112 @@ namespace LongoMatch.Drawing
                        }
                }
 
+               /// <summary>
+               /// A list of the first level objects stored in the canvas.
+               /// Objects including other objects should take care of forwarding
+               /// the redraw events their self.
+               /// </summary>
                public List<ICanvasObject> Objects {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// Adds a new object to the canvas and a listener to its redraw event.
+               /// </summary>
+               /// <param name="co">The object to add.</param>
                public void AddObject (ICanvasObject co)
                {
                        Objects.Add (co);
                        co.RedrawEvent += HandleRedrawEvent;
                }
 
+               /// <summary>
+               /// Removes and object from the canvas.
+               /// </summary>
+               /// <param name="co">The object to remove.</param>
                public void RemoveObject (ICanvasObject co)
                {
                        co.RedrawEvent -= HandleRedrawEvent;
                        Objects.Remove (co);
                }
 
+               /// <summary>
+               /// Converts a point to the original position removing the applied
+               /// tanslation and invering the scale.
+               /// </summary>
+               /// <returns>The converted point.</returns>
+               /// <param name="p">The point to convert.</param>
                protected Point ToUserCoords (Point p)
                {
-                       return new Point ((p.X - translation.X) / scaleX,
-                               (p.Y - translation.Y) / scaleY);
+                       return new Point ((p.X - Translation.X) / ScaleX,
+                               (p.Y - Translation.Y) / ScaleY);
                
                }
 
+               /// <summary>
+               /// When set to <c>true</c> redraws events are not ignored
+               /// </summary>
+               protected bool IgnoreRedraws {
+                       get;
+                       set;
+               }
+
+               /// <summary>
+               /// Applied scale on the X axis
+               /// </summary>
+               protected double ScaleX {
+                       get;
+                       set;
+               }
+
+               /// <summary>
+               /// Applied scale on the Y axis.
+               /// </summary>
+               protected double ScaleY {
+                       get;
+                       set;
+               }
+
+               /// <summary>
+               /// Applied XY translation.
+               /// </summary>
+               protected Point Translation {
+                       get;
+                       set;
+               }
+
                void HandleRedrawEvent (ICanvasObject co, Area area)
                {
-                       if (!ignoreRedraws) {
+                       if (!IgnoreRedraws) {
                                widget.ReDraw (area);
                        }
                }
 
                void HandleSizeChangedEvent ()
                {
+                       /* After a resize objects are rescalled and we need to invalidate
+                        * their cached surfaces */
                        foreach (CanvasObject to in Objects) {
                                to.ResetDrawArea ();
                        }
                }
 
+               /// <summary>
+               /// Draws the canvas objects the specified context and area.
+               /// Object are drawn in the following order:
+               ///  1) Regular objects
+               ///  2) Selected objects
+               ///  3) Highlithed objects
+               /// </summary>
+               /// <param name="context">The context where the canvas is drawn.</param>
+               /// <param name="area">The affected area.</param>
                public virtual void Draw (IContext context, Area area)
                {
                        List<CanvasObject> highlighted = new List<CanvasObject> ();
                        tk.Context = context;
                        tk.Begin ();
-                       tk.TranslateAndScale (translation, new Point (scaleX, scaleY));
+                       tk.TranslateAndScale (Translation, new Point (ScaleX, ScaleY));
                        foreach (ICanvasObject co in Objects) {
                                if (co.Visible) {
                                        if (co is ICanvasSelectableObject) {
@@ -154,6 +219,10 @@ namespace LongoMatch.Drawing
                }
        }
 
+       /// <summary>
+       /// A selection canvas supports selecting <see cref="ICanvasSelectableObject"/>
+       /// objects from the canvas and moving, resizing them.
+       /// </summary>
        public class SelectionCanvas: Canvas
        {
                protected bool moving, moved;
@@ -168,7 +237,6 @@ namespace LongoMatch.Drawing
                        SelectionMode = MultiSelectionMode.Single;
                        Accuracy = 1;
                        ClickRepeatMS = 100;
-                       MoveWithoutSelection = false;
                        ObjectsCanMove = true;
                        SingleSelectionObjects = new List<Type> ();
                        
@@ -185,6 +253,9 @@ namespace LongoMatch.Drawing
                        base.Dispose (disposing);
                }
 
+               /// <summary>
+               /// Clears the objects.
+               /// </summary>
                protected override void ClearObjects ()
                {
                        // Make sure we don't maintain a selection with invalid objects.
@@ -192,45 +263,61 @@ namespace LongoMatch.Drawing
                        base.ClearObjects ();
                }
 
+               /// <summary>
+               /// Maximum time in milliseconds where 2 mouse clicks are
+               /// considered a single one
+               /// </summary>
                public int ClickRepeatMS {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// Set the tolerance for clicks in the dashboards. An accuracy of 5
+               /// lets select objects with clicks 5 points away from their position.
+               /// </summary>
                public double Accuracy {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// Set the selection mode.
+               /// </summary>
                public MultiSelectionMode SelectionMode {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// A list of objects for which multiple selection is disabled.
+               /// </summary>
                public List<Type> SingleSelectionObjects {
                        get;
                        set;
                }
 
+               /// <summary>
+               /// If <c>true</c> objects can moved in the canvas
+               /// </summary>
                public bool ObjectsCanMove {
                        get;
                        set;
                }
 
-               protected bool MoveWithoutSelection {
-                       get;
-                       set;
-               }
-
+               /// <summary>
+               /// A list with all the selected objects
+               /// </summary>
                protected List<Selection> Selections {
                        get;
                        set;
                }
 
-               protected virtual void StartMove (Selection sel)
-               {
-               }
-
+               /// <summary>
+               /// Called when the cursor is being moved.
+               /// Highlights objects when the cursor passes over them. 
+               /// </summary>
+               /// <param name="coords">Coords.</param>
                protected virtual void CursorMoved (Point coords)
                {
                        CanvasObject current;
@@ -254,18 +341,43 @@ namespace LongoMatch.Drawing
                        }
                }
 
+               /// <summary>
+               /// Notifies subclasses when an object starts to be moved.
+               /// </summary>
+               /// <param name="sel">The selection moved.</param>
+               protected virtual void StartMove (Selection sel)
+               {
+               }
+
+               /// <summary>
+               /// Notifies subclasses when an object has been moved.
+               /// </summary>
+               /// <param name="sel">The selection moved.</param>
                protected virtual void SelectionMoved (Selection sel)
                {
                }
 
+               /// <summary>
+               /// Notifies subclass when the move process stops.
+               /// </summary>
+               /// <param name="moved">If set to <c>true</c>, the object position changed.</param>
                protected virtual void StopMove (bool moved)
                {
                }
 
+               /// <summary>
+               /// Notifies subclasses when the selected objects has changed.
+               /// </summary>
+               /// <param name="sel">List of selected objects.</param>
                protected virtual void SelectionChanged (List<Selection> sel)
                {
                }
 
+               /// <summary>
+               /// Notifies subclasses a menu should be displayed.
+               /// Canvas' with menus should override it to display their menu here.
+               /// </summary>
+               /// <param name="coords">Position where the click happens.</param>
                protected virtual void ShowMenu (Point coords)
                {
                }
@@ -284,6 +396,14 @@ namespace LongoMatch.Drawing
                        Selections.Clear ();
                }
 
+               /// <summary>
+               /// Updates the current selection. If <paramref name="sel"/> is <c>null</c>,
+               /// it clears the current selection. If <paramref name="sel"/> wasn't previously
+               /// selected, it's added to the list of selected objects, otherwise it's removed
+               /// from the list.
+               /// </summary>
+               /// <param name="sel">The selection.</param>
+               /// <param name="notify">If set to <c>true</c>, notifies about the changes.</param>
                protected void UpdateSelection (Selection sel, bool notify = true)
                {
                        ICanvasSelectableObject so;
@@ -457,8 +577,14 @@ namespace LongoMatch.Drawing
                protected virtual void HandleSizeChangedEvent ()
                {
                        if (background != null) {
+                               double scaleX, scaleY;
+                               Point translation;
+
                                background.ScaleFactor ((int)widget.Width, (int)widget.Height, out scaleX,
                                        out scaleY, out translation);
+                               ScaleX = scaleX;
+                               ScaleY = scaleY;
+                               Translation = translation;
                        }
                }
 
@@ -467,7 +593,7 @@ namespace LongoMatch.Drawing
                        if (Background != null) {
                                tk.Context = context;
                                tk.Begin ();
-                               tk.TranslateAndScale (translation, new Point (scaleX, scaleY));
+                               tk.TranslateAndScale (Translation, new Point (ScaleX, ScaleY));
                                tk.DrawImage (Background);
                                tk.End ();
                        }
diff --git a/LongoMatch.Drawing/CanvasObjects/ButtonObject.cs 
b/LongoMatch.Drawing/CanvasObjects/ButtonObject.cs
index 1da89d1..e04fc8a 100644
--- a/LongoMatch.Drawing/CanvasObjects/ButtonObject.cs
+++ b/LongoMatch.Drawing/CanvasObjects/ButtonObject.cs
@@ -28,7 +28,8 @@ namespace LongoMatch.Drawing.CanvasObjects
                const int SELECTION_SIZE = 6;
                protected ISurface backBufferSurface;
 
-               public ButtonObject () {
+               public ButtonObject ()
+               {
                        BackgroundColor = Config.Style.PaletteBackgroundLight;
                        BackgroundColorActive = Config.Style.PaletteActive;
                        BorderColor = Config.Style.PaletteBackgroundDark;
@@ -36,7 +37,7 @@ namespace LongoMatch.Drawing.CanvasObjects
                        MinWidth = 20;
                        MinHeight = 20;
                }
-               
+
                protected override void Dispose (bool disposing)
                {
                        ResetBackbuffer ();
@@ -62,7 +63,7 @@ namespace LongoMatch.Drawing.CanvasObjects
                        get;
                        set;
                }
-               
+
                public virtual Color BackgroundColorActive {
                        get;
                        set;
@@ -82,7 +83,7 @@ namespace LongoMatch.Drawing.CanvasObjects
                        get;
                        set;
                }
-               
+
                protected Color CurrentBackgroundColor {
                        get {
                                if (!Active) {
@@ -107,7 +108,7 @@ namespace LongoMatch.Drawing.CanvasObjects
                public virtual Area Area {
                        get {
                                return new Area (Position, Width + SELECTION_SIZE / 2 + 1,
-                                                Height + SELECTION_SIZE / 2 + 1);
+                                       Height + SELECTION_SIZE / 2 + 1);
                        }
                }
 
@@ -136,7 +137,7 @@ namespace LongoMatch.Drawing.CanvasObjects
                        }
                }
 
-               public Selection GetSelection (Point p, double precision, bool inMotion=false)
+               public virtual Selection GetSelection (Point p, double precision, bool inMotion = false)
                {
                        Selection s;
 
@@ -145,8 +146,8 @@ namespace LongoMatch.Drawing.CanvasObjects
                        if (s != null) {
                                s.Drawable = this;
                                if (s.Position != SelectionPosition.BottomRight &&
-                                       s.Position != SelectionPosition.Right &&
-                                       s.Position != SelectionPosition.Bottom) {
+                                   s.Position != SelectionPosition.Right &&
+                                   s.Position != SelectionPosition.Bottom) {
                                        s.Position = SelectionPosition.All;
                                }
                        }
@@ -199,8 +200,8 @@ namespace LongoMatch.Drawing.CanvasObjects
                        tk.StrokeColor = tk.FillColor = Constants.SELECTION_INDICATOR_COLOR;
                        tk.LineStyle = LineStyle.Normal;
                        tk.DrawRectangle (new Point (Position.X + Width - SELECTION_SIZE / 2,
-                                                    Position.Y + Height - SELECTION_SIZE / 2),
-                                         SELECTION_SIZE, SELECTION_SIZE);
+                               Position.Y + Height - SELECTION_SIZE / 2),
+                               SELECTION_SIZE, SELECTION_SIZE);
                }
 
                protected void DrawButton (IDrawingToolkit tk)
@@ -214,7 +215,7 @@ namespace LongoMatch.Drawing.CanvasObjects
                        } else {
                                tk.LineWidth = 0;
                                front = TextColor;
-                               back =  BackgroundColor;
+                               back = BackgroundColor;
                        }
                        tk.FillColor = back;
                        tk.StrokeColor = front;
@@ -222,7 +223,7 @@ namespace LongoMatch.Drawing.CanvasObjects
                        if (Icon != null) {
                                tk.FillColor = front;
                                tk.DrawImage (new Point (Position.X + 5, Position.Y + 5),
-                                             Icon.Width, Icon.Height, Icon, false, true);
+                                       Icon.Width, Icon.Height, Icon, false, true);
                        }
                }
 
@@ -254,7 +255,8 @@ namespace LongoMatch.Drawing.CanvasObjects
                        }
                }
 
-               void CreateBackBufferSurface () {
+               void CreateBackBufferSurface ()
+               {
                        IDrawingToolkit tk = Config.DrawingToolkit;
 
                        ResetBackbuffer ();
@@ -262,7 +264,7 @@ namespace LongoMatch.Drawing.CanvasObjects
                        using (IContext c = backBufferSurface.Context) {
                                tk.Context = c;
                                tk.TranslateAndScale (new Point (-Position.X, -Position.Y),
-                                                     new Point (1, 1));
+                                       new Point (1, 1));
                                DrawButton (tk);
                                DrawImage (tk);
                                DrawText (tk);
diff --git a/LongoMatch.Drawing/Widgets/Blackboard.cs b/LongoMatch.Drawing/Widgets/Blackboard.cs
index 461e3e2..e194817 100644
--- a/LongoMatch.Drawing/Widgets/Blackboard.cs
+++ b/LongoMatch.Drawing/Widgets/Blackboard.cs
@@ -349,7 +349,7 @@ namespace LongoMatch.Drawing.Widgets
                        if (backbuffer != null) {
                                tk.Context = context;
                                tk.Begin ();
-                               tk.TranslateAndScale (translation, new Point (scaleX, scaleY));
+                               tk.TranslateAndScale (Translation, new Point (ScaleX, ScaleY));
                                tk.DrawSurface (backbuffer);
                                tk.End ();
                        }
diff --git a/LongoMatch.Drawing/Widgets/DashboardCanvas.cs b/LongoMatch.Drawing/Widgets/DashboardCanvas.cs
index 4f056c4..88c62c5 100644
--- a/LongoMatch.Drawing/Widgets/DashboardCanvas.cs
+++ b/LongoMatch.Drawing/Widgets/DashboardCanvas.cs
@@ -211,7 +211,7 @@ namespace LongoMatch.Drawing.Widgets
                        tk.Begin ();
                        tk.Clear (Config.Style.PaletteBackground);
                        if (TagMode == TagMode.Edit) {
-                               tk.TranslateAndScale (translation, new Point (scaleX, scaleY));
+                               tk.TranslateAndScale (Translation, new Point (ScaleX, ScaleY));
                                /* Draw grid */
                                tk.LineWidth = 1;
                                tk.StrokeColor = Color.Grey1;
@@ -291,16 +291,21 @@ namespace LongoMatch.Drawing.Widgets
                        if (FitMode == FitMode.Original) {
                                widget.Width = templateWidth;
                                widget.Height = templateHeight;
-                               scaleX = scaleY = 1;
-                               translation = new Point (0, 0);
+                               ScaleX = ScaleY = 1;
+                               Translation = new Point (0, 0);
                        } else if (FitMode == FitMode.Fill) {
-                               scaleX = (double)widget.Width / templateWidth;
-                               scaleY = (double)widget.Height / templateHeight;
-                               translation = new Point (0, 0);
+                               ScaleX = (double)widget.Width / templateWidth;
+                               ScaleY = (double)widget.Height / templateHeight;
+                               Translation = new Point (0, 0);
                        } else if (FitMode == FitMode.Fit) {
+                               double scaleX, scaleY;
+                               Point translation;
                                Image.ScaleFactor (templateWidth, templateHeight,
                                        (int)widget.Width, (int)widget.Height,
                                        out scaleX, out scaleY, out translation);
+                               ScaleX = scaleX;
+                               ScaleY = scaleY;
+                               Translation = translation;
                        }
                        if (modeChanged) {
                                modeChanged = false;


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