Table of Contents

Class Model

Namespace
Qt.Bridge.Models
Assembly
Qt.Bridge.CSharp.Api.dll

Represents a C# data model that can be consumed by views and delegates.

public abstract class Model
Inheritance
Model
Derived
Inherited Members

Remarks

Use Model when you need full control over how items are arranged, including hierarchical data or custom parent-child relationships. For common flat shapes, prefer ListModel or TableModel, which provide specialized base behavior for one-dimensional and row/column data.

Subclasses describe the shape of the data and expose values by overriding methods such as RowCount(ModelIndex), ColumnCount(ModelIndex), Index(int, int, ModelIndex), Parent(ModelIndex), and Data(ModelIndex, int). Optional capabilities such as editing, sorting, or loading data on demand are enabled by overriding the corresponding virtual methods.

Structural changes must be announced with matching protected begin/end calls. Call the relevant Begin* helper before mutating the backing storage, then call the matching End* helper immediately after the model modification completes. For in-place value updates, call DataChanged(ModelIndex, ModelIndex, int[]) or HeaderDataChanged(int, int, int) instead of a structural notification.

Once a Begin* helper has been called successfully, the matching End* helper must also be called. This is part of the base class contract and should usually be enforced with a try/finally block around the model modification. 

public class NameListModel : Model
{
    private List<string> Items { get; } = ["John", "Paul", "George", "Ringo"];

    public override int RowCount(ModelIndex parent)
        => parent?.IsValid == true ? 0 : Items.Count;
    public override int ColumnCount(ModelIndex parent) => 1;
    public override ModelIndex Parent(ModelIndex index) => ModelIndex.Empty;

    public override ModelIndex Index(int row, int column, ModelIndex parent)
    {
        if (parent?.IsValid == true || column != 0 || row < 0 || row >= Items.Count)
            return ModelIndex.Empty;
        return new ModelIndex(row, column);
    }

    public override object Data(ModelIndex index, int role)
    {
        if (index is not { IsValid: true } || role != Roles.DisplayRole)
            return null;
        return Items[index.Row];
    }

    public override bool InsertRows(int row, int count, ModelIndex parent = null)
    {
        if (parent?.IsValid == true || row < 0 || row > Items.Count || count < 1)
            return false;

        BeginInsertRows(ModelIndex.Empty, row, row + count - 1);
        try {
            Items.InsertRange(row, Enumerable.Repeat("(empty)", count));
        } finally {
            EndInsertRows();
        }
        return true;
    }
}

Methods

BeginInsertColumns(ModelIndex, int, int)

Notifies that columns are about to be inserted under the specified parent.

protected void BeginInsertColumns(ModelIndex parent, int first, int last)

Parameters

parent ModelIndex

The parent whose child columns will change.

first int

The first inserted column index.

last int

The inclusive last inserted column index.

Remarks

Call this method immediately before mutating the backing storage. Each call must be paired with EndInsertColumns() once the begin/end section has been entered.

BeginInsertRows(ModelIndex, int, int)

Notifies that rows are about to be inserted under the specified parent.

protected void BeginInsertRows(ModelIndex parent, int first, int last)

Parameters

parent ModelIndex

The parent whose child rows will change.

first int

The first inserted row index.

last int

The inclusive last inserted row index.

Remarks

Call this method immediately before mutating the backing storage. Each call must be paired with EndInsertRows() once the begin/end section has been entered.

BeginMoveColumns(ModelIndex, int, int, ModelIndex, int)

Notifies that columns are about to move to a new parent and destination.

protected void BeginMoveColumns(ModelIndex sourceParent, int sourceFirst, int sourceLast, ModelIndex destinationParent, int destinationChild)

Parameters

sourceParent ModelIndex
sourceFirst int
sourceLast int
destinationParent ModelIndex
destinationChild int

BeginMoveRows(ModelIndex, int, int, ModelIndex, int)

Notifies that rows are about to move to a new parent and destination.

protected void BeginMoveRows(ModelIndex sourceParent, int sourceFirst, int sourceLast, ModelIndex destinationParent, int destinationChild)

Parameters

sourceParent ModelIndex
sourceFirst int
sourceLast int
destinationParent ModelIndex
destinationChild int

BeginRemoveColumns(ModelIndex, int, int)

Notifies that columns are about to be removed under the specified parent.

protected void BeginRemoveColumns(ModelIndex parent, int first, int last)

Parameters

parent ModelIndex

The parent whose child columns will change.

