Table of Contents

Class ObservableRecipient

Namespace
CommunityToolkit.Mvvm.ComponentModel
Assembly
CommunityToolkit.Mvvm.dll

A base class for observable objects that also acts as recipients for messages. This class is an extension of ObservableObject which also provides built-in support to use the IMessenger type.

public abstract class ObservableRecipient : ObservableObject, INotifyPropertyChanged, INotifyPropertyChanging
Inheritance
ObservableRecipient
Implements
Inherited Members

Constructors

ObservableRecipient()

Initializes a new instance of the ObservableRecipient class.

protected ObservableRecipient()

Remarks

This constructor will produce an instance that will use the Default instance to perform requested operations. It will also be available locally through the Messenger property.

ObservableRecipient(IMessenger)

Initializes a new instance of the ObservableRecipient class.

protected ObservableRecipient(IMessenger messenger)

Parameters

messenger IMessenger

The IMessenger instance to use to send messages.

Exceptions

ArgumentNullException

Thrown if messenger is null.

Properties

IsActive

Gets or sets a value indicating whether the current view model is currently active.

public bool IsActive { get; set; }

Property Value

bool

Messenger

Gets the IMessenger instance in use.

protected IMessenger Messenger { get; }

Property Value

IMessenger

Methods

Broadcast<T>(T, T, string?)

Broadcasts a PropertyChangedMessage<T> with the specified parameters, without using any particular token (so using the default channel).

protected virtual void Broadcast<T>(T oldValue, T newValue, string? propertyName)

Parameters

oldValue T

The value of the property before it changed.

newValue T

The value of the property after it changed.

propertyName string

The name of the property that changed.

Type Parameters

T

The type of the property that changed.

Remarks

You should override this method if you wish to customize the channel being used to send the message (eg. if you need to use a specific token for the channel).

OnActivated()

Invoked whenever the IsActive property is set to true. Use this method to register to messages and do other initialization for this instance.

protected virtual void OnActivated()

Remarks

The base implementation registers all messages for this recipients that have been declared explicitly through the IRecipient<TMessage> interface, using the default channel. For more details on how this works, see the RegisterAll(IMessenger, object) method. If you need more fine tuned control, want to register messages individually or just prefer the lambda-style syntax for message registration, override this method and register manually.

OnDeactivated()

Invoked whenever the IsActive property is set to false. Use this method to unregister from messages and do general cleanup for this instance.

protected virtual void OnDeactivated()

Remarks

The base implementation unregisters all messages for this recipient. It does so by invoking UnregisterAll(object), which removes all registered handlers for a given subscriber, regardless of what token was used to register them. That is, all registered handlers across all subscription channels will be removed.

SetProperty<T>(T, T, Action<T>, bool, string?)

Compares the current and new values for a given property. If the value has changed, raises the PropertyChanging event, updates the property with the new value, then raises the PropertyChanged event. Similarly to the SetProperty<T>(T, T, Action<T>, string?) method, this overload should only be used when SetProperty<T>(ref T, T, string?) can't be used directly.

protected bool SetProperty<T>(T oldValue, T newValue, Action<T> callback, bool broadcast, string? propertyName = null)

Parameters

oldValue T

The current property value.

newValue T

The property's value after the change occurred.

callback Action<T>

A callback to invoke to update the property value.

broadcast bool

If true, Broadcast<T>(T, T, string?) will also be invoked.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

T

The type of the property that changed.

Remarks

This method is just like SetProperty<T>(T, T, Action<T>, string?), just with the addition of the broadcast parameter. As such, following the behavior of the base method, the PropertyChanging and PropertyChanged events are not raised if the current and new value for the target property are the same.

Exceptions

ArgumentNullException

Thrown if callback is null.

SetProperty<T>(T, T, IEqualityComparer<T>, Action<T>, bool, string?)

Compares the current and new values for a given property. If the value has changed, raises the PropertyChanging event, updates the property with the new value, then raises the PropertyChanged event. See additional notes about this overload in SetProperty<T>(T, T, Action<T>, bool, string?).

protected bool SetProperty<T>(T oldValue, T newValue, IEqualityComparer<T> comparer, Action<T> callback, bool broadcast, string? propertyName = null)

Parameters

oldValue T

The current property value.

newValue T

The property's value after the change occurred.

comparer IEqualityComparer<T>

