---
title: Add a new item through IBindingList
summary: Implements the AddNew entry point by checking AllowNew and delegating item creation to the subclass hook.
status: draft
owner: SAIF Team
last_reviewed: 2026-07-30
library: SAIF.Framework.Bindable
reference_type: package
operation_id: OP-BIND-003
trigger: Caller invokes IBindingList.AddNew()
---

# 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.
   - If the subclass has overridden `OnAddNew()`, the override's creation logic runs.
   - If not overridden, the base implementation returns `null`.
4. The method returns whatever `OnAddNew()` produced to the caller.
5. 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.

```mermaid
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.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `SAIF.Framework.Bindable\clsBindableCollectionBase.cs`