DxCheckBoxSettings Class

Contains settings of an auto-generated checkbox editor.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v24.2.dll

NuGet Package: DevExpress.Blazor

Declaration

public class DxCheckBoxSettings :
    DxEditSettings,
    ICheckBoxSettings,
    IEditSettings

Remarks

Grid and TreeList components automatically generate editors for columns based on associated data types. For Boolean and Nullable Boolean types, they generate a checkbox editor.

The DxCheckBoxSettings class contains checkbox editor settings. Specify properties of this class to customize checkbox appearance and behavior in the following elements:

• Edit forms
• Edit cells
• Filter row
• Filer menu and column cells

You can replace the default editor of any column with a checkbox. Refer to the following section for more information: Change a Column Editor to Checkbox.

Auto-Generated CheckBox in Edit Cells

Grid and TreeList components automatically display column editors in data rows during edit operations. In the following code snippet, the Grid displays a checkbox editor for the Discontinued column:

Razor

@inject ProductService ProductData

<DxGrid Data="@products"
        PageSize="5"
        EditMode="GridEditMode.EditRow">
    <Columns>
        <DxGridCommandColumn />
        <DxGridDataColumn FieldName="ProductName" Width="30%" />
        <DxGridDataColumn FieldName="UnitPrice" />
        <DxGridDataColumn FieldName="UnitsInOrder" />
        <DxGridDataColumn FieldName="Discontinued" />
    </Columns>
</DxGrid>

@code {
    private Product[]? products;
    protected override async Task OnInitializedAsync() {
        products = await ProductData.GetData();
    }
}

ProductService.cs

public class ProductService {
    public Task<Product[]> GetData() {
        List<Product> products = new List<Product>();
        products.Add(new Product() { ProductID = 1, ProductName = "Chai", UnitPrice = 19, UnitsInOrder = 20, Discontinued = true });
        products.Add(new Product() { ProductID = 2, ProductName = "Chang", UnitPrice = 19, UnitsInOrder = 40, Discontinued = true });
        products.Add(new Product() { ProductID = 3, ProductName = "Aniseed Syrup", UnitPrice = 10, UnitsInOrder = 70, Discontinued = true });
        products.Add(new Product() { ProductID = 4, ProductName = "Mishi Kobe Niku", UnitPrice = 97, UnitsInOrder = 32, Discontinued = false });
        products.Add(new Product() { ProductID = 5, ProductName = "Ikura", UnitPrice = 31, UnitsInOrder = 10, Discontinued = false });
        products.Add(new Product() { ProductID = 6, ProductName = "Chef Anton's Cajun Seasoning", UnitPrice = 22, UnitsInOrder = 12, Discontinued = false });
        products.Add(new Product() { ProductID = 7, ProductName = "Chef Anton's Gumbo Mix", UnitPrice = 21.35m, UnitsInOrder = 16, Discontinued = true });
        products.Add(new Product() { ProductID = 8, ProductName = "Grandma's Boysenberry Spread", UnitPrice = 25, UnitsInOrder = 20, Discontinued = true });
        products.Add(new Product() { ProductID = 9, ProductName = "Uncle Bob's Organic Dried Pears", UnitPrice = 30, UnitsInOrder = 24, Discontinued = false });
        products.Add(new Product() { ProductID = 10, ProductName = "Northwoods Cranberry Sauce", UnitPrice = 40, UnitsInOrder = 18, Discontinued = false });
        products.Add(new Product() { ProductID = 11, ProductName = "Queso Cabrales", UnitPrice = 21, UnitsInOrder = 30 });
        products.Add(new Product() { ProductID = 12, ProductName = "Queso Manchego La Pastora", UnitPrice = 38, UnitsInOrder = 10 });
        return Task.FromResult(products.ToArray());
    }
}

Product.cs

public class Product {
    public int ProductID { get; set; }
    public string ProductName { get; set; }
    public decimal? UnitPrice { get; set; }
    public short? UnitsInOrder { get; set; }
    public bool Discontinued { get; set; }
}

