Skip to main content

ColumnView.FocusedRowHandle Property

Read this property value to retrieve the currently selected row’s handle. Modify the property to manually select a row with the given handle.

Namespace: DevExpress.XtraGrid.Views.Base

Assembly: DevExpress.XtraGrid.v24.1.dll

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

Declaration

[Browsable(false)]
public int FocusedRowHandle { get; set; }

Property Value

Type Description
Int32

An integer value that is the handle of the focused record.

Remarks

Records within a View (rows in a Grid View and cards in a Card View) are identified by their handles. The FocusedRowHandle property allows you to get the currently selected row’s handle, or to move focus to a row with the specific handle. In the latter case, the Data Grid expands a group that contains this row, and scrolls the View up or down to make this row visible.

If there is no focused record, the FocusedRowHandle property returns the GridControl.InvalidRowHandle value. For instance, this value is returned when the View is empty. Note that if a Grid View has any records, you cannot set the FocusedRowHandle property to the GridControl.InvalidRowHandle value to deselect the currently focused row.

Note

The FocusedRowHandle property should be used only when a Grid is completely initialized. If you need to set a new value for this property when the form loads, call the GridControl.ForceInitialize method first to ensure the control is ready.

When row focus changes, the ColumnView.FocusedRowChanged and ColumnView.FocusedRowObjectChanged events are raised.

In Layouts and Card Views, when you change the FocusedRowHandle property value, the ColumnView.FocusedColumn property resets to null. In this instance, you may want to manually edit the FocusedColumn property to move focus to a specific card field.

Multiple Row/Card Selection Mode

The focused row/card is the only one that accepts input from an end user. For that reason, a View can have only one focused row even if multiple row/card selection is enabled.

In multiple row/card selection mode, a focused row can be unselected (not highlighted) and vice versa, a selected (highlighted) row can be unfocused. The following images illustrate these cases.

MultiSelect-FocusedRowSelected

The focused “Condiments” row is selected. The ColumnView.GetSelectedRows method returns three row handles, including the focused row handle.

MultiSelect-FocusedRowDeSelected.png

The focused “Condiments” row is not selected; the selected “Dairy Products” and “Grains, Cereals” rows are not focused. The ColumnView.GetSelectedRows method returns an array that contains two handles and does not include the focused row handle.

See the Multiple Row and Cell Selection topic for more information.

Note

Detail pattern Views do not contain data and they are never displayed within XtraGrid. So, the FocusedRowHandle member must not be invoked for these Views. The FocusedRowHandle member can only be used with Views that display real data within the Grid Control. Use the following methods to access these Views with which an end user interacts at runtime.

Example

The following example creates a GridControl at runtime and shows how to perform basic customization tasks:

  • Bind the grid to a data source
  • Access the View that displays the underlying data
  • Access columns
  • Assign an in-place editor (a combo box editor) to a column
  • Sort and group data
  • Calculate total and group summaries
  • Create a filter
  • Hide columns and calculate column “best” widths
  • Expand group rows
  • Focus a specific cell
  • Specify DataAnnotation attributes (column display names and data formats) at the data source level

Note

Add the corresponding assemblies to your Windows Forms project.

Read the following topic for information: Redistribution and Deployment.

Grid-create-at-runtime

using System;
using DevExpress.ClipboardSource.SpreadsheetML;
using DevExpress.Data;
using DevExpress.XtraEditors;
using DevExpress.XtraEditors.Repository;
using DevExpress.XtraGrid;
using DevExpress.XtraGrid.Columns;
using DevExpress.XtraGrid.Views.Grid;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations;
using System.Runtime.CompilerServices;
using System.Windows.Forms;

