Skip to content

Publish collection-mutation notification

This operation converts the four CollectionBase lifecycle callbacks — insert, clear, remove, and set completion — into a single, uniform ListChanged notification for subscribers of a clsBindableCollectionBase instance. It exists so that a data-bound list control can react to any collection edit through one event rather than four.

Field Value
Operation ID OP-BIND-002
Trigger CollectionBase invokes OnInsertComplete, OnClearComplete, OnRemoveComplete, or OnSetComplete on the subclass after the underlying list mutation finishes.
Inputs Mutation type plus the affected index/value, both supplied by the CollectionBase lifecycle hook.
Outputs ListChanged(this, e) when a subscriber is attached; otherwise no side effect.
Primary components clsBindableCollectionBase.OnInsertComplete, clsBindableCollectionBase.OnClearComplete, clsBindableCollectionBase.OnRemoveComplete, clsBindableCollectionBase.OnSetComplete, clsBindableCollectionBase.OnListChanged
Entry point SAIF.Framework.Bindable\clsBindableCollectionBase.cs

Steps

  1. CollectionBase calls the completion hook that matches the mutation that just finished — the operation never starts on its own; it is always a reaction to a prior insert, clear, remove, or set.
  2. The hook maps itself to the corresponding ListChangedType value:
  3. OnInsertComplete maps to ListChangedType.ItemAdded.
  4. OnClearComplete maps to ListChangedType.Reset.
  5. OnRemoveComplete maps to ListChangedType.ItemDeleted.
  6. OnSetComplete maps to ListChangedType.ItemChanged.
  7. The hook constructs a ListChangedEventArgs instance carrying the mapped change type and the affected index.
  8. For OnClearComplete, the index is always 0, since a full reset has no single affected position.
  9. The hook passes the constructed event arguments to OnListChanged(...).
  10. OnListChanged(...) checks whether the ListChanged event delegate has at least one subscriber.
  11. If a subscriber is attached, it invokes ListChanged(this, e).
  12. If no subscriber is attached, it returns without raising an event and without throwing.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Collection mutation completes]) --> Hook[Enter matching completion hook]
    Hook --> Map[Map hook to ListChangedType]
    Map --> Args[Create ListChangedEventArgs]
    Args --> Check{ListChanged subscriber attached?}
    Check -->|Yes| Raise[Invoke ListChanged(this, e)]
    Check -->|No| NoOp([Return without side effects])
    Raise --> EndOk([Notification delivered])

Failure and edge-case behavior

  • No subscriber attached: OnListChanged(...) exits quietly because it guards the delegate invocation with a null check, the same defensive pattern used in Notify modified-state change.
  • Clear/reset operation: because a reset affects the whole collection rather than one position, the notification always reports index 0 regardless of how many items were removed.

Sources

  • SAIF.Framework.Bindable\clsBindableCollectionBase.cs