RepositoryItemCheckEdit.QueryCheckStateByValue Event

Allows for custom conversion from the edit value to a check state (checked, unchecked and indeterminate).

Namespace: DevExpress.XtraEditors.Repository

Assembly: DevExpress.XtraEditors.v24.1.dll

NuGet Package: DevExpress.Win.Navigation

Declaration

C#

[DXCategory("Events")]
public event QueryCheckStateByValueEventHandler QueryCheckStateByValue

VB.NET

<DXCategory("Events")>
Public Event QueryCheckStateByValue As QueryCheckStateByValueEventHandler

Event Data

The QueryCheckStateByValue event's data class is QueryCheckStateByValueEventArgs. The following properties provide information specific to this event:

Property	Description
CheckState	Use this property to set the check state that corresponds to the current edit value.
Handled	Gets or sets whether the event is handled and no default processing is required. Inherited from QueryCheckStatesEventArgs.
Value	Gets the current edit value.

Remarks

Each state (checked, unchecked and indeterminate) in the CheckEdit control corresponds to a certain value. The default “state - value” pairs are:

• Checked state corresponds to the true Boolean value.
• Unchecked state corresponds to the false Boolean value.
• Indeterminate state (see RepositoryItemCheckEdit.AllowGrayed) corresponds to the null value (Nothing in Visual Basic).

When the editor’s check state is modified by an end-user or in code, a corresponding value is assigned to the editor’s edit value. Conversely, when the editor’s edit value is modified, the corresponding check state is enabled. For instance, when you assign false to the CheckEdit.EditValue property in a standalone editor, the editor switches to the Unchecked state. When an end-user enables the Checked state, the editor’s edit value is set to true.

Note

The edit value is typically used for data binding. For standalone editors, it is specified by the CheckEdit.EditValue property. For editors embedded in a Grid Control, the editor’s edit value is a cell value.

You can associate custom values with the check states using the RepositoryItemCheckEdit.ValueChecked, RepositoryItemCheckEdit.ValueUnchecked, and RepositoryItemCheckEdit.ValueGrayed properties. In advanced cases, you can implement dynamic conversion from the check states to edit values and vice versa manually, by handling the RepositoryItemCheckEdit.QueryValueByCheckState and QueryCheckStateByValue events.

Conversion from Edit Value to Check State

The QueryCheckStateByValue event fires each time the editor’s check state is requested (for instance, when reading the CheckEdit.CheckState property, or when calling the RepositoryItemCheckEdit.GetStateByValue method). In your event handler, set the CheckState event parameter according to the Value event parameter. In addition, set the Handled parameter to true for the CheckState parameter to be in effect once the event handler is complete.

If the Handled parameter is left set to false, the CheckState parameter value will be ignored, and the actual check state will be calculated by comparing the current edit value with the values of the RepositoryItemCheckEdit.ValueChecked, RepositoryItemCheckEdit.ValueUnchecked, and RepositoryItemCheckEdit.ValueGrayed properties.

Conversion from Check State to Edit Value

The RepositoryItemCheckEdit.QueryValueByCheckState event allows you to perform the opposite conversion. It fires each time the editor’s check state is modified and the edit value is to be updated accordingly. This happens when end-users toggle the check state, when changing the CheckEdit.CheckState property, and when calling the RepositoryItemCheckEdit.GetValueByState method. In your QueryValueByCheckState event handler, set the Value event parameter according to the CheckState event parameter. In addition, set the Handled parameter to true for the Value parameter to be in effect once the event handler is complete.

If the Handled parameter is left set to false, the Value parameter value will be ignored, and the edit value will be set to the RepositoryItemCheckEdit.ValueChecked, RepositoryItemCheckEdit.ValueUnchecked, or RepositoryItemCheckEdit.ValueGrayed property value (dependent on the current state).

Example

This example demonstrates how to handle RepositoryItemCheckEdit.QueryCheckStateByValue and RepositoryItemCheckEdit.QueryValueByCheckState events in order to use a check editor to display and modify data from the bound data field.

The example assumes that a check editor is bound to a specific dataset field whose type is not obviously known and should be determined programmatically. The available data types that the field can take on are boolean, string and integer. So the field can contain the following combinations representing an option value (these values will be used to set the editor’s CheckEdit.EditValue property):

• True, False - for the boolean type;
• “Yes“, “No“, “?“ - for the string type;
• 1, 0, -1 - for the integer type.

It is evident that making use of RepositoryItemCheckEdit.ValueChecked, RepositoryItemCheckEdit.ValueUnchecked and RepositoryItemCheckEdit.ValueGrayed properties is insufficient in this case. Thus, the example requires and implements a custom “edit value -> check state” and “check state -> edit value” conversion logic, which is illustrated by the sample code below.

C#

using DevExpress.XtraEditors.Controls;

private void checkEdit1_QueryCheckStateByValue(object sender, QueryCheckStateByValueEventArgs e) {
    string val = e.Value.ToString();
    switch (val) {
        case "True":
        case "Yes":
        case "1":
            e.CheckState = CheckState.Checked;
            break;
        case "False":
        case "No":
        case "0":
            e.CheckState = CheckState.Unchecked;
            break;
        default:
            e.CheckState = CheckState.Indeterminate;
            break;
    }
    e.Handled = true;
}

private void checkEdit1_QueryValueByCheckState(object sender, QueryValueByCheckStateEventArgs e) {
    CheckEdit edit = sender as CheckEdit;
    object val = edit.EditValue;
    switch (e.CheckState) {
        case CheckState.Checked:
            if (val is bool) e.Value = true;
            else if (val is string) e.Value = "Yes";
            else if (val is int) e.Value = 1;
            else e.Value = null;
        break;
        case CheckState.Unchecked:
            if (val is bool) e.Value = false;
            else if (val is string) e.Value = "No";
            else if (val is int) e.Value = 0;
            else e.Value = null;
            break;
        default:
            if (val is bool) e.Value = false;
            else if (val is string) e.Value = "?";
            else if (val is int) e.Value = -1;
            else e.Value = null;
            break;
    }
    e.Handled = true;
}

VB.NET

Private Sub QueryCheckStateByValue(ByVal sender As Object, _
  ByVal e As DevExpress.XtraEditors.Controls.QueryCheckStateByValueEventArgs)
    Dim val As String = e.Value.ToString()
    Select Case val
        Case "True", "Yes", "1"
            e.CheckState = CheckState.Checked
        Case "False", "No", "0"
            e.CheckState = CheckState.Unchecked
        Case Else
            e.CheckState = CheckState.Indeterminate
    End Select
    e.Handled = True
End Sub

Private Sub QueryValueByCheckState(ByVal sender As Object, _ 
  ByVal e As DevExpress.XtraEditors.Controls.QueryValueByCheckStateEventArgs)
    Dim Edit As CheckEdit = CType(sender, CheckEdit)
    Dim Val As Object = Edit.EditValue
    Select Case e.CheckState
        Case CheckState.Checked
            If TypeOf Val Is Boolean Then
                e.Value = True
            ElseIf TypeOf Val Is String Then
                e.Value = "Yes"
            ElseIf TypeOf Val Is Integer Then
                e.Value = 1
            Else : e.Value = Nothing
            End If
        Case CheckState.Unchecked
            If TypeOf Val Is Boolean Then
                e.Value = False
            ElseIf TypeOf Val Is String Then
                e.Value = "No"
            ElseIf TypeOf Val Is Integer Then
                e.Value = 0
            Else : e.Value = Nothing
            End If
        Case Else
            If TypeOf Val Is Boolean Then
                e.Value = False
            ElseIf TypeOf Val Is String Then
                e.Value = "?"
            ElseIf TypeOf Val Is Integer Then
                e.Value = -1
            Else : e.Value = Nothing
            End If
    End Select
    e.Handled = True
End Sub