Esta documentación está archivada y no tiene mantenimiento.

DataGrid (Clase)

Muestra datos de ADO.NET en una cuadrícula desplazable. El control DataGridView reemplaza y agrega funcionalidad al control DataGrid; sin embargo, el control DataGrid se conserva para compatibilidad con versiones anteriores y para uso futuro, si así se elige.

Espacio de nombres: System.Windows.Forms
Ensamblado: System.Windows.Forms (en system.windows.forms.dll)

[ComVisibleAttribute(true)] 
[ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch)] 
public class DataGrid : Control, ISupportInitialize, IDataGridEditingService
/** @attribute ComVisibleAttribute(true) */ 
/** @attribute ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) */ 
public class DataGrid extends Control implements ISupportInitialize, IDataGridEditingService
ComVisibleAttribute(true) 
ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) 
public class DataGrid extends Control implements ISupportInitialize, IDataGridEditingService
No aplicable.

System.Windows.Forms.DataGrid muestra vínculos de tipo Web a las tablas secundarias. Para desplazarse a la tabla secundaria, haga clic en un vínculo. Cuando se muestra una tabla secundaria, aparece en el título un botón de retroceso en el que se puede hacer clic para volver a la tabla primaria. Los datos de las filas primarias se muestran debajo del título y encima de los encabezados de columna. Para ocultar la información de las filas primarias, haga clic en el botón situado a la derecha del botón de retroceso.

Para mostrar una tabla en System.Windows.Forms.DataGrid en tiempo de ejecución, utilice el método SetDataBinding para establecer las propiedades DataSource y DataMember en un origen de datos válido. Son válidos los siguientes orígenes de datos:

Para obtener más información sobre la clase DataSet, vea Utilizar DataSets en ADO.NET.

Se puede crear una cuadrícula que permita a los usuarios editar los datos pero que les impida agregar nuevas filas; para ello, se debe utilizar DataView como origen de datos y establecer el valor de la propiedad AllowNew en false.

Los objetos BindingManagerBase administran asimismo los orígenes de datos. Para cada tabla de un origen de datos, se puede devolver un objeto BindingManagerBase desde BindingContext del formulario. Por ejemplo, se puede determinar el número de filas de un origen de datos devolviendo la propiedad Count del objeto BindingManagerBase asociado.

Para validar los datos, utilice los objetos subyacentes que representan los datos y sus eventos. Por ejemplo, si los datos proceden de un objeto DataTable de DataSet, utilice los eventos ColumnChanging y RowChanging.

NotaNota:

Dado que es posible personalizar el número de columnas (agregando o eliminando miembros de GridColumnStylesCollection) y que las filas pueden ordenarse por columna, no es posible garantizar que los valores de las propiedades RowNumber y ColumnNumber se correspondan con los índices de DataRow y DataColumn en DataTable. Por este motivo, se ha de evitar el uso de dichas propiedades en el evento Validating para validar los datos.

Para determinar la celda seleccionada, utilice la propiedad CurrentCell. Para cambiar el valor de cualquier celda, utilice la propiedad Item, que puede adoptar los índices de fila y columna de la celda o un solo objeto DataGridCell. Supervise el evento CurrentCellChanged para detectar cuándo el usuario selecciona otra celda.

Para determinar en qué parte del control ha hecho clic el usuario, utilice el método HitTest en el evento MouseDown. El método HitTest devuelve un objeto DataGrid.HitTestInfo, que contiene la fila y la columna de un área en la que se ha hecho clic.

Para administrar la apariencia del control en tiempo de ejecución, existen varias propiedades que permiten establecer los atributos de color y título, incluidas las propiedades CaptionForeColor, CaptionBackColor, CaptionFont, etc.

La apariencia de la cuadrícula o cuadrículas mostradas puede modificarse también creando objetos DataGridTableStyle y agregándolos a la colección GridTableStylesCollection, a la que se puede obtener acceso mediante la propiedad TableStyles. Por ejemplo, si la propiedad DataSource está establecida en una clase DataSet que contiene tres objetos DataTable, se pueden agregar tres objetos DataGridTableStyle a la colección, uno por cada tabla. Para sincronizar cada objeto DataGridTableStyle con un objeto DataTable, establezca la propiedad MappingName de DataGridTableStyle en TableName de DataTable. Para obtener más información sobre la forma de enlazarse a una matriz de objetos, vea la propiedad DataGridTableStyle.MappingName.

