Property System
Overview
Section titled “Overview”MewUI’s property system plays a role similar to WPF’s DependencyProperty, but it has been redesigned around these goals:
| WPF | MewUI |
|---|---|
DependencyProperty |
MewProperty<T> |
DependencyObject |
MewObject |
DependencyPropertyKey |
MewPropertyKey<T> |
PropertyMetadata |
MewPropertyOptions (flag enum) + callback parameters |
| Reflection-based binding | Delegate-based, no Reflection |
Design principles:
- Native AOT compatibility: works without Reflection or runtime code generation
- Minimal allocation:
PropertyValueStoreis created lazily only when a property is actually used - Value-comparison optimization: setting the same value again skips change notification
Declaring Properties
Section titled “Declaring Properties”Basic pattern
Section titled “Basic pattern”Declare properties as static readonly fields and wrap them with CLR properties:
public static readonly MewProperty<bool> IsVisibleProperty = MewProperty<bool>.Register<UIElement>(nameof(IsVisible), true, MewPropertyOptions.AffectsRender | MewPropertyOptions.AffectsLayout);
public bool IsVisible{ get => GetValue(IsVisibleProperty); set => SetValue(IsVisibleProperty, value);}Register<TOwner> signature:
public static MewProperty<T> Register<TOwner>( string name, // Property name, used for diagnostics T defaultValue, // Default value MewPropertyOptions options = MewPropertyOptions.None, Action<TOwner, T, T>? changed = null, // Change callback (owner, oldValue, newValue) Func<TOwner, T, T>? coerce = null, // Coerce callback (owner, proposed) => stored Action<TOwner, T>? validate = null // Validation callback (owner, proposed); throw to reject)Properties with change callbacks
Section titled “Properties with change callbacks”Register a changed callback for properties that need side effects.
The callback receives the owner type-safely cast to TOwner:
public static readonly MewProperty<Element?> ContentProperty = MewProperty<Element?>.Register<Button>(nameof(Content), null, MewPropertyOptions.AffectsLayout, static (self, oldValue, newValue) => { if (oldValue != null) oldValue.Parent = null; if (newValue != null) newValue.Parent = self; });Properties with coerce callbacks
Section titled “Properties with coerce callbacks”The coerce callback runs before a proposed value is stored and can normalize it.
It applies to every value source: local values, styles, and triggers.
public static readonly MewProperty<double> ValueProperty = MewProperty<double>.Register<Slider>(nameof(Value), 0.0, MewPropertyOptions.AffectsRender, coerce: static (self, proposed) => Math.Clamp(proposed, self.Minimum, self.Maximum));When external state used by the coercion rule changes, call CoerceValue to request reevaluation:
// Example: re-coerce CanMaximize when resizability changesCoerceValue(CanMaximizeProperty);Properties with validate callbacks
Section titled “Properties with validate callbacks”The validate callback is a pre-commit veto. It runs just before the value is stored, after coerce, and only for writes that pass the priority guard and are not same-value no-ops. Throwing from it rejects the set with no state change: nothing is stored and no change notifications fire. Unlike coerce, it also runs for null.
public static readonly MewProperty<Element?> ChildProperty = MewProperty<Element?>.Register<Border>(nameof(Child), null, MewPropertyOptions.AffectsLayout, validate: static (self, value) => self.ValidateLogicalChild(value, allowTransfer: true));Use it to reject an invalid assignment before it takes effect, for example an element that already belongs to another logical parent. Because the veto runs before storage, the value store and the side effects of changed callbacks (such as tree mutation) stay consistent.
Read-only properties
Section titled “Read-only properties”State properties that should not be set externally, such as IsFocused or IsMouseOver, are registered with RegisterReadOnly.
Keep the returned MewPropertyKey<T> private and expose only Key.Property publicly:
private static readonly MewPropertyKey<bool> IsFocusedPropertyKey = MewProperty<bool>.RegisterReadOnly<UIElement>(nameof(IsFocused), false, MewPropertyOptions.AffectsVisualState);
public static MewProperty<bool> IsFocusedProperty => IsFocusedPropertyKey.Property;
public bool IsFocused => GetValue(IsFocusedProperty);
// Owner-internal only:internal void SetFocused(bool value) => SetValue(IsFocusedPropertyKey, value);Read-only properties:
- throw
InvalidOperationExceptionfrom normalSetValue(MewProperty<T>, T)calls - cannot be binding targets and throw the same exception from
SetBinding - can only be set through the
SetValue(MewPropertyKey<T>, T)overload
Inherited properties
Section titled “Inherited properties”Properties whose values flow from parent to child:
public static readonly MewProperty<Color> ForegroundProperty = MewProperty<Color>.Register<Control>(nameof(Foreground), Color.Black, MewPropertyOptions.AffectsRender | MewPropertyOptions.Inherits);MewPropertyOptions
Section titled “MewPropertyOptions”MewPropertyOptions is a flag enum that controls property behavior:
| Flag | Effect |
|---|---|
None |
No special behavior |
AffectsRender |
Calls InvalidateVisual() when the value changes |
AffectsLayout |
Calls InvalidateMeasure() when the value changes |
Inherits |
Looks up the parent chain when there is no local/style value |
BindsTwoWayByDefault |
Makes SetBinding() / Bind() default to TwoWay |
AffectsVisualState |
Calls InvalidateVisualState() when the value changes. This queues visual-state recomputation at the start of the next layout/render pass. Use it for properties read by ComputeVisualState, such as IsEnabled, IsMouseOver, IsFocused, and IsPressed. |
Flags can be combined:
// Affects rendering + inherits from parentMewPropertyOptions.AffectsRender | MewPropertyOptions.InheritsAutomatic invalidation
Section titled “Automatic invalidation”UIElement.OnMewPropertyChanged checks the flags and performs invalidation automatically, so control code rarely needs to call InvalidateMeasure() or InvalidateVisual() manually.
Value Resolution Priority
Section titled “Value Resolution Priority”Property values are resolved in the following priority order. Higher entries win:
1. Local <- SetValue() / CLR property setter (user-explicit value)2. Animated <- Animation system (interpolated value updated each frame)3. Trigger <- StateTrigger Setter (when a state condition matches)4. Style <- Style base Setter5. Inherited <- Resolved through the parent chain when the Inherits flag is set6. Default <- Default value passed to Register(), including type-specific overrides- When a Local value exists, trigger/style setters are ignored for that property, matching WPF behavior.
- Animated values sit below Local, so animations do not override user-explicit values.
- Trigger values override the same property’s Style base setter. When a trigger no longer matches, that source value is cleared and the style base value is restored.
- Inherited values have higher priority than Default. Inherited values are resolved through the parent chain and cached; when the parent changes, the cache is invalidated and resolved again on the next lookup.
Internally, writes from lower-priority sources are ignored. For example, if a property has a local value, attempts by a style setter to write that property are rejected before storage.
Note: there is currently no public API for clearing a local value and returning to the style/default value.
The value store (PropertyValueStore) and its ClearLocal operation are internal and are used only by the framework, such as when clearing triggers or restoring animation values.
Default Value Overrides
Section titled “Default Value Overrides”Derived types can change the default value of an existing property. This must be done from the static constructor:
public sealed class ProgressBar : RangeBase{ static ProgressBar() { // Change RangeBase.Maximum's default value (double.MaxValue) to 100 MaximumProperty.OverrideDefaultValue<ProgressBar>(100.0);
// Change FrameworkElement.Height's default value to 10 HeightProperty.OverrideDefaultValue<ProgressBar>(10.0); }}Default lookup starts from the most-derived type and walks upward. The first override found is used:
ProgressBar -> RangeBase -> Control -> FrameworkElement -> UIElement -> ... ^ Use the overridden value if found hereProperty Inheritance
Section titled “Property Inheritance”Properties with the MewPropertyOptions.Inherits flag look up the parent chain when the object has no value of its own.
How it works
Section titled “How it works”// Inside MewObject.GetValue:if (PropertyStore.HasOwnValue(property.Id) || !property.Inherits) return PropertyStore.GetValue(property);
return ResolveInheritedValue(property);ResolveInheritedValue is a virtual method that returns the default value in MewObject.
Element, which participates in the visual tree, overrides it to walk the parent chain.
If it finds the first ancestor with a value, that value is used; otherwise the type-specific default is used.
The resolved inherited value is cached in the store without change notification. When the parent changes, caches originating from the previous parent chain are invalidated. When the value of an inherited property changes, the change propagates through the descendant tree. If a descendant has its own value, such as a local/trigger/style value, propagation stops for that subtree.
Common inherited properties
Section titled “Common inherited properties”The font-related properties on Control are inherited:
Foreground, FontFamily, FontSize, and FontWeight.
This lets a top-level font setting automatically apply to every child control:
new StackPanel() .FontSize(14) // Applies to every control under this panel .FontFamily("Pretendard") .Children( new Label().Text("Inherited font"), new Button().Content("Inherited font"), new TextBox() // Also Pretendard 14 )Change Notification Pipeline
Section titled “Change Notification Pipeline”When a property’s value actually changes, processing happens in this order:
SetValue / SetStyle / SetTrigger -> reject if a higher-priority source already owns the value -> apply coerce callback (skipped for null) -> stop here if the value is equal (skip notification) -> run validate callback (pre-commit veto; throwing rejects with no state change) -> stop any running animation -> store the value, then:
1. OnMewPropertyChanged(property) <- virtual, cross-cutting handling |-- AffectsLayout -> InvalidateMeasure() |-- AffectsRender -> InvalidateVisual() |-- AffectsVisualState -> InvalidateVisualState() `-- Inherits -> propagate to descendant tree
2. Property Forwards <- property-to-property forwarding (weak-reference targets)3. Binding Callbacks <- ObservableValue synchronization4. changed(owner, oldValue, newValue) <- callback registered by Register()Avoiding same-value updates
Section titled “Avoiding same-value updates”Local value assignment compares the new value with the existing value using EqualityComparer<T>.Default.
If the values are equal, it returns without even boxing.
Other paths also skip notification if the value is equal immediately before storage.
This prevents unnecessary layout/render invalidation and infinite invalidation loops.
Binding Integration
Section titled “Binding Integration”MewProperty can bind directly to ObservableValue<T> or to another MewObject property:
var fontSize = new ObservableValue<double>(14);
// MewProperty <-> ObservableValue bindingelement.SetBinding(FontSizeProperty, fontSize);
// Binding with type conversionvar count = new ObservableValue<int>(0);element.SetBinding(FontSizeProperty, count, convert: c => 12.0 + c, convertBack: fs => (int)(fs - 12));
// Property-to-property bindingchild.SetBinding(PaddingProperty, parent, PaddingProperty);Rules:
- The default mode is
property.BindsTwoWayByDefault ? TwoWay : OneWay. - Conversion bindings are downgraded to
OneWaywhen the requested mode isTwoWaybutconvertBackis missing. - Rebinding the same property disposes the previous binding first.
ClearBinding(property)removes only the binding and preserves the current value.- Read-only properties cannot be binding targets.
- In property-to-property binding, source changes are written to the target’s Style tier. If the target has a local value, the local value still wins.
See the Binding document for more details.
Animation Integration
Section titled “Animation Integration”Animated values are not handled as a separate value tier in storage. Instead, they use a wrapper.
When an animation starts, the entry’s value is wrapped in an AnimatedEntry, preserving the existing base value and its source.
Each frame updates the interpolated value:
- Each frame:
SetAnimatedValue(propertyId, value)(internal API) - On completion:
ClearAnimatedValue(propertyId)restores the preserved base value and source - If
SetValuearrives from any source while an animation is running, the animation is stopped and the new value is stored
Effectively, Animated resolves below Local and above Trigger/Style. Style transitions run on top of this mechanism.
Implementation Notes
Section titled “Implementation Notes”PropertyValueStoreholds a weak reference to its owner and a strong reference only to the owner type for type-specific default-value resolution.- The store starts as a sparse property-id-based array for up to 8 entries, then promotes to a dense array only for elements that actually use many properties. This keeps
GetValue/SetValueO(1) for heavily styled controls. - To reduce boxing on the style/trigger hot path, small ints (-1..8) and doubles 0.0 / 1.0 reuse cached boxes.
- Property-to-property forward targets are stored as weak references and are automatically removed from the forwarding list when the target is collected.