first int

The first removed column index.

last int

The inclusive last removed column index.

Remarks

Call this method immediately before mutating the backing storage. Each call must be paired with EndRemoveColumns() once the begin/end section has been entered.

BeginRemoveRows(ModelIndex, int, int)

Notifies that rows are about to be removed under the specified parent.

protected void BeginRemoveRows(ModelIndex parent, int first, int last)

Parameters

parent ModelIndex

The parent whose child rows will change.

first int

The first removed row index.

last int

The inclusive last removed row index.

Remarks

Call this method immediately before mutating the backing storage. Each call must be paired with EndRemoveRows() once the begin/end section has been entered.

BeginResetModel()

Notifies that the entire model is about to be reset.

protected void BeginResetModel()

Remarks

Use a reset when the structure or contents change so broadly that fine-grained insert, remove, move, or data notifications are no longer practical. Each call must be paired with EndResetModel() once the begin/end section has been entered.

Buddy(ModelIndex)

Returns an alternate item that should be edited instead of the specified item.

public virtual ModelIndex Buddy(ModelIndex index)

Parameters

index ModelIndex

Returns

ModelIndex

CanFetchMore(ModelIndex)

Returns whether more child items can be loaded for the specified parent.

public virtual bool CanFetchMore(ModelIndex parent)

Parameters

parent ModelIndex

Returns

bool

ClearItemData(ModelIndex)

Clears all values associated with the specified item.

public virtual bool ClearItemData(ModelIndex index)

Parameters

index ModelIndex

Returns

bool

ColumnCount(ModelIndex)

Returns the number of columns for the specified parent index.

public abstract int ColumnCount(ModelIndex parent)

Parameters

parent ModelIndex

Returns

int

Data(ModelIndex, int)

Returns the value stored for the specified item and role.

public abstract object Data(ModelIndex index, int role)

Parameters

index ModelIndex
role int

Returns

object

DataChanged(ModelIndex, ModelIndex, int[])

Notifies that existing item values changed within the specified inclusive range.

protected void DataChanged(ModelIndex topLeft, ModelIndex bottomRight, int[] roles = null)

Parameters

topLeft ModelIndex

The top-left changed index.

bottomRight ModelIndex

The bottom-right changed index.

roles int[]

The affected roles, or null to indicate a general value update.

Remarks

Use this for in-place value edits only. Do not use it for insertions, removals, moves, or resets.

EndInsertColumns()

Completes a column insertion previously started with BeginInsertColumns(ModelIndex, int, int).

protected void EndInsertColumns()

EndInsertRows()

Completes a row insertion previously started with BeginInsertRows(ModelIndex, int, int).

protected void EndInsertRows()

EndMoveColumns()

Completes a column move previously started with BeginMoveColumns(ModelIndex, int, int, ModelIndex, int).

protected void EndMoveColumns()

EndMoveRows()

Completes a row move previously started with BeginMoveRows(ModelIndex, int, int, ModelIndex, int).

protected void EndMoveRows()

EndRemoveColumns()

Completes a column removal previously started with BeginRemoveColumns(ModelIndex, int, int).

protected void EndRemoveColumns()

EndRemoveRows()

Completes a row removal previously started with BeginRemoveRows(ModelIndex, int, int).

protected void EndRemoveRows()

EndResetModel()

Completes a model reset previously started with BeginResetModel().

protected void EndResetModel()

FetchMore(ModelIndex)

Loads additional child items for the specified parent.

public virtual void FetchMore(ModelIndex parent)

Parameters

parent ModelIndex

Flags(ModelIndex)

Returns the capability flags for the specified item.

public virtual int Flags(ModelIndex index)

Parameters

index ModelIndex

Returns

int

Remarks

The default implementation marks items as enabled and selectable.

HasChildren(ModelIndex)

Returns whether the specified parent item has any children.

public virtual bool HasChildren(ModelIndex parent)

Parameters

parent ModelIndex

Returns

bool

HeaderData(int, int, int)

Returns the value for a header section and role.

public virtual object HeaderData(int section, int orientation, int role)

Parameters

section int
orientation int
role int

Returns

object

HeaderDataChanged(int, int, int)

Notifies that header values changed for the specified inclusive section range.

protected void HeaderDataChanged(int orientation, int first, int last)

Parameters

orientation int

The header orientation, typically Horizontal or Vertical.

first int

The first changed section index.

last int

The inclusive last changed section index.

Index(int, int, ModelIndex)