Auto-Generated CheckBox in Edit Forms

Place a column editor in EditFormTemplate to display the editor in the inline or pop-up edit form. To get the editor, pass the column’s field name to the GetEditor method.

In the following code snippet, the Grid displays an auto-generated checkbox editor for the Discontinued column:

Razor

@inject ProductService ProductData

<DxGrid Data="@products" PageSize="3">
    <Columns>
        <DxGridCommandColumn />
        <DxGridDataColumn FieldName="ProductName" Width="30%" />
        <DxGridDataColumn FieldName="UnitPrice" />
        <DxGridDataColumn FieldName="UnitsInOrder" />
        <DxGridDataColumn FieldName="Discontinued" />
    </Columns>
    <EditFormTemplate Context="editFormContext">
        <DxFormLayout>
            <DxFormLayoutItem Caption="Product Name:">
                @editFormContext.GetEditor("ProductName")
            </DxFormLayoutItem>
            <DxFormLayoutItem Caption="Unit Price:">
                @editFormContext.GetEditor("UnitPrice")
            </DxFormLayoutItem>
            <DxFormLayoutItem Caption="Units In Order:">
                @editFormContext.GetEditor("UnitsInOrder")
            </DxFormLayoutItem>
            <DxFormLayoutItem Caption="Discontinued:">
                @editFormContext.GetEditor("Discontinued")
            </DxFormLayoutItem>
        </DxFormLayout>
    </EditFormTemplate>
</DxGrid>

@code {
    private Product[]? products;
    protected override async Task OnInitializedAsync() {
        products = await ProductData.GetData();
    }
}

ProductService.cs

public class ProductService {
    public Task<Product[]> GetData() {
        List<Product> products = new List<Product>();
        products.Add(new Product() { ProductID = 1, ProductName = "Chai", UnitPrice = 19, UnitsInOrder = 20, Discontinued = true });
        products.Add(new Product() { ProductID = 2, ProductName = "Chang", UnitPrice = 19, UnitsInOrder = 40, Discontinued = true });
        products.Add(new Product() { ProductID = 3, ProductName = "Aniseed Syrup", UnitPrice = 10, UnitsInOrder = 70, Discontinued = true });
        products.Add(new Product() { ProductID = 4, ProductName = "Mishi Kobe Niku", UnitPrice = 97, UnitsInOrder = 32, Discontinued = false });
        products.Add(new Product() { ProductID = 5, ProductName = "Ikura", UnitPrice = 31, UnitsInOrder = 10, Discontinued = false });
        products.Add(new Product() { ProductID = 6, ProductName = "Chef Anton's Cajun Seasoning", UnitPrice = 22, UnitsInOrder = 12, Discontinued = false });
        products.Add(new Product() { ProductID = 7, ProductName = "Chef Anton's Gumbo Mix", UnitPrice = 21.35m, UnitsInOrder = 16, Discontinued = true });
        products.Add(new Product() { ProductID = 8, ProductName = "Grandma's Boysenberry Spread", UnitPrice = 25, UnitsInOrder = 20, Discontinued = true });
        products.Add(new Product() { ProductID = 9, ProductName = "Uncle Bob's Organic Dried Pears", UnitPrice = 30, UnitsInOrder = 24, Discontinued = false });
        products.Add(new Product() { ProductID = 10, ProductName = "Northwoods Cranberry Sauce", UnitPrice = 40, UnitsInOrder = 18, Discontinued = false });
        products.Add(new Product() { ProductID = 11, ProductName = "Queso Cabrales", UnitPrice = 21, UnitsInOrder = 30 });
        products.Add(new Product() { ProductID = 12, ProductName = "Queso Manchego La Pastora", UnitPrice = 38, UnitsInOrder = 10 });
        return Task.FromResult(products.ToArray());
    }
}

Product.cs

public class Product {
    public int ProductID { get; set; }
    public string ProductName { get; set; }
    public decimal? UnitPrice { get; set; }
    public short? UnitsInOrder { get; set; }
    public bool Discontinued { get; set; }
}

