All docs
V20.1
20.1
19.2
The page you are viewing does not exist in version 19.2. This link will take you to the root page.
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.

New-Item Row

  • 4 minutes to read

The tree list control supports the New-Item Row — a row that is displayed at the top or bottom of the list and allows users to create a new root node.

Set the TreeList.OptionsView.NewItemRowPosition property to Top or Bottom to show the New-Item Row at the list's corresponding side.

Initialize Column Values

The TreeList.InitNewRow event fires when a new row is about to be created and allows you to initialize column values. This event fires if the user starts to enter a value in the New-Item Row or invokes the Add Node or Add Child Node command in the context menu.

Example: How to Specify a New Node's Key and Other Column Values

The code below shows how to initialize the Status, Start Date, and Due Date column values when a user focuses the New-Item Row.

The TreeList.KeyFieldName property specifies the field name that contains node keys. A node's key should be unique and cannot be empty. Since the column that corresponds to the key field is not typically shown in the tree list, the user cannot enter a value.

The code below also shows how to handle the TreeList.InitNewRow event to specify a key for a newly created node. In this example, the tree list uses integer values as node keys and the handler assigns the next available integer to the new node.

private void TreeList1_InitNewRow(object sender, DevExpress.XtraTreeList.TreeListInitNewRowEventArgs e) {
    e.SetValue("Status", 0);
    e.SetValue("StartDate", DateTime.Now);
    e.SetValue("DueDate", DateTime.Now.AddDays(7));
    e.SetValue("ID", treeList1.AllNodesCount);
}

Text in the Row

When the New-Item Row is located at the top of the list, it displays the default caption — "Click here to add a new row".

You can use the localization service to localize the default text. Use the TreeListStringId.NewItemRowText field to identify the string.

You can also use the TreeList.NewItemRowText property to provide a custom text. This custom text cannot be localized.

Example: How to Localize the Text in the Row

The code below shows how to use the localization service to localize the text displayed in the New-Item Row. Use the TreeListStringId.NewItemRowText field to identify the string.

using DevExpress.XtraTreeList.Localization;

TreeListLocalizer.Active = new NodeContextMenuLocalizer();

public class NodeContextMenuLocalizer : TreeListLocalizer {
    public override string Language { get { return "English"; } }
    public override string GetLocalizedString(TreeListStringId id) {
        switch (id) {
            case TreeListStringId.NewItemRowText: return "New Node";
            default: return base.GetLocalizedString(id);
        }
    }
}

Appearance

You can use the TreeList.Appearance.TopNewRow appearance setting's BackColor and ForeColor properties to specify the background and foreground colors for the New-Item Row.

Example: How to Customize Appearance Settings

The code below show how to change the New-Item Row's background and foreground colors.

treeList1.Appearance.TopNewRow.BackColor = System.Drawing.Color.AliceBlue;
treeList1.Appearance.TopNewRow.ForeColor = System.Drawing.Color.Fuchsia;

Context Menu

If the control displays the New-Item Row, the node context menu also contains the following commands:

  • Add Node — creates a new node at the same level as the focused node.
  • Add Child Node — creates a new child node for the focused node.

To hide/show these commands regardless of whether the New-Item Row is displayed, use the TreeList.OptionsMenu.ShowAddNodeItems option.

The InitNewRow event raises after a command is clicked. You can handle this event to initialize column values.