Para crear una vista personalizada de una tabla, hay que crear una instancia de una clase DataGridTextBoxColumn o DataGridBoolColumn y agregar el objeto a la colección GridTableStylesCollection, a la que se obtiene acceso a través de la propiedad TableStyles. Ambas clases se heredan de DataGridColumnStyle. Para cada estilo de columna, hay que establecer la propiedad MappingName en ColumnName de una columna que se desee mostrar en la cuadrícula. Para ocultar una columna, establezca su propiedad MappingName en un valor que no sea una propiedad ColumnName válida.

Para aplicar formato al texto de una columna, hay que establecer la propiedad Format de DataGridTextBoxColumn en uno de los valores de Cadenas de formato de fecha y hora o Cadenas con formato numérico estándar.

Para enlazar DataGrid a una matriz de objetos con establecimiento inflexible de tipos, el tipo de objeto debe contener propiedades públicas. Para crear un control DataGridTableStyle que muestre la matriz, establezca la propiedad DataGridTableStyle.MappingName en typename[] donde el nombre del tipo de objeto reemplaza a typename. Observe también que la propiedad MappingName distingue entre mayúsculas y minúsculas; el nombre de tipo debe coincidir exactamente. Para obtener un ejemplo, vea la propiedad MappingName.

También es posible enlazar DataGrid a ArrayList. Una característica de ArrayList es que puede contener objetos de varios tipos, pero DataGrid sólo puede enlazarse a dicha lista si todos los elementos de la lista son del mismo tipo que el primero. Esto significa que todos los objetos deben ser del mismo tipo o que deben heredarse de la misma clase que el primer elemento de la lista. Por ejemplo, si el primer elemento de una lista es Control, el segundo elemento podría ser TextBox (que se hereda de Control). En cambio, si el primer elemento es TextBox, el segundo objeto no puede ser Control. Además, ArrayList debe contener elementos en el momento de enlazarse. Una lista ArrayList vacía dará como resultado una cuadrícula vacía. Además, los objetos en el control ArrayList deben contener propiedades públicas. Para enlazarse a ArrayList, hay que establecer la propiedad MappingName de DataGridTableStyle en "ArrayList" (el nombre de tipo).

Para cada DataGridTableStyle, se pueden establecer los atributos de color y título que reemplazan los valores del control System.Windows.Forms.DataGrid. Sin embargo, si no se establecen dichas propiedades, se utilizan los valores del control de manera predeterminada. Las propiedades DataGridTableStyle pueden reemplazar las siguientes propiedades:

Para personalizar la apariencia de columnas individuales, agregue objetos DataGridColumnStyle a la colección GridColumnStylesCollection, a la que se obtiene acceso mediante la propiedad GridColumnStyles de cada DataGridTableStyle. Para sincronizar cada objeto DataGridColumnStyle con un objeto DataColumn en DataTable, establezca la propiedad MappingName en la propiedad ColumnName de un objeto DataColumn. Al construir un objeto DataGridColumnStyle, también se puede establecer una cadena de formato que especifica el modo en que se muestran los datos en la columna. Por ejemplo, se puede especificar que la columna utilice un formato de fecha corta para mostrar las fechas que contiene la tabla.

Nota de precauciónPrecaución:

Primero deben crearse los objetos DataGridColumnStyle y, después, deben agregarse a GridColumnStylesCollection antes de agregar los objetos DataGridTableStyle a GridTableStylesCollection. Cuando se agrega un objeto DataGridTableStyle vacío con un valor válido MappingName a la colección, se generan automáticamente objetos DataGridColumnStyle. Por lo tanto, se producirá una excepción si se intentan agregar nuevos objetos DataGridColumnStyle a GridColumnStylesCollection con valores de MappingName duplicados.

NotaNota:

El control DataGridView reemplaza y agrega funcionalidad al control DataGrid; sin embargo, el control DataGrid se conserva para mantener la compatibilidad con versiones anteriores y para uso futuro, si así se elige. Para obtener más información, vea Diferencias entre los controles DataGridView y DataGrid de formularios Windows Forms.

En el siguiente ejemplo de código se crean un formulario de Windows, una clase DataSet que contiene dos objetos DataTable y un objeto DataRelation que relaciona las dos tablas. Para mostrar los datos, se enlaza un control System.Windows.Forms.DataGrid a DataSet mediante el método SetDataBinding. Un botón del formulario cambia la apariencia de la cuadrícula creando dos objetos DataGridTableStyle y estableciendo la propiedad MappingName de cada objeto en una propiedad TableName de uno de los objetos DataTable. El ejemplo contiene también código en el evento MouseUp que utiliza el método HitTest para imprimir la columna, la fila y la parte de la cuadrícula en la que se ha hecho clic.

using System;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Windows.Forms;

