[longomatch] Document Canvas and cleanup API
- From: Andoni Morales Alastruey <amorales src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [longomatch] Document Canvas and cleanup API
- Date: Fri, 17 Apr 2015 16:23:50 +0000 (UTC)
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]