Class MutationViewModel<TArgs, TData, TProgress>

Namespace

Fetchling.Mvvm

Assembly

Fetchling.Mvvm.dll

An INotifyPropertyChanged view model wrapping a progress-reporting IMutation<TArgs, TData, TProgress>. Identical to MutationViewModel<TArgs, TData> plus a bindable Progress — bind a progress bar to it.

Progress reports share the latest-wins coalescing every state goes through: a mutator reporting thousands of times per second produces at most one PropertyChanged per dispatcher hop, carrying the newest value, so there is no need to throttle reports for the UI's sake.

The view model holds a live subscription to State for its entire lifetime. Dispose the view model when its page is torn down.

Double-submit protection: ExecuteCommand, Execute(TArgs), and every command returned by ToCommand<TParam>(Func<TParam, TArgs>, Func<TParam, bool>?) read CurrentState directly — not the dispatcher-applied CurrentState below — before starting a run, exactly as MutationViewModel<TArgs, TData> does.

public class MutationViewModel<TArgs, TData, TProgress> : BindableBase, INotifyPropertyChanged, IDisposable

Type Parameters

TArgs

The type of the arguments passed to the mutator.

TData

The type of the data returned on success.

TProgress

The type of the progress values the mutator reports.

Inheritance

object

BindableBase

MutationViewModel<TArgs, TData, TProgress>

Implements

INotifyPropertyChanged

IDisposable

Inherited Members

BindableBase.PropertyChanged

BindableBase.RaisePropertyChanged(string)

BindableBase.SetProperty<T>(ref T, T, string)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

MutationViewModel(IMutation<TArgs, TData, TProgress>, IUiDispatcher?)

Wraps an existing mutation. The view model does not take ownership: Dispose() releases only the view model's own state subscription, and the caller remains responsible for disposing mutation.

public MutationViewModel(IMutation<TArgs, TData, TProgress> mutation, IUiDispatcher? dispatcher = null)

Parameters

mutation IMutation<TArgs, TData, TProgress>

The mutation to wrap.

dispatcher IUiDispatcher

The UI-thread dispatcher. When null, Current is captured; construct the view model on the UI thread or pass a dispatcher explicitly.

MutationViewModel(IQueryClient, MutationOptions<TArgs, TData, TProgress>, IUiDispatcher?)

Creates a new mutation via CreateMutation<TArgs, TData, TProgress>(MutationOptions<TArgs, TData, TProgress>) and wraps it. The view model owns the created mutation and disposes it in Dispose().

public MutationViewModel(IQueryClient client, MutationOptions<TArgs, TData, TProgress> options, IUiDispatcher? dispatcher = null)

Parameters

client IQueryClient

The query client used to create the mutation.

options MutationOptions<TArgs, TData, TProgress>

The mutation options.

dispatcher IUiDispatcher

The UI-thread dispatcher. When null, Current is captured; construct the view model on the UI thread or pass a dispatcher explicitly.

Properties

CancelCommand

Triggers Cancel(). Enabled only while a run is in flight.

public ICommand CancelCommand { get; }

Property Value

ICommand

CurrentState

The raw state snapshot, for bindings and converters that need the whole state.

public MutationState<TData, TProgress> CurrentState { get; }

Property Value

MutationState<TData, TProgress>

Data

The data returned by the most recent successful execution. null until then.

public TData? Data { get; }

Property Value

TData

Error

The exception from the most recent failed execution. null when not in a failure state.

public Exception? Error { get; }

Property Value

Exception

ExecuteCommand

Triggers a run with a object? parameter cast strictly to TArgs. Disabled while a run is already in flight.

public ICommand ExecuteCommand { get; }

Property Value

ICommand

HasData

true when Data is available.

public bool HasData { get; }

Property Value

bool

HasError

true when Error is not null.

public bool HasError { get; }

Property Value

bool

IsFailure

true when the most recent execution failed.

public bool IsFailure { get; }

Property Value

bool

IsIdle

true when the mutation has not yet executed, or has been reset.

public bool IsIdle { get; }

Property Value

bool

IsRunning

true while an execution is in flight.

public bool IsRunning { get; }

Property Value

bool

IsSuccess

true when the most recent execution succeeded.

public bool IsSuccess { get; }

Property Value

bool

Mutation

The wrapped mutation — the escape hatch for members without a bindable counterpart (SetEnabled(bool), or direct Rx composition via Success, Failure, Settled).

public IMutation<TArgs, TData, TProgress> Mutation { get; }

Property Value

IMutation<TArgs, TData, TProgress>

Progress

The latest progress the mutator reported. default before the first report and at the start of every retry; kept after success or failure; cleared when the mutation returns to idle.

public TProgress? Progress { get; }

Property Value

TProgress

Status

The current lifecycle status of the mutation.

public MutationStatus Status { get; }

Property Value

MutationStatus

Methods

Dispose()

Releases the view model's state subscription and disposes the wrapped mutation if this view model created it.

public void Dispose()

Dispose(bool)

Releases resources. Override in derived view models to dispose additional state; always call the base implementation.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true when called from Dispose().

Execute(TArgs)

Triggers a run with args, unless CurrentState already reports Running.

public void Execute(TArgs args)

Parameters

args TArgs

The arguments to pass to the mutator.

ToCommand(Func<TArgs>, Func<bool>?)

Wraps this mutation as a parameterless command whose arguments come from args. Behaves exactly like ToCommand(Func<TArgs>, Func<bool>?).

public IMutationCommand ToCommand(Func<TArgs> args, Func<bool>? canExecute = null)

Parameters

args Func<TArgs>

Produces the mutator's arguments at the moment the command executes.

canExecute Func<bool>

An additional predicate. When null, only the running gate applies.

Returns

IMutationCommand

ToCommand<TParam>(Func<TParam, TArgs>, Func<TParam, bool>?)

Wraps this mutation as a command whose parameter is TParam, mapped to TArgs via map. Behaves exactly like ToCommand<TParam>(Func<TParam, TArgs>, Func<TParam, bool>?).

public IMutationCommand ToCommand<TParam>(Func<TParam, TArgs> map, Func<TParam, bool>? canExecute = null)

Parameters

map Func<TParam, TArgs>

Maps the command parameter to the mutator's arguments.

canExecute Func<TParam, bool>

An additional predicate evaluated with the command parameter. When null, only the running gate applies.

Returns

IMutationCommand

Type Parameters

TParam

Events

StateChanged

Raised on the UI thread after every PropertyChanged notification for an applied state.

public event EventHandler? StateChanged

Event Type

EventHandler