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);