Providing Property Change Notification

WFC uses a naming convention for creating events that indicate that a property value is changing or has changed:

• The <propertyName>Changing event indicates that the function used to change a property value has been called. Typically, you fire this event at the beginning of your set<Property> method. You pass it a CancelEvent object; if the host application has a <propertyName>Changing event handler, the handler can prevent the property from being changed by setting the CancelEvent object's cancel property to true.
  
  
• To indicate a successfully completed change, you fire a <propertyName>Changed event.

Note   Data binding requires that you implement the <propertyName>Changed event.

These events are not designed to provide data validation, but rather to allow control over properties being edited, such as preventing a control from updating its value. Data validation is either done on the data source (for example, a recordset) or through custom properties on the control.

You implement the property change events the way you do a custom event. For each event, you provide an addOn<property>Changing and addOn<property>Changed method and corresponding removeOn methods. You also typically create protected on<PropertyName>Changing and on<PropertyName>Changed methods. The on<PropertyName>Changing usually uses a CancelEvent object to allow the change to be stopped. For details about creating these methods, see Creating a Custom Event.

The following example illustrates how you can include property notification for an alignment property:

public void setAlignment(int value) {
   if (alignment != value) {
         CancelEvent e = new CancelEvent();
         onAlignmentChanging(e);
         if (!e.cancel) {
            alignment = value;
            invalidate();   // Repaint control when property changes
            onAlignmentChanged(Event.EMPTY);
         }
      }
   }
}

private EventHandler eAlignChanged = null;
public final void addOnAlignmentChanged(EventHandler handler){
   eAlignChanged = (EventHandler)Delegate.combine(eAlignChanged,
       handler);
}
public final void removeOnAlignmentChanged(EventHandler handler){
   eAlignChanged = (EventHandler)Delegate.remove(eAlignChanged, handler);
}
protected void onAlignmentChanged(Event event){
   if(eAlignChanged != null){
      eAlignChanged.invoke(this, event);
   }
}

private CancelEventHandler eAlignChanging = null;
public final void addOnAlignmentChanging(CancelEventHandler handler){
   eAlignChanging = (CancelEventHandler)Delegate.combine(eAlignChanging,
       handler);
}
public final void removeOnAlignmentChanging(CancelEventHandler handler){
   eAlignChanging = (CancelEventHandler)Delegate.remove(eAlignChanging,
       handler);
}
protected void onAlignmentChanging(CancelEvent event){
   if(eAlignChanging != null){
      eAlignChanging.invoke(this, event);
   }
}

public static EventInfo eiAlignChanged = new EventInfo(MyControl.class, 
   "onAlignmentChanged", EventHandler.class);
public static EventInfo eiAlignChanging = new EventInfo(MyControl.class, 
   "onAlignmentChanging", EventHandler.class);

public void getEvents(IEvents events){
   super.getEvents(events);
   events.add(eiAlignChanged);
   events.add(eiAlignChanging);
}