Class ViewModelBase<T, THs>

public abstract class ViewModelBase<T, THs> : PropertyMonitor, IViewModel, INotifyPropertyChanged, INotifyPropertyChanging where T : class, IViewModelInjection<THs> where THs : IHostServices

Type Parameters

Name	Description
T	The type of injection parameters for the view model. Must implement IViewModelInjection<T> and be a reference type.
THs	The type of services passed from the host application. Must implement IHostServices.

Remarks

This is the base class for all view models used by the editor and provides the bare minimum in functionality. This object already implements the INotifyPropertyChanged and the INotifyPropertyChanging interfaces to allow communication with a view.

Common services used by the application, such as a message display service, content plug in service, etc... are provided through the HostServices property so that custom view models can use standardized functionality to communicate with the user should the need arise.

When implementing a view model, the developers should set up their properties like this:

public ReturnType PropertyName
{
    get => _backingStoreValue;
    set
    {
        // Always check to see if the value has changed. This keeps the view model from being too "chatty" with the UI.
        if (_backingStoreValue == value)
        {
            return;
        }
    // Notify that the property is about to change. This allows the view to do any necessary clean up prior to updating the visual side.
    OnPropertyChanging();
    _backingStoreValue = value;
    // Now, notify that the property has changed. The view will intercept the change and update the visual associated with the property.
    OnPropertyChanged();
}

}

This setup notifies the view that the property has been updated, and that any associated visual should probably update as well. This is the most common pattern to use, however there will be times when a property notification is required from a method. If that is the case, the NotifyPropertyChanged(string), and NotifyPropertyChanging(string) methods should be used like this:

private void DoCommandAction()
{
    NotifyPropertyChanging(nameof(ReadOnlyValue));
    _readOnlyValue++;
    NotifyPropertyChanged(nameof(ReadOnlyValue));
}

The difference being that for properties, you do not need to specify the name of the property being updated, and in methods you do.

The view model is also equipped with several events that are used to notify the application that a long running operation is executing. Applications can intercept these events and display a progress panel, or "please wait" panel. These should only be used with asynchronous operations as they will not update correctly if everything is running on the same thread.

Constructors

| Edit this page View Source

ViewModelBase()

Initializes a new instance of the ViewModelBase<T, THs> class.

Declaration

protected ViewModelBase()

Properties

| Edit this page View Source

HostServices

Property to return the services passed in from the host application.

Declaration

protected THs HostServices { get; }

Property Value

Type	Description
THs

Methods

| Edit this page View Source

HideProgress()

Function to hide the progress overlay panel on the view, if the view supports it.

Declaration

protected void HideProgress()

HideWaitPanel()

Function to deactivate an active wait panel overlay on the view, if the view supports it.

Declaration

protected void HideWaitPanel()

Initialize(T)

Function to inject dependencies for the view model.

Declaration

public void Initialize(T injectionParameters)

Parameters

Type	Name	Description
T	injectionParameters	The parameters to inject.

Remarks

Applications should call this when setting up the view model for complex operations and/or dependency injection. The constructor should only be used for simple set up and initialization of objects.

This method is only ever called after the view model has been created, and never again during the lifetime of the view model.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `injectionParameters` parameter is null.

Load()

Function called when the associated view is loaded.

Declaration

public void Load()

Remarks

This method should be overridden when there is a need to set up functionality (e.g. events) when the UI first loads with the view model attached. Unlike the Initialize(T) method, this method may be called multiple times during the lifetime of the application.

Anything that requires tear down should have their tear down functionality in the accompanying Unload() method.

OnInitialize(T)

Function to inject dependencies for the view model.

Declaration

protected abstract void OnInitialize(T injectionParameters)

Parameters

Type	Name	Description
T	injectionParameters	The parameters to inject.

Remarks

Applications should call this when setting up the view model for complex operations and/or dependency injection. The constructor should only be used for simple set up and initialization of objects.

This method is only ever called after the view model has been created, and never again during the lifetime of the view model.

OnLoad()

Function called when the associated view is loaded.

Declaration

protected virtual void OnLoad()

Remarks

Anything that requires tear down should have their tear down functionality in the accompanying Unload() method.

OnUnload()

Function called when the associated view is unloaded.

Declaration

protected virtual void OnUnload()

Remarks

This method is used to perform tear down and clean up of resources.