public class Form1 : System.Windows.Forms.Form
{
   private System.ComponentModel.Container components;
   private Button button1;
   private Button button2;
   private DataGrid myDataGrid;   
   private DataSet myDataSet;
   private bool TablesAlreadyAdded;
   public Form1()
   {
      // Required for Windows Form Designer support.
      InitializeComponent();
      // Call SetUp to bind the controls.
      SetUp();
   }

   protected override void Dispose( bool disposing ){
      if( disposing ){
         if (components != null){
            components.Dispose();}
      }
      base.Dispose( disposing );
   }
   private void InitializeComponent()
   {
      // Create the form and its controls.
      this.components = new System.ComponentModel.Container();
      this.button1 = new System.Windows.Forms.Button();
      this.button2 = new System.Windows.Forms.Button();
      this.myDataGrid = new DataGrid();
      
      this.Text = "DataGrid Control Sample";
      this.ClientSize = new System.Drawing.Size(450, 330);
      
      button1.Location = new Point(24, 16);
      button1.Size = new System.Drawing.Size(120, 24);
      button1.Text = "Change Appearance";
      button1.Click+=new System.EventHandler(button1_Click);

      button2.Location = new Point(150, 16);
      button2.Size = new System.Drawing.Size(120, 24);
      button2.Text = "Get Binding Manager";
      button2.Click+=new System.EventHandler(button2_Click);

      myDataGrid.Location = new  Point(24, 50);
      myDataGrid.Size = new Size(300, 200);
      myDataGrid.CaptionText = "Microsoft DataGrid Control";
      myDataGrid.MouseUp += new MouseEventHandler(Grid_MouseUp);
      
      this.Controls.Add(button1);
      this.Controls.Add(button2);
      this.Controls.Add(myDataGrid);
   }

   public static void Main()
   {
      Application.Run(new Form1());
   }
   
   private void SetUp()
   {
      // Create a DataSet with two tables and one relation.
      MakeDataSet();
      /* Bind the DataGrid to the DataSet. The dataMember
      specifies that the Customers table should be displayed.*/
      myDataGrid.SetDataBinding(myDataSet, "Customers");
   }

   private void button1_Click(object sender, System.EventArgs e)
   {
      if(TablesAlreadyAdded) return;
      AddCustomDataTableStyle();
   }

   private void AddCustomDataTableStyle()
   {
      DataGridTableStyle ts1 = new DataGridTableStyle();
      ts1.MappingName = "Customers";
      // Set other properties.
      ts1.AlternatingBackColor = Color.LightGray;

      /* Add a GridColumnStyle and set its MappingName 
      to the name of a DataColumn in the DataTable. 
      Set the HeaderText and Width properties. */
      
      DataGridColumnStyle boolCol = new DataGridBoolColumn();
      boolCol.MappingName = "Current";
      boolCol.HeaderText = "IsCurrent Customer";
      boolCol.Width = 150;
      ts1.GridColumnStyles.Add(boolCol);
      
      // Add a second column style.
      DataGridColumnStyle TextCol = new DataGridTextBoxColumn();
      TextCol.MappingName = "custName";
      TextCol.HeaderText = "Customer Name";
      TextCol.Width = 250;
      ts1.GridColumnStyles.Add(TextCol);

      // Create the second table style with columns.
      DataGridTableStyle ts2 = new DataGridTableStyle();
      ts2.MappingName = "Orders";

      // Set other properties.
      ts2.AlternatingBackColor = Color.LightBlue;
      
      // Create new ColumnStyle objects
      DataGridColumnStyle cOrderDate = 
      new DataGridTextBoxColumn();
      cOrderDate.MappingName = "OrderDate";
      cOrderDate.HeaderText = "Order Date";
      cOrderDate.Width = 100;
      ts2.GridColumnStyles.Add(cOrderDate);

      /* Use a PropertyDescriptor to create a formatted
      column. First get the PropertyDescriptorCollection
      for the data source and data member. */
      PropertyDescriptorCollection pcol = this.BindingContext
      [myDataSet, "Customers.custToOrders"].GetItemProperties();
 
      /* Create a formatted column using a PropertyDescriptor.
      The formatting character "c" specifies a currency format. */     
      DataGridColumnStyle csOrderAmount = 
      new DataGridTextBoxColumn(pcol["OrderAmount"], "c", true);
      csOrderAmount.MappingName = "OrderAmount";
      csOrderAmount.HeaderText = "Total";
      csOrderAmount.Width = 100;
      ts2.GridColumnStyles.Add(csOrderAmount);

      /* Add the DataGridTableStyle instances to 
      the GridTableStylesCollection. */
      myDataGrid.TableStyles.Add(ts1);
      myDataGrid.TableStyles.Add(ts2);

     // Sets the TablesAlreadyAdded to true so this doesn't happen again.
     TablesAlreadyAdded=true;
   }

