diff --git a/Perspex.Base/IDescription.cs b/Perspex.Base/IDescription.cs index 557c9c858f..157ecb4abd 100644 --- a/Perspex.Base/IDescription.cs +++ b/Perspex.Base/IDescription.cs @@ -6,8 +6,17 @@ namespace Perspex { + /// + /// Interface for objects with a . + /// public interface IDescription { + /// + /// Gets the description of the object. + /// + /// + /// The description of the object. + /// string Description { get; } } } diff --git a/Perspex.Base/PerspexObject.cs b/Perspex.Base/PerspexObject.cs index f43bbcd9aa..af82369b78 100644 --- a/Perspex.Base/PerspexObject.cs +++ b/Perspex.Base/PerspexObject.cs @@ -6,9 +6,6 @@ namespace Perspex { - using Perspex.Reactive; - using Serilog; - using Serilog.Core.Enrichers; using System; using System.Collections.Generic; using System.ComponentModel; @@ -16,6 +13,9 @@ namespace Perspex using System.Reactive.Disposables; using System.Reactive.Linq; using System.Reflection; + using Perspex.Reactive; + using Serilog; + using Serilog.Core.Enrichers; /// /// The priority of a binding. @@ -36,9 +36,9 @@ namespace Perspex /// A triggered style binding. /// /// - /// A style trigger is a selector such as .class which overrides a + /// A style trigger is a selector such as .class which overrides a /// binding. In this way, a basic control can have - /// for example a Background from the templated parent which changes when the + /// for example a Background from the templated parent which changes when the /// control has the :pointerover class. /// StyleTrigger, @@ -134,9 +134,12 @@ namespace Perspex } /// - /// Gets or sets the parent object that inherited values + /// Gets or sets the parent object that inherited values /// are inherited from. /// + /// + /// The inheritance parent. + /// protected PerspexObject InheritanceParent { get @@ -210,8 +213,8 @@ namespace Perspex set { - BindingMode mode = (binding.Mode == BindingMode.Default) ? - binding.Property.DefaultBindingMode : + BindingMode mode = (binding.Mode == BindingMode.Default) ? + binding.Property.DefaultBindingMode : binding.Mode; Binding sourceBinding = value as Binding; @@ -272,7 +275,7 @@ namespace Perspex /// The type. /// The property. /// - /// You won't usually want to call this method directly, instead use the + /// You won't usually want to call this method directly, instead use the /// method. /// public static void Register(Type type, PerspexProperty property) @@ -301,7 +304,7 @@ namespace Perspex public void ClearValue(PerspexProperty property) { Contract.Requires(property != null); - + this.SetValue(property, PerspexProperty.UnsetValue); } @@ -333,7 +336,7 @@ namespace Perspex { this.PropertyChanged -= handler; }); - }, + }, this.GetObservableDescription(property)); } @@ -353,9 +356,10 @@ namespace Perspex /// /// Gets an observable for a . /// - /// - /// - /// + /// The type of the property. + /// The property. + /// An observable which when subscribed pushes the old and new values of the + /// property each time it is changed. public IObservable> GetObservableWithHistory(PerspexProperty property) { return new PerspexObservable>( @@ -375,7 +379,7 @@ namespace Perspex { this.PropertyChanged -= handler; }); - }, + }, this.GetObservableDescription(property)); } @@ -412,6 +416,7 @@ namespace Perspex /// /// Gets a value. /// + /// The type of the property. /// The property. /// The value. public T GetValue(PerspexProperty property) @@ -493,8 +498,8 @@ namespace Perspex /// The value. /// The priority of the value. public void SetValue( - PerspexProperty property, - object value, + PerspexProperty property, + object value, BindingPriority priority = BindingPriority.LocalValue) { Contract.Requires(property != null); @@ -530,8 +535,8 @@ namespace Perspex } this.propertyLog.Verbose( - "Set {Property} to {$Value} with priority {Priority}", - property, + "Set {Property} to {$Value} with priority {Priority}", + property, value, priority); v.SetDirectValue(value, (int)priority); @@ -545,8 +550,8 @@ namespace Perspex /// The value. /// The priority of the value. public void SetValue( - PerspexProperty property, - T value, + PerspexProperty property, + T value, BindingPriority priority = BindingPriority.LocalValue) { Contract.Requires(property != null); @@ -557,7 +562,6 @@ namespace Perspex /// /// Binds a to an observable. /// - /// The type of the property. /// The property. /// The observable. /// The priority of the binding. @@ -589,8 +593,8 @@ namespace Perspex } this.propertyLog.Verbose( - "Bound {Property} to {Binding} with priority {Priority}", - property, + "Bound {Property} to {Binding} with priority {Priority}", + property, source, priority); @@ -608,8 +612,8 @@ namespace Perspex /// A disposable which can be used to terminate the binding. /// public IDisposable Bind( - PerspexProperty property, - IObservable source, + PerspexProperty property, + IObservable source, BindingPriority priority = BindingPriority.LocalValue) { Contract.Requires(property != null); @@ -631,8 +635,8 @@ namespace Perspex /// The binding is first carried out from to this. /// public IDisposable BindTwoWay( - PerspexProperty property, - PerspexObject source, + PerspexProperty property, + PerspexObject source, PerspexProperty sourceProperty, BindingPriority priority = BindingPriority.LocalValue) { @@ -782,17 +786,17 @@ namespace Perspex /// The new property value. /// The priority of the binding that produced the value. private void RaisePropertyChanged( - PerspexProperty property, - object oldValue, - object newValue, + PerspexProperty property, + object oldValue, + object newValue, BindingPriority priority) { Contract.Requires(property != null); PerspexPropertyChangedEventArgs e = new PerspexPropertyChangedEventArgs( - this, - property, - oldValue, + this, + property, + oldValue, newValue, priority); diff --git a/Perspex.Base/PerspexProperty.cs b/Perspex.Base/PerspexProperty.cs index c2eb1fb00d..17850e8631 100644 --- a/Perspex.Base/PerspexProperty.cs +++ b/Perspex.Base/PerspexProperty.cs @@ -22,6 +22,7 @@ namespace Perspex /// /// Represents an unset property value. /// + [System.Diagnostics.CodeAnalysis.SuppressMessage("StyleCop.CSharp.MaintainabilityRules", "SA1401:Fields must be private", Justification = "It's readonly")] public static readonly object UnsetValue = new Unset(); /// @@ -49,6 +50,7 @@ namespace Perspex /// Whether the property inherits its value. /// The default binding mode for the property. /// A coercion function. + /// Whether the property is an attached property. public PerspexProperty( string name, Type valueType, @@ -76,37 +78,57 @@ namespace Perspex /// /// Gets the name of the property. /// + /// + /// The name of the property. + /// public string Name { get; } /// /// Gets the type of the property's value. /// + /// + /// The type of the property's value. + /// public Type PropertyType { get; } /// /// Gets the type of the class that registers the property. /// + /// + /// The type of the class that registers the property. + /// public Type OwnerType { get; } /// /// Gets a value indicating whether the property inherits its value. /// + /// + /// A value indicating whether the property inherits its value. + /// public bool Inherits { get; } /// /// Gets the default binding mode for the property. /// - /// + /// + /// The default binding mode for the property. + /// public BindingMode DefaultBindingMode { get; } /// /// Gets the property's coerce function. /// + /// + /// The property's coerce function. + /// public Func Coerce { get; } /// /// Gets a value indicating whether this is an attached property. /// + /// + /// A value indicating whether this is an attached property. + /// public bool IsAttached { get; } /// @@ -115,24 +137,62 @@ namespace Perspex /// /// /// This observable is fired each time a new is constructed - /// for all properties registered on the object's type. The default value of the property - /// for the object is passed in the args' NewValue (OldValue will always be + /// for all properties registered on the object's type. The default value of the property + /// for the object is passed in the args' NewValue (OldValue will always be /// . /// + /// + /// An observable that is fired when this property is initialized on a new + /// instance. + /// public IObservable Initialized { get { return this.initialized; } } /// - /// Gets an observable that is fired when this property changes on any + /// Gets an observable that is fired when this property changes on any /// instance. /// + /// + /// An observable that is fired when this property changes on any + /// instance. + /// public IObservable Changed { get { return this.changed; } } + /// + /// Provides access to a property's binding via the + /// indexer. + /// + /// The property. + /// A describing the binding. + public static Binding operator !(PerspexProperty property) + { + return new Binding + { + Priority = BindingPriority.LocalValue, + Property = property, + }; + } + + /// + /// Provides access to a property's template binding via the + /// indexer. + /// + /// The property. + /// A describing the binding. + public static Binding operator ~(PerspexProperty property) + { + return new Binding + { + Priority = BindingPriority.TemplatedParent, + Property = property, + }; + } + /// /// Registers a . /// @@ -240,37 +300,7 @@ namespace Perspex } /// - /// Provides access to a property's binding via the - /// indexer. - /// - /// The property. - /// A describing the binding. - public static Binding operator !(PerspexProperty property) - { - return new Binding - { - Priority = BindingPriority.LocalValue, - Property = property, - }; - } - - /// - /// Provides access to a property's template binding via the - /// indexer. - /// - /// The property. - /// A describing the binding. - public static Binding operator ~(PerspexProperty property) - { - return new Binding - { - Priority = BindingPriority.TemplatedParent, - Property = property, - }; - } - - /// - /// Returns a binding accessor that can be passed to 's [] + /// Returns a binding accessor that can be passed to 's [] /// operator to initiate a binding. /// /// A . @@ -309,6 +339,11 @@ namespace Perspex return this.defaultValues[this.OwnerType]; } + /// + /// Checks whether the is valid for the property. + /// + /// The value. + /// True if the value is valid, otherwise false. public bool IsValidValue(object value) { if (value == UnsetValue) @@ -342,96 +377,46 @@ namespace Perspex this.defaultValues.Add(type, defaultValue); } + /// + /// Gets the string representation of the property. + /// + /// The property's string representation. public override string ToString() { return this.Name; } + /// + /// Notifies the observable. + /// + /// The observable arguments. internal void NotifyInitialized(PerspexPropertyChangedEventArgs e) { this.initialized.OnNext(e); } + /// + /// Notifies the observable. + /// + /// The observable arguments. internal void NotifyChanged(PerspexPropertyChangedEventArgs e) { this.changed.OnNext(e); } + /// + /// Class representing the . + /// private class Unset { + /// + /// Returns the string representation of the . + /// + /// The string "(unset)". public override string ToString() { return "(unset)"; } } } - - /// - /// A typed perspex property. - /// - public class PerspexProperty : PerspexProperty - { - /// - /// Initializes a new instance of the class. - /// - /// The name of the property. - /// The type of the class that registers the property. - /// The default value of the property. - /// Whether the property inherits its value. - /// The default binding mode for the property. - /// A coercion function. - /// Whether the property is an attached property. - public PerspexProperty( - string name, - Type ownerType, - TValue defaultValue = default(TValue), - bool inherits = false, - BindingMode defaultBindingMode = BindingMode.Default, - Func coerce = null, - bool isAttached = false) - : base( - name, - typeof(TValue), - ownerType, - defaultValue, - inherits, - defaultBindingMode, - Convert(coerce), - isAttached) - { - Contract.Requires(name != null); - Contract.Requires(ownerType != null); - } - - /// - /// Registers the property on another type. - /// - /// The type of the additional owner. - /// The property. - public PerspexProperty AddOwner() - { - PerspexObject.Register(typeof(TOwner), this); - return this; - } - - /// - /// Gets the default value for the property on the specified type. - /// - /// The type. - /// The default value. - public TValue GetDefaultValue() - { - return (TValue)this.GetDefaultValue(typeof(T)); - } - - /// - /// Converts from a typed coercion function to an untyped. - /// - /// The typed coercion function. - /// Te untyped coercion function. - private static Func Convert(Func f) - { - return f != null ? (o, v) => f(o, (TValue)v) : (Func)null; - } - } } diff --git a/Perspex.Base/PerspexPropertyChangedEventArgs.cs b/Perspex.Base/PerspexPropertyChangedEventArgs.cs index e29acf6602..0912df7846 100644 --- a/Perspex.Base/PerspexPropertyChangedEventArgs.cs +++ b/Perspex.Base/PerspexPropertyChangedEventArgs.cs @@ -11,6 +11,14 @@ namespace Perspex /// public class PerspexPropertyChangedEventArgs { + /// + /// Initializes a new instance of the class. + /// + /// The object that the property changed on. + /// The property that changed. + /// The old value of the property. + /// The new value of the property. + /// The priority of the binding that produced the value. public PerspexPropertyChangedEventArgs( PerspexObject sender, PerspexProperty property, @@ -28,27 +36,39 @@ namespace Perspex /// /// Gets the that the property changed on. /// - /// + /// The sender object. public PerspexObject Sender { get; private set; } /// /// Gets the property that changed. /// + /// + /// The property that changed. + /// public PerspexProperty Property { get; private set; } /// /// Gets the old value of the property. /// + /// + /// The old value of the property. + /// public object OldValue { get; private set; } /// /// Gets the new value of the property. /// + /// + /// The new value of the property. + /// public object NewValue { get; private set; } /// /// Gets the priority of the binding that produced the value. /// + /// + /// The priority of the binding that produced the value. + /// public BindingPriority Priority { get; private set; } } } diff --git a/Perspex.Base/PerspexProperty`1.cs b/Perspex.Base/PerspexProperty`1.cs new file mode 100644 index 0000000000..ebd28467e2 --- /dev/null +++ b/Perspex.Base/PerspexProperty`1.cs @@ -0,0 +1,80 @@ +// ----------------------------------------------------------------------- +// +// Copyright 2014 MIT Licence. See licence.md for more information. +// +// ----------------------------------------------------------------------- + +namespace Perspex +{ + using System; + + /// + /// A typed perspex property. + /// + /// The value type of the property. + public class PerspexProperty : PerspexProperty + { + /// + /// Initializes a new instance of the class. + /// + /// The name of the property. + /// The type of the class that registers the property. + /// The default value of the property. + /// Whether the property inherits its value. + /// The default binding mode for the property. + /// A coercion function. + /// Whether the property is an attached property. + public PerspexProperty( + string name, + Type ownerType, + TValue defaultValue = default(TValue), + bool inherits = false, + BindingMode defaultBindingMode = BindingMode.Default, + Func coerce = null, + bool isAttached = false) + : base( + name, + typeof(TValue), + ownerType, + defaultValue, + inherits, + defaultBindingMode, + Convert(coerce), + isAttached) + { + Contract.Requires(name != null); + Contract.Requires(ownerType != null); + } + + /// + /// Registers the property on another type. + /// + /// The type of the additional owner. + /// The property. + public PerspexProperty AddOwner() + { + PerspexObject.Register(typeof(TOwner), this); + return this; + } + + /// + /// Gets the default value for the property on the specified type. + /// + /// The type. + /// The default value. + public TValue GetDefaultValue() + { + return (TValue)this.GetDefaultValue(typeof(T)); + } + + /// + /// Converts from a typed coercion function to an untyped. + /// + /// The typed coercion function. + /// Te untyped coercion function. + private static Func Convert(Func f) + { + return f != null ? (o, v) => f(o, (TValue)v) : (Func)null; + } + } +}