Grid and TreeList components allow you to customize settings of a column’s checkbox editor. To apply these settings, specify a DxCheckBoxSettings object in a column’s EditSettings property:

<DxGrid Data="@products"
        PageSize="3">
    <Columns>
        <DxGridCommandColumn />
        <DxGridDataColumn FieldName="ProductName" Width="30%" />
        <DxGridDataColumn FieldName="UnitPrice" />
        <DxGridDataColumn FieldName="UnitsInOrder" />
        <DxGridDataColumn FieldName="Discontinued">
            <EditSettings>
                <DxCheckBoxSettings CheckType="CheckType.Switch" Alignment="CheckBoxContentAlignment.Right"/>
            </EditSettings>
        </DxGridDataColumn>
    </Columns>
    <EditFormTemplate Context="editFormContext">
        <DxFormLayout>
            <DxFormLayoutItem Caption="Product Name:">
                @editFormContext.GetEditor("ProductName")
            </DxFormLayoutItem>
            <DxFormLayoutItem Caption="Unit Price:">
                @editFormContext.GetEditor("UnitPrice")
            </DxFormLayoutItem>
            <DxFormLayoutItem Caption="Units In Order:">
                @editFormContext.GetEditor("UnitsInOrder")
            </DxFormLayoutItem>
            <DxFormLayoutItem Caption="Discontinued:">
                @editFormContext.GetEditor("Discontinued")
            </DxFormLayoutItem>
        </DxFormLayout>
    </EditFormTemplate>
</DxGrid>

Auto-Generated CheckBox in Filter Row

In the filter row, Grid and TreeList components replace a checkbox with another editor based on the current FilterMode. If a component filters column data by value, the component displays a combo box instead of the checkbox. If column data is filtered by display text, the component replaces the checkbox with a text box.

In the following code snippet, the Grid filters Discontinued column data by value:

<DxGrid Data="@products"
        PageSize="5"
        ShowFilterRow="true">
    <Columns>
        <DxGridCommandColumn />
        <DxGridDataColumn FieldName="ProductName" Width="30%" />
        <DxGridDataColumn FieldName="UnitPrice" />
        <DxGridDataColumn FieldName="UnitsInOrder" />
        <DxGridDataColumn FieldName="Discontinued" />
    </Columns>
</DxGrid>

Display Text in Filter Menu and Column Cell

In display mode, Grid and TreeList show read-only checkboxes instead of column cell values if the column’s editor is a checkbox. Set the ShowCheckBoxInDisplayMode property to false to show text strings instead of checkboxes in display mode. To customize these strings, specify the following properties:

• CheckedDisplayText
• IndeterminateDisplayText
• UncheckedDisplayText

The following code snippet displays custom strings in the Discontinued column:

Razor

<DxGrid Data="@products" PageSize="5">
    <Columns>
        <DxGridDataColumn FieldName="ProductName" />
        <DxGridDataColumn FieldName="UnitPrice" />
        <DxGridDataColumn FieldName="UnitsInOrder" />
        <DxGridDataColumn FieldName="Discontinued">
            <EditSettings>
                <DxCheckBoxSettings ShowCheckBoxInDisplayMode="false"
                                    CheckedDisplayText="Yes"
                                    IndeterminateDisplayText="Unknown"
                                    UncheckedDisplayText="No" />
            </EditSettings>
        </DxGridDataColumn>
    </Columns>
</DxGrid>

@code {
    private Product[]? products;
    protected override async Task OnInitializedAsync() {
        products = await ProductData.GetData();
    }
}

ProductService.cs

