How to support an Event

"Life is a sequence of events whether you perceive those events as good or bad is your choice, but it is in a sequence." - Jeremy Limn.

On Silverlight, events allow code behind to react to changes in a control state. This guide will show how to add support for a given event on a component.

This guide builds up on the How to implement a component guide. It assumes that basic support for Slider control is already implemented on WebMAP Silverlight packages repository.

Source Code

The source code for the legacy Silverlight example and migrated application used through this guide is available on the resources section.

ValueChanged event example

Lets begin with a Slider example (SliderTest), which uses the ValueChanged event to update the text in a TextBox. The Silverlight application looks like this:

The application starts with a "Value has not changed" text on the TextBox. When the user moves the slider, the text changes to "Value is positive" or "Value is negative", depending on the slider position to the left or to the right. Note that the text change occurs immediately when the user moves the slider.

In the C# code the slider_ValueChanged() function (the handler) is the one that changes the Text value on the TextBox:

MainPage.xaml.cs

...
public partial class MainPage : UserControl
{
    ...
    private void slider_ValueChanged(object sender, RoutedPropertyChangedEventArgs<double> e)
    {
        if (e.NewValue > 0)
        {
            textBox.Text = "Value is positive";
        }
        else if (e.NewValue < 0)
        {
            textBox.Text = "Value is negative";
        }
        else
        {
            textBox.Text = "Value is zero";
        }
    }
}
...

On XAML the slider_ValueChanged() function is added into ValueChange event:

MainPage.xaml

<UserControl ...>
    ...
    <Slider x:Name="slider"
            ...
            ValueChanged="slider_ValueChanged"
            />
    ...
</UserControl>

This means that every time that Value changes on the slider, slider_ValueChanged() will be called, and the text on the TextBox will be updated.

Migrated application

When the SliderTest code is initially migrated, Slider will be a stub, because there is no slider support on the migrator. The ValueChanged information on the XAML will also be lost during migration.

MainPage.component.html

<wm-user-control ...>
      ...
      <stub-wm-slider
            class='slider'
            [height]="24"
            [width]="100"
            [model]='model.slider'
            wmGrid
            #gridItem>
      </stub-wm-slider>
      ...
</wm-user-control>

On the MainPage model the slider will also be a stub. The handler function is there, it was not lost, but no one is going to call it, so the text on the TextBox never changes.

MainPage.ts

import { Stub_System_Windows_Controls_Slider} from "stubs";
...
export class MainPage extends UserControlModel {
   ...
   private slider_ValueChanged (sender : any,e : RoutedPropertyChangedEventArgs <number>) : void {
      if (e.newValue > 0) {
         this.textBox.Text = "Value is positive";
      } else if (e.newValue < 0) {
         this.textBox.Text = "Value is negative";
      } else {
         this.textBox.Text = "Value is zero";
      }
   }
   ...
   protected loadModels () {
      ...
      this.slider = withName(new Stub_System_Windows_Controls_Slider (),"slider");
      ...
   }
   ...
   public slider : Stub_System_Windows_Controls_Slider = null;
   ...
}

