diff --git a/Perspex.Controls/Control.cs b/Perspex.Controls/Control.cs
index dffee0001d..f5bf956286 100644
--- a/Perspex.Controls/Control.cs
+++ b/Perspex.Controls/Control.cs
@@ -7,36 +7,63 @@
namespace Perspex.Controls
{
using System;
- using System.Collections.Generic;
- using System.Linq;
using System.Reactive.Linq;
using Perspex.Collections;
using Perspex.Controls.Primitives;
- using Perspex.Controls.Shapes;
using Perspex.Input;
using Perspex.Interactivity;
- using Perspex.Media;
using Perspex.Rendering;
using Perspex.Styling;
using Splat;
+ ///
+ /// Base class for Perspex controls.
+ ///
+ ///
+ /// The control class extends and adds the following features:
+ ///
+ /// - A .
+ /// - An inherited .
+ /// - A property to allow user-defined data to be attached to the control.
+ /// - A collection of class strings for custom styling.
+ /// - Implements to allow styling to work on the control.
+ /// - Implements to form part of a logical tree.
+ ///
public class Control : InputElement, INamed, ILogical, IStyleable, IStyleHost
{
+ ///
+ /// Defines the property.
+ ///
public static readonly PerspexProperty DataContextProperty =
- PerspexProperty.Register("DataContext", inherits: true);
+ PerspexProperty.Register(nameof(DataContext), inherits: true);
+ ///
+ /// Defines the property.
+ ///
public static readonly PerspexProperty FocusAdornerProperty =
- PerspexProperty.Register("FocusAdorner");
+ PerspexProperty.Register(nameof(FocusAdorner));
+ ///
+ /// Defines the property.
+ ///
public static readonly PerspexProperty ParentProperty =
- PerspexProperty.Register("Parent");
+ PerspexProperty.Register(nameof(Parent));
+ ///
+ /// Defines the property.
+ ///
public static readonly PerspexProperty TagProperty =
- PerspexProperty.Register("Tag");
+ PerspexProperty.Register(nameof(Tag));
+ ///
+ /// Defines the property.
+ ///
public static readonly PerspexProperty TemplatedParentProperty =
- PerspexProperty.Register("TemplatedParent");
+ PerspexProperty.Register(nameof(TemplatedParent));
+ ///
+ /// Event raised when an element wishes to be scrolled into view.
+ ///
public static readonly RoutedEvent RequestBringIntoViewEvent =
RoutedEvent.Register("RequestBringIntoView", RoutingStrategies.Bubble);
@@ -52,6 +79,9 @@ namespace Perspex.Controls
private Styles styles;
+ ///
+ /// Initializes static members of the class.
+ ///
static Control()
{
Control.AffectsMeasure(Control.IsVisibleProperty);
@@ -60,13 +90,28 @@ namespace Perspex.Controls
PseudoClass(InputElement.IsPointerOverProperty, ":pointerover");
}
+ ///
+ /// Gets or sets the control's classes.
+ ///
+ ///
+ ///
+ /// Classes can be used to apply user-defined styling to controls, or to allow controls
+ /// that share a common purpose to be easily selected.
+ ///
+ ///
+ /// Even though this property can be set, the setter is only intended for use in object
+ /// initializers. Assigning to this property does not change the underlying collection,
+ /// it simply clears the existing collection and addds the contents of the assigned
+ /// collection.
+ ///
+ ///
public Classes Classes
{
- get
+ get
{
- return this.classes;
+ return this.classes;
}
-
+
set
{
if (this.classes != value)
@@ -77,12 +122,35 @@ namespace Perspex.Controls
}
}
+ ///
+ /// Gets or sets the control's data context.
+ ///
+ ///
+ /// The data context is an inherited property that specifies the default object that will
+ /// be used for data binding.
+ ///
public object DataContext
{
get { return this.GetValue(DataContextProperty); }
set { this.SetValue(DataContextProperty, value); }
}
+ ///
+ /// Gets or sets the control's focus adorner.
+ ///
+ public AdornerTemplate FocusAdorner
+ {
+ get { return this.GetValue(FocusAdornerProperty); }
+ set { this.SetValue(FocusAdornerProperty, value); }
+ }
+
+ ///
+ /// Gets or sets the data templates for the control.
+ ///
+ ///
+ /// Each control may define data templates which are applied to the control itself and its
+ /// children.
+ ///
public DataTemplates DataTemplates
{
get
@@ -101,6 +169,13 @@ namespace Perspex.Controls
}
}
+ ///
+ /// Gets or sets the name of the control.
+ ///
+ ///
+ /// A control's name is used to uniquely identify a control within the control's name
+ /// scope. Once a control is added to a visual tree, its name cannot be changed.
+ ///
public string Name
{
get
@@ -124,6 +199,14 @@ namespace Perspex.Controls
}
}
+ ///
+ /// Gets or sets the styles for the control.
+ ///
+ ///
+ /// Styles for the entire application are added to the Application.Styles collection, but
+ /// each control may in addition define its own styles which are applied to the control
+ /// itself and its children.
+ ///
public Styles Styles
{
get
@@ -142,44 +225,75 @@ namespace Perspex.Controls
}
}
+ ///
+ /// Gets the control's logical parent.
+ ///
public Control Parent
{
get { return this.GetValue(ParentProperty); }
internal set { this.SetValue(ParentProperty, value); }
}
+ ///
+ /// Gets or sets a user-defined object attached to the control.
+ ///
public object Tag
{
get { return this.GetValue(TagProperty); }
set { this.SetValue(TagProperty, value); }
}
+ ///
+ /// Gets the control whose lookless template this control is part of.
+ ///
public ITemplatedControl TemplatedParent
{
get { return this.GetValue(TemplatedParentProperty); }
internal set { this.SetValue(TemplatedParentProperty, value); }
}
+ ///
+ /// Gets the control's logical parent.
+ ///
ILogical ILogical.LogicalParent
{
get { return this.Parent; }
}
+ ///
+ /// Gets the control's logical children.
+ ///
IPerspexReadOnlyList ILogical.LogicalChildren
{
get { return EmptyChildren; }
}
+ ///
+ /// Gets the type by which the control is styled.
+ ///
+ ///
+ /// Usually controls are styled by their own type, but there are instances where you want
+ /// a control to be styled by its base type, e.g. creating SpecialButton that
+ /// derives from Button and adds extra functionality but is still styled as a regular
+ /// Button.
+ ///
Type IStyleable.StyleKey
{
get { return this.GetType(); }
}
+ ///
+ /// Tries to being the control into view.
+ ///
public void BringIntoView()
{
this.BringIntoView(new Rect(this.Bounds.Size));
}
+ ///
+ /// Tries to being the specified area on the control into view.
+ ///
+ /// The area of the control to being into view.
public void BringIntoView(Rect rect)
{
var ev = new RequestBringIntoViewEventArgs
@@ -192,11 +306,13 @@ namespace Perspex.Controls
this.RaiseEvent(ev);
}
+ [Obsolete("Obsolete this: use properties instead")]
protected static void PseudoClass(PerspexProperty property, string className)
{
PseudoClass(property, x => x, className);
}
+ [Obsolete("Obsolete this: use properties instead")]
protected static void PseudoClass(
PerspexProperty property,
Func selector,
@@ -226,6 +342,7 @@ namespace Perspex.Controls
});
}
+ ///
protected override void OnGotFocus(GotFocusEventArgs e)
{
base.OnGotFocus(e);
@@ -255,10 +372,11 @@ namespace Perspex.Controls
}
}
+ ///
protected override void OnLostFocus(RoutedEventArgs e)
{
base.OnLostFocus(e);
-
+
if (this.focusAdorner != null)
{
var adornerLayer = this.focusAdorner.Parent as Panel;
@@ -267,6 +385,7 @@ namespace Perspex.Controls
}
}
+ ///
protected override void OnAttachedToVisualTree(IRenderRoot root)
{
base.OnAttachedToVisualTree(root);