public class ProductService {
    public Task<Product[]> GetData() {
        List<Product> products = new List<Product>();
        products.Add(new Product() { ProductID = 1, ProductName = "Chai", UnitPrice = 19, UnitsInOrder = 20, Discontinued = true });
        products.Add(new Product() { ProductID = 2, ProductName = "Chang", UnitPrice = 19, UnitsInOrder = 40, Discontinued = true });
        products.Add(new Product() { ProductID = 3, ProductName = "Aniseed Syrup", UnitPrice = 10, UnitsInOrder = 70, Discontinued = true });
        products.Add(new Product() { ProductID = 4, ProductName = "Mishi Kobe Niku", UnitPrice = 97, UnitsInOrder = 32, Discontinued = false });
        products.Add(new Product() { ProductID = 5, ProductName = "Ikura", UnitPrice = 31, UnitsInOrder = 10 });
        products.Add(new Product() { ProductID = 6, ProductName = "Chef Anton's Cajun Seasoning", UnitPrice = 22, UnitsInOrder = 12, Discontinued = false });
        products.Add(new Product() { ProductID = 7, ProductName = "Chef Anton's Gumbo Mix", UnitPrice = 21.35m, UnitsInOrder = 16, Discontinued = true });
        products.Add(new Product() { ProductID = 8, ProductName = "Grandma's Boysenberry Spread", UnitPrice = 25, UnitsInOrder = 20, Discontinued = true });
        products.Add(new Product() { ProductID = 9, ProductName = "Uncle Bob's Organic Dried Pears", UnitPrice = 30, UnitsInOrder = 24, Discontinued = false });
        products.Add(new Product() { ProductID = 10, ProductName = "Northwoods Cranberry Sauce", UnitPrice = 40, UnitsInOrder = 18, Discontinued = false });
        products.Add(new Product() { ProductID = 11, ProductName = "Queso Cabrales", UnitPrice = 21, UnitsInOrder = 30 });
        products.Add(new Product() { ProductID = 12, ProductName = "Queso Manchego La Pastora", UnitPrice = 38, UnitsInOrder = 10 });
        return Task.FromResult(products.ToArray());
    }
}

Product.cs

public class Product {
    public int ProductID { get; set; }
    public string ProductName { get; set; }
    public decimal? UnitPrice { get; set; }
    public short? UnitsInOrder { get; set; }
    public bool? Discontinued { get; set; }
}

A filer menu also displays these text strings:

Change a Column Editor to Checkbox

Grid and TreeList automatically generate editors for columns based on their data type. For Boolean and Nullable Boolean types, they generate a checkbox editor. Specify a DxCheckBoxSettings object in a column’s EditSettings property to replace the default editor with a checkbox.

A checkbox editor supports all data types. For predefined data types, the checkbox defines the values that correspond to checked, unchecked, and indeterminate^[1] states as follows:

Data Type	Checked State	Unchecked State	Indeterminate State
Boolean	true	false	(not supported)
Nullable Boolean	true	false	null
String	"true"	"false"	null
Unsigned Integer Numeric Types	1	0	2
Signed Integer Numeric Types	1	0	-1
Floating-Point Numeric Types	1	0	-1

Other values correspond to the indeterminate state of the checkbox. If the indeterminate state is unavailable, such values correspond to the unchecked state.

Set the following properties to display a checkbox editor for a column associated with another data type:

ValueChecked

Specifies the value that corresponds to the checked state.

ValueUnchecked

Specifies the value that corresponds to the unchecked state.

ValueIndeterminate

Specifies the value that corresponds to the indeterminate state.

The following code snippet displays a checkbox for a column bound to an Enum object:

Index.razor

<DxGrid Data="@products"
        EditMode="GridEditMode.EditRow">
    <Columns>
        <DxGridCommandColumn />
        <DxGridDataColumn FieldName="ProductName" />
        <DxGridDataColumn FieldName="UnitPrice" />
        <DxGridDataColumn FieldName="UnitsInOrder" />
        <DxGridDataColumn FieldName="Discontinued">
            <EditSettings>
                <DxCheckBoxSettings ValueChecked="@State.Yes"
                                    ValueUnchecked="@State.No"
                                    ValueIndeterminate="@State.Unknown" />
            </EditSettings>
        </DxGridDataColumn>
    </Columns>
</DxGrid>

Product.cs

public enum State { Yes, No, Unknown }