Creates an index that identifies the item at the specified row and column under a parent.

public abstract ModelIndex Index(int row, int column, ModelIndex parent)

Parameters

row int
column int
parent ModelIndex

Returns

ModelIndex

InsertColumns(int, int, ModelIndex)

Inserts columns under the specified parent item.

public virtual bool InsertColumns(int column, int count, ModelIndex parent = null)

Parameters

column int
count int
parent ModelIndex

Returns

bool

InsertRows(int, int, ModelIndex)

Inserts rows under the specified parent item.

public virtual bool InsertRows(int row, int count, ModelIndex parent = null)

Parameters

row int
count int
parent ModelIndex

Returns

bool

Remarks

If implemented, call BeginInsertRows(ModelIndex, int, int) before changing the backing storage and EndInsertRows() immediately after the insertion completes successfully. Once BeginInsertRows has been called, the matching EndInsertRows call must still happen, typically from a try/finally block.

MoveColumns(ModelIndex, int, int, ModelIndex, int)

Moves columns from one parent and position to another.

public virtual bool MoveColumns(ModelIndex sourceParent, int sourceColumn, int count, ModelIndex destinationParent, int destinationChild)

Parameters

sourceParent ModelIndex
sourceColumn int
count int
destinationParent ModelIndex
destinationChild int

Returns

bool

MoveRows(ModelIndex, int, int, ModelIndex, int)

Moves rows from one parent and position to another.

public virtual bool MoveRows(ModelIndex sourceParent, int sourceRow, int count, ModelIndex destinationParent, int destinationChild)

Parameters

sourceParent ModelIndex
sourceRow int
count int
destinationParent ModelIndex
destinationChild int

Returns

bool

Parent(ModelIndex)

Returns the parent index for the specified item.

public abstract ModelIndex Parent(ModelIndex index)

Parameters

index ModelIndex

Returns

ModelIndex

RemoveColumns(int, int, ModelIndex)

Removes columns under the specified parent item.

public virtual bool RemoveColumns(int column, int count, ModelIndex parent = null)

Parameters

column int
count int
parent ModelIndex

Returns

bool

RemoveRows(int, int, ModelIndex)

Removes rows under the specified parent item.

public virtual bool RemoveRows(int row, int count, ModelIndex parent = null)

Parameters

row int
count int
parent ModelIndex

Returns

bool

Remarks

If implemented, call BeginRemoveRows(ModelIndex, int, int) before changing the backing storage and EndRemoveRows() immediately after the removal completes successfully. Once BeginRemoveRows has been called, the matching EndRemoveRows call must still happen, typically from a try/finally block.

RoleNames()

Returns the names used to address values exposed by this model.

public virtual Dictionary<int, string> RoleNames()

Returns

Dictionary<int, string>

Remarks

A role identifies a value that can be requested from an item, such as a display string, an editable value, or a custom property. Return a dictionary whose keys are role ids, such as DisplayRole or values starting at UserRole, and whose values are stable, consumer-facing role names.

RowCount(ModelIndex)

Returns the number of child rows under the specified parent index.

public abstract int RowCount(ModelIndex parent)

Parameters

parent ModelIndex

Returns

int

SetData(ModelIndex, object, int)

Updates the value stored for the specified item and role.

public virtual bool SetData(ModelIndex index, object value, int role)

Parameters

index ModelIndex
value object
role int

Returns

bool

Remarks

Call DataChanged(ModelIndex, ModelIndex, int[]) after a successful in-place edit so that connected consumers refresh the affected data.

SetHeaderData(int, int, object, int)

Updates the value of a header section for the specified role.

public virtual bool SetHeaderData(int section, int orientation, object value, int role)

Parameters

section int
orientation int
value object
role int

Returns

bool

Sibling(int, int, ModelIndex)

Returns another item with the same parent as the specified item.

public virtual ModelIndex Sibling(int row, int column, ModelIndex index)

Parameters

row int
column int
index ModelIndex

Returns

ModelIndex

Sort(int, int)

Reorders the model by the specified column and direction.

public virtual void Sort(int column, int order)

Parameters

column int
order int

Events

ModelChanged

Raised when the model reports a structural or data change.

public event EventHandler<ModelChangeEventArgs> ModelChanged

Event Type

EventHandler<ModelChangeEventArgs>

Remarks

This event is used by the generated bridge layer to forward model updates to consumers. Application model code normally uses the protected Begin*, End*, and *Changed methods instead of raising this event directly.