ShowWaitPanel(WaitPanelActivateArgs)

Function to activate a wait overlay panel on the view, if the view supports it.

Declaration

protected void ShowWaitPanel(WaitPanelActivateArgs args)

Parameters

Type	Name	Description
WaitPanelActivateArgs	args	The event message arguments.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `args` parameter is null.

ShowWaitPanel(string, string)

Function to activate a wait overlay panel on the view, if the view supports it.

Declaration

protected void ShowWaitPanel(string message, string title = null)

Parameters

Type	Name	Description
string	message	The message for the wait overlay.
string	title	[Optional] The title for the overlay.

Unload()

Function called when the associated view is unloaded.

Declaration

public void Unload()

Remarks

This method is used to perform tear down and clean up of resources.

UpdateMarequeeProgress(string, string, Action)

Function to activate and/or update the progress panel overlay on the view as a marquee progress meter, if the view supports it.

Declaration

protected void UpdateMarequeeProgress(string message, string title = null, Action cancelAction = null)

Parameters

Type	Name	Description
string	message	The message to display.
string	title	[Optional] The title for the panel.
Action	cancelAction	[Optional] The action to execute if the operation is cancelled.

UpdateProgress(ProgressPanelUpdateArgs)

Function to activate and/or update the progress panel overlay on the view, if the view supports it.

Declaration

protected void UpdateProgress(ProgressPanelUpdateArgs args)

Parameters

Type	Name	Description
ProgressPanelUpdateArgs	args	The event message arguments.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `args` parameter is null.

UpdateProgress(string, float, string, Action)

Function to activate and/or update the progress panel overlay on the view, if the view supports it.

Declaration

protected void UpdateProgress(string message, float percentage, string title = null, Action cancelAction = null)

Parameters

Type	Name	Description
string	message	The message to display.
float	percentage	The percentage complete as a normalized value (0..1).
string	title	[Optional] The title for the panel.
Action	cancelAction	[Optional] The action to execute if the operation is cancelled.

Events

| Edit this page View Source

ProgressDeactivated

Event triggered when the progress overlay should be deactivated.

Declaration

public event EventHandler ProgressDeactivated

Event Type

Type	Description
EventHandler

ProgressUpdated

Event triggered when the progress overlay panel over needs to be updated.

Declaration

public event EventHandler<ProgressPanelUpdateArgs> ProgressUpdated

Event Type

Type	Description
EventHandler<ProgressPanelUpdateArgs>

WaitPanelActivated

Event triggered when a wait overlay panel needs to be activated.

Declaration

public event EventHandler<WaitPanelActivateArgs> WaitPanelActivated

Event Type

Type	Description
EventHandler<WaitPanelActivateArgs>

WaitPanelDeactivated

Event triggered when a wait overlay panel needs to be deactivated.

Declaration

public event EventHandler WaitPanelDeactivated

Event Type

Type	Description
EventHandler

Implements

IViewModel

INotifyPropertyChanged

INotifyPropertyChanging

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)

Class ViewModelBase<T, THs>

Inheritance

Implements

Inherited Members

Namespace: Gorgon.Editor.UI

Assembly: Gorgon.Editor.API.dll

Syntax

Type Parameters

Remarks

Constructors

ViewModelBase()

Declaration

See Also

Properties

HostServices

Declaration

Property Value

See Also

Methods

HideProgress()

Declaration

See Also

HideWaitPanel()

Declaration

See Also

Initialize(T)

Declaration

Parameters

Remarks

Exceptions

See Also

Load()

Declaration

Remarks

See Also

OnInitialize(T)

Declaration

Parameters

Remarks

See Also

OnLoad()

Declaration

Remarks

See Also

OnUnload()

Declaration

Remarks

See Also

ShowWaitPanel(WaitPanelActivateArgs)

Declaration

Parameters

Exceptions

See Also

ShowWaitPanel(string, string)

Declaration

Parameters

See Also

Unload()

Declaration

Remarks

See Also

UpdateMarequeeProgress(string, string, Action)

Declaration

Parameters

See Also

UpdateProgress(ProgressPanelUpdateArgs)

Declaration

Parameters

Exceptions

See Also

UpdateProgress(string, float, string, Action)

Declaration

Parameters

See Also

Events

ProgressDeactivated

Declaration

Event Type

See Also

ProgressUpdated