There is already a basic slider model and component on wms-framework and i-component (if you don't see a slider model and component, you need to follow this guide). Let's change the migrated application to use the basic slider:

MainPage.component.html

<wm-user-control ...>
    ...
    <wm-slider
        class='slider'
        [height]="24"
        [width]="100"
        [horizontalAlignment]='"Left"'
        [verticalAlignment]='"Top"'
        [minimum]="-1"
        [maximum]="1"
        [model]='model.slider'
        wmGrid
        #gridItem>
    </wm-slider>
    <!-- <stub-wm-slider class='slider' [height]="24" [width]="100" [model]='model.slider' wmGrid #gridItem>
    </stub-wm-slider> -->
    ...
</wm-user-control>

MainPage.ts

import { ..., SliderModel } from "@mobilize/wms-framework";
//import { Stub_System_Windows_Controls_Slider} from "stubs";
...
export class MainPage extends UserControlModel {
   ...
   protected loadModels () {
      ...
      this.slider = withName(new SliderModel(),"slider");
      ...
   }
   ...
   public slider : SliderModel = null;
   ...
}

Build the migrated application and run it.

As expected, the text on the TextBox does not change. ValueChanged event support must be added in the slider model and component.

Model event support

In Silverlight, the ValueChanged event is defined on RangeBase. To add support for ValueChange event on the slider model, open RangeBaseModel from wms-framework and add a ValueChange property:

RangeBaseModel.ts

...
import { SubscriptionEvent } from '../../utils/SubscriptionEvent';
import {
  RoutedPropertyChangedEventArgs
} from '../events/RoutedPropertyChangedEventArgs';
export class RangeBaseModel extends Control {
  ...
  ValueChanged = new SubscriptionEvent<(s: any, a: RoutedPropertyChangedEventArgs<number>) => void>();
  ...
}

A C# event is migrated into a SubscriptionEvent. Take a look at the signature of the generic type variable on the SubscriptionEvent declaration: it is the same signature of the handler on MainPage.

// MainPage.ts
private slider_ValueChanged(sender: any, e: RoutedPropertyChangedEventArgs <number>): void {
  ...
}

// RangeBaseModel.ts
ValueChanged = new SubscriptionEvent<(s: any, a: RoutedPropertyChangedEventArgs<number>) => void>();

The ValueChanged subscription event must be fired when Value is changed. This can be done on the Value setter:

RangeBaseModel.ts

...
export class RangeBaseModel extends Control {
  ...
  set Value(value: number) {
    const oldValue = this._value;
    this._value = value;
    this.ValueChanged.fire([
      this,
      new RoutedPropertyChangedEventArgs(oldValue, value)
    ]);
  }
  ...
}

On line 7 the ValueChanged subscription even is fired, with this as first argument (the sender), and a new RoutedPropertyChangedEventArgs object as second argument (the event arguments). Note that RoutedPropertyChangedEventArgs constructor requires the old and new values, that is the reason why the old value was saved on line 5.

Build wms-framework and copy it into i-components, so that the changes on RangeBaseModel can be used on the slider component.

Component event support

To support event binding from the HTML template on the migrated application, an Angular output property must be declared on the slider component class:

slider.component.ts

import {
  ...
  EventEmitter,
  Output
} from '@angular/core';
import {
  ...
  RoutedPropertyChangedEventArgs,
  ...
} from '@mobilize/wms-framework';
...
export class SliderComponent extends BaseComponent implements OnInit {
  @Output()
  valueChanged = new EventEmitter<(s: any, a: RoutedPropertyChangedEventArgs<number>) => void>();
  ...
}

Again pay attention to the signature of the generic type variable on the valueChange event emitter declaration: it is the same signature used on ValueChange subscription event on RangeBaseModel, and it is the same signature of the handler function on MainPage.

This Angular output will allow HTML event bindings on a slider component, something like this:

<wm-slider (valueChanged)="function($event.sender,$event.e)">
</wm-slider>

Now the Angular event emitter must be connected with the subscription event on the model. BaseComponent provides a utility to accomplish this, which we can call on the ngOnInit() function:

slider.component.ts

...
export class SliderComponent extends BaseComponent implements OnInit {
  ...
  ngOnInit(): void {
    this.model = this.model || new SliderModel();
    this.setupModel(this.model);
    this.registerObservers(this.valueChanged, this.model, this.model.ValueChanged);
    super.ngOnInit();
  }
  ...
}

On line 7 registerObservers() is called with the Angular event emitter (valueChanged), the model, and the subscription event (model.ValueChanged) as parameters. registerObservers() will take any observer currently registered on the angular event emitter and subscribe it on the model's subscription event. The practical effect is that anything registered on valueChanged in the component will be called when ValueChanged is fired on the model.

Build i-components and copy it into the migrated application to use the new valueChange event support.

Back to migrated application

Now that slider has support for valueChanged event, the only thing to do is recover the information lost during migration. Open MainPage template on the migrated application and add the binding between the event and the handler function:

MainPage.component.html

<wm-user-control ...>
   ...
   <wm-slider
      ...
      (valueChanged)="model.slider_ValueChanged($event.sender,$event.e)"
      ...
      >
   </wm-slider>
   ...
</wm-user-control>

Note that slider_ValueChanged() (the handler) is called through the model, and that $event.sender (the sender) and $event.e (the event arguments) are sent as arguments.

Rebuild the migrated application and test the changes:

Excellent! The slider model and component now have a functional support for ValueChanged event.

Resources

PreviousHow to implement a component NextHow to support Bindings

Last updated 3 years ago

Was this helpful?