public class Product {
    public int ProductID { get; set; }
    public string ProductName { get; set; }
    public decimal? UnitPrice { get; set; }
    public short? UnitsInOrder { get; set; }
    public State Discontinued { get; set; }
}

ProductService.cs

public class ProductService {
    public Task<Product[]> GetData() {
        List<Product> products = new List<Product>();
        products.Add(new Product() { ProductID = 1, ProductName = "Chai", UnitPrice = 19, UnitsInOrder = 20 });
        products.Add(new Product() { ProductID = 2, ProductName = "Chang", UnitPrice = 19, UnitsInOrder = 40, Discontinued = State.Unknown });
        products.Add(new Product() { ProductID = 3, ProductName = "Aniseed Syrup", UnitPrice = 10, UnitsInOrder = 70, Discontinued = State.Yes });
        products.Add(new Product() { ProductID = 4, ProductName = "Mishi Kobe Niku", UnitPrice = 97, UnitsInOrder = 32, Discontinued = State.Yes });
        products.Add(new Product() { ProductID = 5, ProductName = "Ikura", UnitPrice = 31, UnitsInOrder = 10, Discontinued = State.Unknown });
        products.Add(new Product() { ProductID = 6, ProductName = "Chef Anton's Cajun Seasoning", UnitPrice = 22, UnitsInOrder = 12, Discontinued = State.No });
        products.Add(new Product() { ProductID = 7, ProductName = "Chef Anton's Gumbo Mix", UnitPrice = 21.35m, UnitsInOrder = 16 });
        products.Add(new Product() { ProductID = 8, ProductName = "Grandma's Boysenberry Spread", UnitPrice = 25, UnitsInOrder = 20, Discontinued = State.Unknown });
        products.Add(new Product() { ProductID = 9, ProductName = "Uncle Bob's Organic Dried Pears", UnitPrice = 30, UnitsInOrder = 24, Discontinued = State.No });
        products.Add(new Product() { ProductID = 10, ProductName = "Northwoods Cranberry Sauce", UnitPrice = 40, UnitsInOrder = 18, Discontinued = State.No });
        products.Add(new Product() { ProductID = 11, ProductName = "Queso Cabrales", UnitPrice = 21, UnitsInOrder = 30 });
        products.Add(new Product() { ProductID = 12, ProductName = "Queso Manchego La Pastora", UnitPrice = 38, UnitsInOrder = 10 });
        return Task.FromResult(products.ToArray());
    }
}

Runtime Customization

At runtime, call the GetColumnEditSettings method to access settings of a checkbox editor in the specified column. The following code snippet dynamically disables the editor:

<DxButton Click="@OnButtonClick" />
<DxGrid @ref=Grid
        Data="@products"
        EditMode="GridEditMode.EditRow">
    <Columns>
        <DxGridCommandColumn />
        <DxGridDataColumn FieldName="ProductName" />
        <DxGridDataColumn FieldName="UnitPrice" />
        <DxGridDataColumn FieldName="UnitsInOrder" />
        <DxGridDataColumn FieldName="Discontinued" />
    </Columns>
</DxGrid>
<DxButton Text="Disable the Discontinued Column" Click="Button_Click" />

@code {
    IGrid grid { get; set; }

    protected override async Task OnInitializedAsync() {
        products = await ProductData.GetData();
    }
    void Button_Click() {
        var settings = grid.GetColumnEditSettings<ICheckBoxSettings>("Discontinued");
        grid.BeginUpdate();
        settings.Enabled = false;
        grid.EndUpdate();
    }
}

Implements

IComponent

IHandleEvent

IHandleAfterRender

IDisposable

ICheckBoxSettings

IEditSettings

Inheritance

Object

ComponentBase

DevExpress.Blazor.Internal.BranchedRenderComponent

DevExpress.Blazor.Internal.ParameterTrackerSettingsComponent

DxEditSettings

DxCheckBoxSettings

Footnotes

1. The indeterminate state is unavailable if the CheckType property is set to Switch.