The IEqualityComparer<T> instance to use to compare the input values.

callback Action<T>

A callback to invoke to update the property value.

broadcast bool

If true, Broadcast<T>(T, T, string?) will also be invoked.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

T

The type of the property that changed.

Exceptions

ArgumentNullException

Thrown if comparer or callback are null.

SetProperty<T>(ref T, T, bool, string?)

Compares the current and new values for a given property. If the value has changed, raises the PropertyChanging event, updates the property with the new value, then raises the PropertyChanged event.

protected bool SetProperty<T>(ref T field, T newValue, bool broadcast, string? propertyName = null)

Parameters

field T

The field storing the property's value.

newValue T

The property's value after the change occurred.

broadcast bool

If true, Broadcast<T>(T, T, string?) will also be invoked.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

T

The type of the property that changed.

Remarks

This method is just like SetProperty<T>(ref T, T, string?), just with the addition of the broadcast parameter. As such, following the behavior of the base method, the PropertyChanging and PropertyChanged events are not raised if the current and new value for the target property are the same.

SetProperty<T>(ref T, T, IEqualityComparer<T>, bool, string?)

Compares the current and new values for a given property. If the value has changed, raises the PropertyChanging event, updates the property with the new value, then raises the PropertyChanged event. See additional notes about this overload in SetProperty<T>(ref T, T, bool, string?).

protected bool SetProperty<T>(ref T field, T newValue, IEqualityComparer<T> comparer, bool broadcast, string? propertyName = null)

Parameters

field T

The field storing the property's value.

newValue T

The property's value after the change occurred.

comparer IEqualityComparer<T>

The IEqualityComparer<T> instance to use to compare the input values.

broadcast bool

If true, Broadcast<T>(T, T, string?) will also be invoked.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

T

The type of the property that changed.

Exceptions

ArgumentNullException

Thrown if comparer is null.

SetProperty<TModel, T>(T, T, IEqualityComparer<T>, TModel, Action<TModel, T>, bool, string?)

Compares the current and new values for a given nested property. If the value has changed, raises the PropertyChanging event, updates the property and then raises the PropertyChanged event. The behavior mirrors that of SetProperty<TModel, T>(T, T, IEqualityComparer<T>, TModel, Action<TModel, T>, string?), with the difference being that this method is used to relay properties from a wrapped model in the current instance. For more info, see the docs for SetProperty<TModel, T>(T, T, IEqualityComparer<T>, TModel, Action<TModel, T>, string?).

protected bool SetProperty<TModel, T>(T oldValue, T newValue, IEqualityComparer<T> comparer, TModel model, Action<TModel, T> callback, bool broadcast, string? propertyName = null) where TModel : class

Parameters

oldValue T

The current property value.

newValue T

The property's value after the change occurred.

comparer IEqualityComparer<T>

The IEqualityComparer<T> instance to use to compare the input values.

model TModel

The model

callback Action<TModel, T>

The callback to invoke to set the target property value, if a change has occurred.

broadcast bool

If true, Broadcast<T>(T, T, string?) will also be invoked.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

TModel

The type of model whose property (or field) to set.

T

The type of property (or field) to set.

Exceptions

ArgumentNullException

Thrown if comparer, model or callback are null.

SetProperty<TModel, T>(T, T, TModel, Action<TModel, T>, bool, string?)

Compares the current and new values for a given nested property. If the value has changed, raises the PropertyChanging event, updates the property and then raises the PropertyChanged event. The behavior mirrors that of SetProperty<TModel, T>(T, T, TModel, Action<TModel, T>, string?), with the difference being that this method is used to relay properties from a wrapped model in the current instance. For more info, see the docs for SetProperty<TModel, T>(T, T, TModel, Action<TModel, T>, string?).

protected bool SetProperty<TModel, T>(T oldValue, T newValue, TModel model, Action<TModel, T> callback, bool broadcast, string? propertyName = null) where TModel : class

Parameters

oldValue T

The current property value.

newValue T

The property's value after the change occurred.

model TModel

The model

callback Action<TModel, T>

The callback to invoke to set the target property value, if a change has occurred.

broadcast bool

If true, Broadcast<T>(T, T, string?) will also be invoked.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

TModel

The type of model whose property (or field) to set.

T

The type of property (or field) to set.

Exceptions

ArgumentNullException

Thrown if model or callback are null.