   private void button2_Click(object sender, System.EventArgs e)
   {
      BindingManagerBase bmGrid;
      bmGrid = BindingContext[myDataSet, "Customers"];
      MessageBox.Show("Current BindingManager Position: " + bmGrid.Position);
   }

   private void Grid_MouseUp(object sender, MouseEventArgs e)
   {
      // Create a HitTestInfo object using the HitTest method.

      // Get the DataGrid by casting sender.
      DataGrid myGrid = (DataGrid)sender;
      DataGrid.HitTestInfo myHitInfo = myGrid.HitTest(e.X, e.Y);
      Console.WriteLine(myHitInfo);
      Console.WriteLine(myHitInfo.Type);
      Console.WriteLine(myHitInfo.Row);
      Console.WriteLine(myHitInfo.Column);
   }

   // Create a DataSet with two tables and populate it.
   private void MakeDataSet()
   {
      // Create a DataSet.
      myDataSet = new DataSet("myDataSet");
      
      // Create two DataTables.
      DataTable tCust = new DataTable("Customers");
      DataTable tOrders = new DataTable("Orders");

      // Create two columns, and add them to the first table.
      DataColumn cCustID = new DataColumn("CustID", typeof(int));
      DataColumn cCustName = new DataColumn("CustName");
      DataColumn cCurrent = new DataColumn("Current", typeof(bool));
      tCust.Columns.Add(cCustID);
      tCust.Columns.Add(cCustName);
      tCust.Columns.Add(cCurrent);

      // Create three columns, and add them to the second table.
      DataColumn cID = 
      new DataColumn("CustID", typeof(int));
      DataColumn cOrderDate = 
      new DataColumn("orderDate",typeof(DateTime));
      DataColumn cOrderAmount = 
      new DataColumn("OrderAmount", typeof(decimal));
      tOrders.Columns.Add(cOrderAmount);
      tOrders.Columns.Add(cID);
      tOrders.Columns.Add(cOrderDate);

      // Add the tables to the DataSet.
      myDataSet.Tables.Add(tCust);
      myDataSet.Tables.Add(tOrders);

      // Create a DataRelation, and add it to the DataSet.
      DataRelation dr = new DataRelation
      ("custToOrders", cCustID , cID);
      myDataSet.Relations.Add(dr);
   
      /* Populates the tables. For each customer and order, 
      creates two DataRow variables. */
      DataRow newRow1;
      DataRow newRow2;

      // Create three customers in the Customers Table.
      for(int i = 1; i < 4; i++)
      {
         newRow1 = tCust.NewRow();
         newRow1["custID"] = i;
         // Add the row to the Customers table.
         tCust.Rows.Add(newRow1);
      }
      // Give each customer a distinct name.
      tCust.Rows[0]["custName"] = "Customer1";
      tCust.Rows[1]["custName"] = "Customer2";
      tCust.Rows[2]["custName"] = "Customer3";

      // Give the Current column a value.
      tCust.Rows[0]["Current"] = true;
      tCust.Rows[1]["Current"] = true;
      tCust.Rows[2]["Current"] = false;

      // For each customer, create five rows in the Orders table.
      for(int i = 1; i < 4; i++)
      {
         for(int j = 1; j < 6; j++)
         {
            newRow2 = tOrders.NewRow();
            newRow2["CustID"]= i;
            newRow2["orderDate"]= new DateTime(2001, i, j * 2);
            newRow2["OrderAmount"] = i * 10 + j  * .1;
            // Add the row to the Orders table.
            tOrders.Rows.Add(newRow2);
         }
      }
   }
}

Los miembros estáticos públicos (Shared en Visual Basic) de este tipo son seguros para la ejecución de subprocesos. No se garantiza que los miembros de instancias sean seguros para la ejecución de subprocesos.

Windows 98, Windows 2000 Service Pack 4, Windows CE, Windows Millennium, Windows Mobile para Pocket PC, Windows Mobile para Smartphone, Windows Server 2003, Windows XP Media Center, Windows XP Professional x64, Windows XP SP2, Windows XP Starter

Microsoft .NET Framework 3.0 es compatible con Windows Vista, Microsoft Windows XP SP2 y Windows Server 2003 SP1.

.NET Framework

Compatible con: 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Compatible con: 2.0, 1.0
Mostrar: