Rows
- 7 minutes to read
- Automatic Row Generation
- Base Row Settings
- Add and Remove Rows Manually
- Nested Rows
- Multi-Editor Rows
- Category Rows
- Hide Horizontal Row Borders
- Fixed Rows
- Identify and Access Grid Rows in Code
- Row Iterator
- Focus and Scroll Rows
- Expand and Collapse Rows
Automatic Row Generation
You can run the application to browse and edit data immediately after the Vertical Grid is bound to a data source since all rows are generated automatically. For code-first data sources (for example, Entity Framework models), you can mark a property with the Display attribute and disable its AutoGenerateField parameter to skip generating a column for this property. The “Display” attribute in the code below prevents a Vertical Grid from generating an “Additional Info” column.
[Display(AutoGenerateField = false, Description = "This column was not created")]
public string AdditionalInfo { get; set; }
You can utilize other attributes to re-arrange columns, modify header captions, change their default in-place editors, etc. Refer to the Data Annotation Attributes article to learn more.
The Vertical Grid does not automatically re-generate columns if you replaced a previous data source with a new one; you need to do it manually by invoking the Vertical Grid Designer and clicking the “Retrieve Fields” button within the “Rows” tab. You can also do this to restore the initial Grid state.
To do the same in code, call the VGridControlBase.RetrieveFields method either directly after changing a data source, or on the VGridControlBase.DataSourceChanged event.
Base Row Settings
The list below enumerates base row settings that you may need to modify.
- RowProperties.Caption - automatically generated rows display captions based on the data source field name. Modify this property to rename a row.
- VGridControlBase.RowHeaderWidth - gets or sets the width of a column that displays row captions. You can call the VGridControlBase.BestFit method to resize them in accordance to their content.
- RowProperties.ImageIndex - allows you to display images next to row headers. Images are retrieved from the VGridControlBase.ImageList collection.
- BaseOptionsView.MinRowAutoHeight, BaseOptionsView.MaxRowAutoHeight - utilize these properties to change the row height settings.
- VGridOptionsBehavior.ResizeRowHeaders, VGridOptionsRow.AllowSize - end-users can drag a row’s bottom border to resize it. Set these properties to false to disable this functionality.
- RowProperties.Format - allows you to apply a formatting rule to cell values.
Add and Remove Rows Manually
Rows associated with data fields declared in a data source are called bound rows. To add such rows manually, invoke the Designer, switch to the “Rows” tab and click the “Add (EditorRow)” button. Use the Property Grid to assign a data source field name to the newly created row’s RowProperties.FieldName property. Otherwise, the row is unbound and receives no data from the data source.
To remove a row, use the “Remove Column” designer button.
Regular data rows are EditorRow class objects.
Nested Rows
In the Designer “Row” tab, drag one row onto another to create a row hierarchy.
Related API
BaseRow.Expanded - gets or sets whether this parent row is expanded.
BaseRow.ChildRows, BaseRow.ParentRow - allow you to build row parent-child relationships in code.
BaseOptionsView.LevelIndent - an integer value that specifies the row horizontal offset. To remove this offset for root level rows, disable the BaseOptionsView.ShowRootLevelIndent setting.
To move a child row from its parent back to the top level, drag-and-drop it while pressing the “Ctrl” key.
To created nested rows in code, place new rows inside existing rows’ BaseRow.ChildRows collection. If you need to categorize existing rows instead, call the VGridControlBase.MoveRow method.
//existing rows
vGridControl1.MoveRow(rowModel, rowMain, false);
vGridControl1.MoveRow(rowCategory, rowModel, false);
vGridControl1.MoveRow(rowTrademark, rowModel, true);
//new rows
EditorRow rowModel = new EditorRow("Model");
rowModel.Properties.Caption = "Model";
rowMain.ChildRows.Add(rowModel);
EditorRow rowCategory = new EditorRow("Category");
rowCategory.Properties.Caption = "Category";
rowModel.ChildRows.Add(rowCategory);
EditorRow rowTrademark = new EditorRow("Trademark");
rowTrademark.Properties.Caption = "Trademark";
rowModel.ChildRows.Add(rowTrademark);
The sample below illustrates how to implement the “Shift+Up” and “Shift+Down” hotkeys that make a currently focused row an upper row’s child or a lower row’s parent.
private void vGridControl1_KeyDown(object sender, KeyEventArgs e) {
VGridControl vGrid = sender as VGridControl;
BaseRow row = vGrid.FocusedRow;
BaseRow prevRow = vGrid.GetPrevVisible(row);
BaseRow nextRow = vGrid.GetNextVisible(row);
if ((e.KeyCode == Keys.Up) && (e.Shift)) {
if ((row == null) || (prevRow == null)) return;
vGrid.MoveRow(row, prevRow, false);
}
if ((e.KeyCode == Keys.Down) && (e.Shift)) {
if ((row == null) || (nextRow == null)) return;
vGrid.MoveRow(nextRow, row, false);
}
}
Multi-Editor Rows
Multi-editor rows (MultiEditorRow objects) combine multiple simple data rows into one, using a more compact layout to display data.
Use the Grid Designer to add multi-editor rows.
To populate your multi-editor row, modify the MultiEditorRow.PropertiesCollection. Each collection item represents a regular EditRow with standard settings - Caption, FieldName, etc.
The following sample illustrates how to add a multi-editor row in code:
MultiEditorRow meRow = new MultiEditorRow();
meRow.PropertiesCollection.Add(new MultiEditorRowProperties() { FieldName = "Name", Caption = "Full Name" });
meRow.PropertiesCollection.Add(new MultiEditorRowProperties() { FieldName = "Category", Caption = "Product Category" });
meRow.PropertiesCollection.Add(new MultiEditorRowProperties() { FieldName = "Color", Caption = "Color" });
vGridControl1.Rows.Add(meRow);
Vertical dashes separate individual value and header cells by default. You can replace these dashes with a custom string by changing the MultiEditorRow.SeparatorKind to String and specifying the MultiEditorRow.SeparatorString property. In the figure below an “x” character serves as a custom separator.
Category Rows
Category rows allow you to organize multiple data rows into a group and provide a caption for it.
To add categories, go to the Designer “Rows” tab and use the “Add” button’s drop-down menu. Then drag-and-drop regular data rows onto this category to populate it.
Related API
- BaseRow.Expanded - allows you to expand and collapse categories manually.
- BaseOptionsView.CategoryLevelIndentStyle - specifies whether categories have a vertical indent that visually separates them from regular data rows.
- VGridControlBase.TreeButtonStyle - specifies the expand\collapse buttons’ style and alignment.
The CategoryRow class instances represent categories in code. The following sample illustrates how to add a category:
CategoryRow cRow = new CategoryRow();
cRow.Properties.Caption = "Main Specs";
cRow.ChildRows.AddRange(new BaseRow[] { row1, row2, row3 });
cRow.Expanded = false;
vGridControl1.Rows.Insert(cRow, propertyGridControl1.Rows.Count - 1);
Hide Horizontal Row Borders
You can hide Vertical Grid’s horizontal and vertical lines by disabling the BaseOptionsView.ShowHorzLines and BaseOptionsView.ShowVertLines settings.
Fixed Rows
If a Vertical Grid control is too small to display all rows at once, it deploys a vertical scrollbar. Rows can anchor to the control’s top or bottom edge and remain visible as users scroll through records. To make a row fixed, specify its BaseRow.Fixed property. In the following animation, the “Appearance” category is anchored to the control’s top.
Important
The BaseRow.Fixed property is in effect only for the top-tier rows. If a row is another row’s child or belongs to a category, it cannot be anchored. As an alternative, specify the Fixed property for the parent row.
To retrieve fixed rows, access the VGridControlBase.FixedTopRows and VGridControlBase.FixedBottomRows collections.
Identify and Access Grid Rows in Code
Use the following API to retrieve specific rows:
-
Stores all columns that belong to this View and provides access to them by indexes or related data field names.
VGridControlBase.GetRowByFieldName, VGridRows.GetRowByFieldName
Retrieve a row associated with the specific data source field.
-
Retrieves a row to which a currently focused cell belongs.