VGridControlBase.CustomizationFormCreatingCategory Event

Fires when an end-user tries to create a new category row within the Customization Form.

Namespace: DevExpress.XtraVerticalGrid

Assembly: DevExpress.XtraVerticalGrid.v18.2.dll

Declaration

C#

public event CustomizationFormCreatingCategoryEventHandler CustomizationFormCreatingCategory

VB.NET

Public Event CustomizationFormCreatingCategory As CustomizationFormCreatingCategoryEventHandler

Event Data

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

Property	Description
CanCreate	Gets or sets a value specifying whether the creation of a new category row with the specified caption is allowed within the Customization Form.
Category	Gets the processed category row. Inherited from CategoryEventArgs.

Remarks

The Customization Form provides the ability to create new category rows and delete category rows that are displayed in the Customization Form. To create a new category row, an end-user should switch to the Categories page of the Customization Form, click the New… button, enter its caption and confirm the row creation by clicking the Ok button.

The CustomizationFormCreatingCategory event is generated immediately after the Ok button has been clicked and before a new category row is added to the vertical grid’s VGridControlBase.Rows collection.

This event enables the creation of new rows to be cancelled. The event parameter’s CategoryEventArgs.Category property allows the row being created to be obtained. The CustomizationFormCreatingCategoryEventArgs.CanCreate property controls whether a new category row with the specified caption can be created.

 

Note

The header of the newly created category row will be displayed within the Categories page. This means that the row has been successfully created and added to the VGridControlBase.Rows collection of top-level grid rows. Note that this category row is hidden - its BaseRow.Visible property is set to false. End-users can drag the row header from the Customization Form to the vertical grid’s header panel to make the corresponding row visible within the grid.

Example

This example responds to a user’s attempt to create a new category row. After clicking the New… button within the Categories page of the Customization Form, an end-user enters the caption for the category row being created. The sample code demonstrates how to handle the CustomizationFormCreatingCategory event in order to search for an existing category row with the same caption and if found, asks the user what they want to do.

While searching, the code visits all the grid rows with the help of the VGridRowsIterator object and performs a specific caption comparison operation on each of them. The operation to be performed on visited rows is a descendant of the RowOperation class. The operation class constructor accepts a parameter representing the newly entered category row’s caption which to compare against the RowProperties.Caption property of rows. The Found property implemented in the operation class is used to recognize whether the match was found.

The picture below displays how the code reacts to entering an already existing caption for the new category row being created.

C#

using DevExpress.XtraVerticalGrid.Events;

public class RowOperationCategoryCaption : RowOperation {
    private string newCategoryCaption;
    private bool found = false;
    public RowOperationCategoryCaption(string newCaption) {
        this.newCategoryCaption = newCaption;
    }
    public bool Found {
        get { return found; }
    }
    public override void Execute(BaseRow row) {
        // checking if the processed row type is category
        if (row.XtraRowTypeID != 0) return;
        // comparing the processed row caption with the entered one
        if (row.Properties.Caption == newCategoryCaption) found = true;
    }
   public override bool CanContinueIteration(BaseRow row){
      return !Found;
   }
}

private void vGridControl1_CustomizationFormCreatingCategory(object sender, 
CustomizationFormCreatingCategoryEventArgs e) {
    RowOperationCategoryCaption operation = 
      new RowOperationCategoryCaption(e.Category.Properties.Caption);
    // performing the declared comparison operation
    vGridControl1.RowsIterator.DoOperation(operation);
    // if the match is found, displaying a warning message
    if (operation.Found) {
        string messageText = 
           "A category row with the same caption already exists.\r\n" + 
          "Click Yes to modify the new category row caption.\r\n" +
          "Click No to create a new category row with the specified caption.\r\n"+
          "Do you want to enter new caption?";
        DialogResult result = MessageBox.Show(messageText,"Match found",
          MessageBoxButtons.YesNo);
        // prohibiting new row creation depending upon the user choice
        if (result == DialogResult.Yes) e.CanCreate = false;
    }
}

VB.NET

Imports DevExpress.XtraVerticalGrid.Events

Public Class RowOperationCategoryCaption
    Inherits RowOperation
    Private _newCategoryCaption As String
    Private _found As Boolean = False
    Public Sub New(ByVal NewCaption As String)
        Me._newCategoryCaption = NewCaption
    End Sub

    Public ReadOnly Property Found() As Boolean
        Get
            Return _found
        End Get
    End Property

    Public Overrides Sub Execute(ByVal Row As BaseRow)
        ' checking if the processed row type is category
        If Row.XtraRowTypeID <> 0 Then Return
        ' comparing the processed row caption with the entered one
        If Row.Properties.Caption = _newCategoryCaption Then _found = True
    End Sub

   Public Overrides Function CanContinueIteration(ByVal row As BaseRow) As Boolean
      Return Not Found
   End Function
End Class

Private Sub VGridControl1_CustomizationFormCreatingCategory(ByVal sender As Object, _
ByVal e As CustomizationFormCreatingCategoryEventArgs) _
Handles VGridControl1.CustomizationFormCreatingCategory
    Dim Operation As New RowOperationCategoryCaption(e.Category.Properties.Caption)
    ' performing the declared comparison operation
    VGridControl1.RowsIterator.DoOperation(Operation)
    ' if the match is found, displaying a warning message
    If Operation.Found Then
    Dim MessageText As String = 
      "A category row with the same caption already exists." & Chr(13) & _
      "Click Yes to modify the new category row caption." & Chr(13) & _
      "Click No to create a new category row with the specified caption." & Chr(13) & _
      "Do you want to enter new caption?"
    Dim Result As DialogResult = MessageBox.Show(MessageText, "Match Found", _
      MessageBoxButtons.YesNo)
        ' prohibiting new row creation depending upon the user choice
        If Result = DialogResult.Yes Then e.CanCreate = False
    End If
End Sub