Skip to content

Add a new item through IBindingList

This operation is clsBindableCollectionBase's explicit IBindingList.AddNew() implementation. It exists to let a data-bound grid or list request a new row while still letting the collection owner forbid that action entirely: the collection's AllowNew flag decides whether the request proceeds at all, and the actual creation logic is left to the subclass-overridable OnAddNew() hook.

Field Value
Operation ID OP-BIND-003
Trigger Caller invokes IBindingList.AddNew().
Inputs None.
Outputs Object returned by OnAddNew(), or InvalidOperationException when new items are disallowed.
Primary components clsBindableCollectionBase.IBindingList.AddNew, clsBindableCollectionBase.OnAddNew
Entry point SAIF.Framework.Bindable\clsBindableCollectionBase.cs

Steps

  1. A caller (typically a bound control) invokes the explicit IBindingList.AddNew() implementation.
  2. The method reads the protected AllowNew flag to decide whether item creation is permitted for this collection instance.
  3. If AllowNew is true, the method calls the virtual OnAddNew() hook to obtain the new item.
  4. If the subclass has overridden OnAddNew(), the override's creation logic runs.
  5. If not overridden, the base implementation returns null.
  6. The method returns whatever OnAddNew() produced to the caller.
  7. If AllowNew is false, the method throws InvalidOperationException("Allow New Not Supported for this object") instead of calling OnAddNew() at all.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Caller invokes IBindingList.AddNew]) --> Check{AllowNew is true?}
    Check -->|Yes| Add[Call OnAddNew()]
    Check -->|No| Err([Throw InvalidOperationException])
    Add --> EndOk([Return created object])

Failure and edge-case behavior

  • AllowNew is false: the method throws InvalidOperationException("Allow New Not Supported for this object") before any creation logic runs.
  • AllowNew is true but the subclass does not override OnAddNew(): the base hook returns null, and that null value is returned to the caller as if it were a valid new item — callers should not assume a non-null result.

Sources

  • SAIF.Framework.Bindable\clsBindableCollectionBase.cs