namespace DXApplication {
    public partial class Form1 : XtraForm {
        public Form1() {
            InitializeComponent();
            this.Load += Form1_Load;
        }
        private void Form1_Load(object sender, EventArgs e) {
            GridControl gridControl1 = new GridControl() {
                Name = "gridControl1",
                Parent = this,
                Dock = DockStyle.Fill
            };
            gridControl1.DataSource = DataHelper.GetData(30);
            // The grid automatically creates columns for the public fields found in the data source. 
            // Calling the gridView1.PopulateColumns method is not required unless gridView1.OptionsBehavior.AutoPopulateColumns is disabled.

            // The grid automatically creates a GridView that displays the underlying data as a two-dimensional table.
            GridView gridView1 = gridControl1.MainView as GridView;

            // Obtain created columns.
            GridColumn colCompany = gridView1.Columns["CompanyName"];
            GridColumn colID = gridView1.Columns["ID"];
            GridColumn colDate = gridView1.Columns["RequiredDate"];
            GridColumn colPayment = gridView1.Columns["Value"];
            GridColumn colProcessed = gridView1.Columns["Processed"];

            // The Company column uses a ComboBox in-place editor that shows a list of available companies.
            RepositoryItemComboBox riComboBox = new RepositoryItemComboBox();
            riComboBox.Items.AddRange(DataHelper.companies);
            gridControl1.RepositoryItems.Add(riComboBox);
            colCompany.ColumnEdit = riComboBox;

            // Hide a column.
            colID.Visible = false;

            // Group and sort data.
            colCompany.GroupIndex = 0;
            colDate.SortIndex = 0;
            colDate.SortOrder = DevExpress.Data.ColumnSortOrder.Descending;

            // Show group columns in the table.
            gridView1.OptionsView.ShowGroupedColumns = true;

            // Expand group rows.
            gridView1.ExpandAllGroups();

            // Apply a filter.
            gridView1.ActiveFilterString = "[RequiredDate]>= #" + DateTime.Today.ToString() + "#";

            // Calculate two total summaries.
            colDate.Summary.Add(SummaryItemType.Count, colDate.FieldName, "Count={0}");
            colDate.Summary.Add(SummaryItemType.Max, colDate.FieldName, "Max={0:d}");
            gridView1.OptionsView.ShowFooter = true;

            // Calculate group summaries.
            GridGroupSummaryItem item = new GridGroupSummaryItem();
            item.FieldName = colCompany.FieldName;
            item.SummaryType = DevExpress.Data.SummaryItemType.Count;
            gridView1.GroupSummary.Add(item);

            GridGroupSummaryItem item1 = new GridGroupSummaryItem();
            item1.FieldName = colPayment.FieldName;
            item1.SummaryType = SummaryItemType.Sum;
            item1.DisplayFormat = "group total={0:c2}";
            item1.ShowInGroupColumnFooter = colPayment;
            gridView1.GroupSummary.Add(item1);

            // Forcibly move group footer summaries to positions in group rows under corresponding column headers. 
            gridView1.OptionsBehavior.AlignGroupSummaryInGroupRow = DevExpress.Utils.DefaultBoolean.True;

            // Focus a specific cell.
            gridView1.FocusedRowHandle = 1;
            gridView1.FocusedColumn = colCompany;

            // Optimize column widths.
            colDate.BestFit();
            colProcessed.BestFit();
        }
    }

    public class Record : INotifyPropertyChanged {
        public Record() {
        }
        int id;
        public int ID {
            get { return id; }
            set {
                if(id != value) {
                    id = value;
                    OnPropertyChanged();
                }
            }
        }

        string text;
        [DisplayName("Company")]
        public string CompanyName {
            get { return text; }
            set {
                if(text != value) {
                    if(string.IsNullOrEmpty(value))
                        throw new Exception();
                    text = value;
                    OnPropertyChanged();
                }
            }
        }
        Nullable<decimal> val;
        [DataType(System.ComponentModel.DataAnnotations.DataType.Currency)]
        [DisplayName("Payment")]
        public Nullable<decimal> Value {
            get { return val; }
            set {
                if(val != value) {
                    val = value;
                    OnPropertyChanged();
                }
            }
        }
        DateTime dt;
        [DisplayFormat(DataFormatString = "d")]
        public DateTime RequiredDate {
            get { return dt; }
            set {
                if(dt != value) {
                    dt = value;
                    OnPropertyChanged();
                }
            }
        }
        bool state;
        public bool Processed {
            get { return state; }
            set {
                if(state != value) {
                    state = value;
                    OnPropertyChanged();
                }
            }
        }

        public override string ToString() {
            return string.Format("ID = {0}, Text = {1}", ID, CompanyName);
        }

        public event PropertyChangedEventHandler PropertyChanged;
        protected void OnPropertyChanged([CallerMemberName] string propertyName = "") {
            if(PropertyChanged != null)
                PropertyChanged(this, new PropertyChangedEventArgs(propertyName));
        }
    }

    public class DataHelper {

        public static string[] companies = new string[] { "Hanari Carnes", "Que Delícia", "Romero y tomillo", "Mère Paillarde",
            "Comércio Mineiro", "Reggiani Caseifici", "Maison Dewey" };
        public static BindingList<Record> GetData(int count) {
            BindingList<Record> records = new BindingList<Record>();
            Random rnd = new Random();
            for(int i = 0; i < count; i++) {
                int n = rnd.Next(10);
                records.Add(new Record() {
                    ID = i + 100,
                    CompanyName = companies[i % companies.Length],
                    RequiredDate = DateTime.Today.AddDays(n - 5),
                    Value = i % 2 == 0 ? (i + 1) * 123 : i * 231,
                    Processed = i % 2 == 0,
                });
            };
            return records;
        }
    }

}

The following code snippets (auto-collected from DevExpress Examples) contain references to the FocusedRowHandle property.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

See Also