Started adding property documentation.

10 years ago · 453668590b
2 changed files with 278 additions and 0 deletions
--- a/docs/defining-properties.md
+++ b/docs/defining-properties.md
@ -0,0 +1,178 @@
+# Defining Properties
+
+If you are creating a control, you will want to define properties on your
+control. The process in Perspex is broadly similar to other XAML languages
+with a few differences - the main one being that Perpsex's equivalent of
+`DependencyProperty` is called `StyledProperty`.
+
+## Registering Styled Properties
+
+A styled property is analogous to a `DependencyProperty` in other XAML
+frameworks.
+
+You register a styled property by calling `PerspexProperty.Register` and
+storing the result in a `static readonly` field. You then create a standard C#
+property to access it.
+
+Here's how the `Border` control defines its `Background` property:
+
+```c#
+    public static readonly StyledProperty<Brush> BackgroundProperty =
+        PerspexProperty.Register<Border, Brush>(nameof(Background));
+
+    public Brush Background
+    {
+        get { return GetValue(BackgroundProperty); }
+        set { SetValue(BackgroundProperty, value); }
+    }
+```
+
+The `PerspexProperty.Register` method also accepts a number of other parameters:
+
+- `defaultValue`: This gives the property a default value. Be sure to only pass
+value types and immutable types here as passing a reference type will cause the
+same object to be used on all instances on which the property is registered.
+- `inherits`: Specified that the property's default value should come from
+the parent control.
+- `defaultBindingMode`: The default binding mode for the property. Can be set to
+`OneWay`, `TwoWay`, `OneTime` or `OneWayToSource`.
+- `validate`: A validation/coercion function of type
+`Func<TOwner, TValue, TValue>`. The function accepts the instance of the class
+on which the property is being set and the value and returns the coerced value
+or throws an exception for an invalid value.
+
+## Using a StyledProperty from Another Class
+
+Sometimes the property you want to add to your control already exists on another
+control, `Background` being a good example. To register a property defined on
+another control, you call `StyledProperty.AddOwner`:
+
+
+```c#
+    public static readonly StyledProperty<Brush> BackgroundProperty =
+        Border.BackgroundProperty.AddOwner<Panel>();
+
+    public Brush Background
+    {
+        get { return GetValue(BackgroundProperty); }
+        set { SetValue(BackgroundProperty, value); }
+    }
+```
+
+*Note: Unlike WPF, a property must be registered on a class otherwise it cannot
+be set on an object of that class.*
+
+## Attached Properties
+
+Attached properties are defined almost identically to styled properties except
+that they are registered using the `RegisterAttached` method and their accessors
+are defined as static methods.
+
+Here's how `Grid` defines its `Grid.Column` attached property:
+
+```c#
+    public static readonly AttachedProperty<int> ColumnProperty =
+        PerspexProperty.RegisterAttached<Grid, Control, int>("Column");
+
+    public static int GetColumn(Control element)
+    {
+        return element.GetValue(ColumnProperty);
+    }
+
+    public static void SetColumn(Control element, int value)
+    {
+        element.SetValue(ColumnProperty, value);
+    }
+```
+
+## Readonly PerspexProperties
+
+To create a readonly property you use the `PerspexProperty.RegisterDirect`
+method. Here is how `Visual` registers the readonly `Bounds` property:
+
+```c#
+    public static readonly DirectProperty<Visual, Rect> BoundsProperty =
+        PerspexProperty.RegisterDirect<Visual, Rect>(
+            nameof(Bounds),
+            o => o.Bounds);
+
+    private Rect _bounds;
+
+    public Rect Bounds
+    {
+        get { return _bounds; }
+        private set { SetAndRaise(BoundsProperty, ref _bounds, value); }
+    }
+```
+
+As can be seen, readonly properties are stored as a field on the object. When
+registering the property, a getter is passed which is used to access the
+property value through `GetValue` and then `SetAndRaise` is used to notify
+listeners to changes to the property.
+
+## Direct PerspexProperties
+
+As its name suggests, `RegisterDirect` isn't just used for registering readonly
+properties. You can also pass a *setter* to `RegisterDirect` to expose a
+standard C# property as a Perspex property.
+
+A `StyledProperty` which is registered using `PerspexProperty.Register`
+maintains a prioritized list of values and bindings that allow styles to work.
+However, this is overkill for many properties, such as `ItemsControl.Items` -
+this will never be styled and the overhead involved with styled properties is
+unnecessary.
+
+Here is how `ItemsControl.Items` is registered:
+
+```c#
+    public static readonly DirectProperty<ItemsControl, IEnumerable> ItemsProperty =
+        PerspexProperty.RegisterDirect<ItemsControl, IEnumerable>(
+            nameof(Items),
+            o => o.Items,
+            (o, v) => o.Items = v);
+
+    private IEnumerable _items = new PerspexList<object>();
+
+    public IEnumerable Items
+    {
+        get { return _items; }
+        set { SetAndRaise(ItemsProperty, ref _items, value); }
+    }
+```
+
+
+Direct properties are a lightweight version of styled properties that support
+the following:
+
+- PerspexObject.GetValue
+- PerspexObject.SetValue for non-readonly properties
+- PropertyChanged
+- Binding (only with LocalValue priority)
+- GetObservable
+- AddOwner
+- Metadata
+
+They don't support the following:
+
+- Validation/Coercion (although this could be done in the property setter)
+- Overriding default values.
+- Inherited values
+
+## When to use a Direct vs a Styled Property
+
+Direct properties have advantages and disadvantages:
+
+Pros:
+- No additional object is allocated per-instance for the property
+- Property getter is a standard C# property getter
+- Property setter is is a standard C# property setter that raises an event.
+
+Cons:
+- Cannot inherit value from parent control
+- Cannot take advantage of Perspex's styling system
+- Property value is a field and as such is allocated whether the property is
+set on the object or not
+
+So use direct properties when you have the following requirements:
+- Property will not need to be styled
+- Property will usually or always have a value
--- a/docs/working-with-properties.md
+++ b/docs/working-with-properties.md
@ -0,0 +1,100 @@
+# Working with Properties
+
+Perspex controls expose their properties as standard CLR properties, so for
+reading and writing values there's no surprises:
+
+```c#
+    // Create a TextBlock and set its Text property.
+    var textBlock = new TextBlock();
+    textBlock.Text = "Hello World!";
+```
+
+
+However there's a lot more you can do with properties such as subscribing to
+changes on the property, and binding.
+
+# Subscribing to Changes to a Property
+
+You can subscribe to changes on a property by calling the `GetObservable`
+method. This returns an `IObservable<T>` which can be used to listen for changes
+to the property:
+
+```c#
+    var textBlock = new TextBlock();
+    var text = textBlock.GetObservable(TextBlock.TextProperty);
+```
+
+Each property that can be subscribed to has a static readonly field called
+`[PropertyName]Property` which is passed to `GetObservable` in order to
+subscribe to the property's changes.
+
+`IObservable` (part of Reactive Extensions, or rx for short) is out of scope
+for this guide, but here's an example which uses the returned observable to
+print a message with the changing property values to the console:
+
+```c#
+    var textBlock = new TextBlock();
+    var text = textBlock.GetObservable(TextBlock.TextProperty);
+    text.Subscribe(value => Console.WriteLine(value + " Changed"));
+```
+
+When the returned observable is subscribed, it will return the current value
+of the property immediately and then push a new value each time the property
+changes. If you don't want the current value, you can use the rx `Skip`
+operator:
+
+```c#
+    var text = textBlock.GetObservable(TextBlock.TextProperty).Skip(1);
+```
+
+# Binding a property
+
+Observables don't just go one way! You can also use them to bind properties.
+For example here we create two `TextBlock`s and bind the second's `Text`
+property to the first:
+
+```c#
+  var textBlock1 = new TextBlock();
+  var textBlock2 = new TextBlock();
+
+  // Get an observable for the first text block's Text property.
+  var source = textBlock1.GetObservable(TextBlock.TextProperty);
+
+  // And bind it to the second.
+  textBlock2.Bind(TextBlock.TextProperty, source);
+
+  // Changes to the first TextBlock's Text property will now be propagated
+  // to the second.
+  textBlock1.Text = "Goodbye Cruel World";
+
+  // Prints "Goodbye Cruel World"
+  Console.WriteLine(textBlock2.Text);
+```
+
+# Subscribing to a Property on Any Object
+
+The `GetObservable` method returns an observable that tracks changes to a
+property on a single instance. However, if you're writing a control you may
+want to implement an `OnPropertyChanged` method. In WPF this is done by passing
+a static `PropertyChangedCallback` to the `DependencyProperty` registration
+method, but in Perspex it's slightly different (and hopefully easier!)
+
+The field which defines the property is derived from `PerspexProperty` and this
+has a `Changed` observable which is fired every time the property changes on
+*any* object. In addition there is an `AddClassHandler` extension method which
+can automatically route the event to a method on your control.
+
+For example if you want to listen to changes to your control's `Foo` property
+you'd do it like this:
+
+```c#
+    static MyControl()
+    {
+        FooProperty.Changed.AddClassHandler<MyControl>(x => x.FooChanged);
+    }
+
+    private void FooChanged(PerspexPropertyChangedEventArgs e)
+    {
+        // The 'e' parameter describes what's changed.
+    }
+```