CustomizationFormCreatingCategoryEventArgs.CanCreate Property

Gets or sets a value specifying whether the creation of a new category row with the specified caption is allowed within the Customization Form.

Namespace: DevExpress.XtraVerticalGrid.Events

Assembly: DevExpress.XtraVerticalGrid.v24.1.dll

NuGet Packages: DevExpress.Win.Navigation, DevExpress.Win.VerticalGrid

Declaration

C#

public bool CanCreate { get; set; }

VB.NET

Public Property CanCreate As Boolean

Property Value

Type	Description
Boolean	true if the category row being created can be added to the VGridControlBase.Rows collection; otherwise false.

Remarks

Creating a new category row within the Customization Form is a two-step process. The first step is user-dependent and implies that the user is attempting to create a new category row by performing the following actions:

• Clicking the New… button within the Categories tabbed page of the Customization Form, as a result the New Category dialog window is invoked;
• Entering a caption for the category row being created and clicking the OK button.

Upon completion of the first step, a stand-alone instance of the CategoryRow object is created and its RowProperties.Caption property is set to the value entered. The created category row instance is not added to any grid’s row collection.

The second step is performed if a handler is assigned to the VGridControlBase.CustomizationFormCreatingCategory event. This event allows you to cancel adding a new category row to the VGridControlBase.Rows collection. For instance, you could prohibit category row addition if a row with the same caption already exists. For this purpose, set the CanCreate event parameter to false. The newly created row can be accessed by the CategoryEventArgs.Category property.

If the CanCreate property value is left set to true (the default value) in a handler, the header of the newly created category row becomes displayed on the Categories page of the Customization Form. This means that a row has been successfully added to the VGridControlBase.Rows collection of top-level grid rows, but is hidden - its BaseRow.Visible property is false and BaseRow.VisibleIndex is -1. The row header can then be dragged from the Customization Form onto the header panel to make the row visible within the grid control.

If the event handler sets the CanCreate parameter to false, the row adding dialog is displayed again. It allows users to correct the row caption or to cancel adding the row by clicking the Cancel button.

Example

When users create a new category, they enter the category caption. The example below shows how to check whether a category with the same caption already exists in the grid. If the captions match, the code shows a warning message.

The code enumerates grid categories to compare their captions with the new category caption. Refer to the following help topic for more information on how to enumerate grid rows: Tree Traversal.

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) {
        // Check if the processed row is a category.
        if (row.XtraRowTypeID != 0) return;
        // Compare the row caption with the entered caption.
        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);
    VGridControl vGridControl = sender as VGridControl;
    // Perform the operation.
    vGridControl.RowsIterator.DoOperation(operation);
    // Display a warning message if the match is found.
    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);
        // Prohibit to create a new row depending on 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)
        ' Check if the processed row is a category.
        If Row.XtraRowTypeID <> 0 Then Return
        ' Compare the row caption with the entered caption.
        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)
    Dim vGridControl As VGridControl = TryCast(sender, VGridControl)
    ' Perform the operation.
    VGridControl.RowsIterator.DoOperation(Operation)
    ' Display a warning message if the match is found.
    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)
        ' Prohibit to create a new row depending on the user choice.
        If Result = DialogResult.Yes Then e.CanCreate = False
    End If
End Sub