System.Web 2.0.0.0 System.Web.UI.WebControls.DataControlField

The class is used by data-bound controls (such as and ) to display the value of a field as text. The object is displayed differently depending on the data-bound control in which it is used. For example, the control displays a object as a column, while the control displays it as a row.

To specify the field to display in a object, set the property to the field's name. The field's value can be HTML-encoded before it is displayed by setting the property to true. You can apply a custom formatting string to the field's value by setting the property. When the property is true, the encoded string value of the field is used in the custom format string. By default, the formatting string is applied to field values only when the data-bound control is in read-only mode. To apply the formatting string to values displayed while the data-bound control is in edit mode, set the property to true. If a field's value is null, you can display a custom caption by setting the property. The object can also automatically convert empty string ("") field values to null values by setting the property to true.

You can hide a object in a data-bound control by setting the property to false. To prevent the value of a field from being modified in edit mode, set the property to true. In data-bound controls that support inserting records (such as the control), you can hide a object by setting the property to false. This is commonly done when you want to hide an automatically generated key field in insert mode.

You can customize the header and footer sections of a object. To display a caption in the header or footer sections, set the or properties, respectively. Instead of displaying text in the header section, you can display an image by setting the property. The header section can be hidden in the object by setting the property to false.

Some data-bound controls (such as the control) can show or hide only the entire header section of the control. These data-bound controls do not support the property for an individual bound field. To show or hide the entire header section of a data-bound control (if available), use the control's ShowHeader property.

You also can customize the appearance of the object (font color, background color, and so on) by setting the style properties for the different parts of the field. The following table lists the different style properties.

Style property

Description

The style settings for the child Web server controls of the object.

The style settings for the footer section of the object.

The style settings for the header section of the object.

The style settings for the data items in the object.

Represents a field that is displayed as text in a data-bound control.

- Constructor

  Use this constructor to initialize a new instance of the class. This constructor is commonly used when adding fields to a dynamically created data-bound control.

  To dynamically add a object to a data-bound control, create a new object, set its properties, and then add it to the data-bound control's field collection. For example, if you are using the control, add the object to the collection.

  Although you can dynamically add fields to a data-bound control, it is strongly recommended that fields be statically declared and then shown or hidden, as appropriate. Statically declaring all of your fields reduces the size of the view state for the parent data-bound control.

  Initializes a new instance of the class.

  2.0.0.0
- Property
  System.ComponentModel.DefaultValue(false)
  System.Boolean To be added.

  Data-bound controls (such as , , and ) have different display modes that allow the user to read, edit, or insert records. By default, the formatting string specified by the property is applied to field values only when the data-bound control is in read-only mode. To apply the formatting string to values displayed while the data-bound control is in edit mode, set the property to true.

  A object does not automatically remove the formatting when the field is updated in the data source. If you do not want the formatting as part of the value stored, you will need to remove the formatting programmatically.

  Gets or sets a value indicating whether the formatting string specified by the property is applied to field values when the data-bound control that contains the object is in edit mode.

  2.0.0.0
- Property
  System.ComponentModel.DefaultValue(true)
  System.Boolean To be added.

  Sometimes the user might enter an empty string for a field value when updating or inserting records. Use the property to specify whether an empty string value is automatically converted to null when the data field is updated in the data source.

  By default, a object displays null values as empty strings. To display a different value, set the property.

  Gets or sets a value indicating whether empty string values ("") are automatically converted to null values when the data field is updated in the data source.

  2.0.0.0
- Method
  System.Void ``

  The method is a helper method used by the method to copy the properties of the current object to the object created by the method.

  Copies the properties of the current object to the specified object.

  The to copy the properties of the current to. 2.0.0.0
- Method
  System.Web.UI.WebControls.DataControlField

  The method is a helper method used by the method to create an empty object to copy the properties of the current object to.

  Creates an empty object.

  An empty .

  2.0.0.0
- Property
  System.ComponentModel.DefaultValue("")
  System.ComponentModel.TypeConverter("System.Web.UI.Design.DataSourceViewSchemaConverter, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")
  System.String To be added.

  Use the property to specify the name of the data field to bind to the object. The values of the specified field are displayed in the object as text. You can optionally format the displayed text by setting the property.

  If a field's value is null, an empty string ("") is displayed for the value by default. To specify an alternate caption, set the property.

  Gets or sets the name of the data field to bind to the object.

  2.0.0.0
- Property
  System.ComponentModel.DefaultValue("")
  System.String To be added.

  Use the property to specify a custom display format for the values that are displayed in the object. If the property is not set, the field's value is displayed without any special formatting.

  In versions of ASP.NET earlier than 3.5, you must set the property to false in order to format fields that are not string data types. Otherwise, the field value is converted to a string by the default conversion method before the format string that is stored in the property is applied.

  By default, the formatting string is applied to the field value only when the data-bound control that contains the object is in read-only mode. To apply the formatting string to field values while in edit mode, set the property to true.

  The formatting string can be any literal string and usually includes a placeholder for the field's value. For example, in the formatting string Item Value: {0}, the field's value is substituted for the {0} placeholder when the string is displayed in the object. The rest of the formatting string is displayed as literal text.

  If the formatting string does not include a placeholder, only the formatting string itself is included in the final display text (the field's value from the data source is not included). If the placeholder is a 0 (zero) enclosed in curly braces as shown in the preceding example, the field value is converted to a string by the default method. You can append to the zero a string that specifies how the field value should be formatted. For example, the placeholder {0:C} for a numeric field specifies that value of the field should be converted to a currency format.

  Formatting is applied by using the method. The number that follows the left curly brace is part of the syntax used by that method and indicates which one of a series of values the placeholder should use. Because there is only one field value in each cell, the number that follows the left curly brace can only be set to 0.

  The following table lists the standard format characters for numeric fields. These format characters are not case-sensitive, except for X, which displays hexadecimal characters in the case that is specified. You can append a number to most format characters in order to specify how many significant digits or decimal places you want to display.

  In most cases, formatting depends on the server's culture setting. The examples are for a culture setting of en-US.

  Format character

  Description

  Example

  C or c

  Displays numeric values in currency format. You can specify the number of decimal places.

  Format: {0:C}

  123.456 -> $123.46

  Format: {0:C3}

  123.456 -> $123.456

  D or d

  Displays integer values in decimal format. You can specify the number of digits. (Although the type is referred to as "decimal", the numbers are formatted as integers.)

  Format: {0:D}

  1234 -> 1234

  Format: {0:D6}

  1234 -> 001234

  E or e

  Displays numeric values in scientific (exponential) format. You can specify the number of decimal places.

  Format: {0:E}

  1052.0329112756 -> 1.052033E+003

  Format: {0:E2}

  -1052.0329112756 -> -1.05e+003

  F or f

  Displays numeric values in fixed format. You can specify the number of decimal places.

  Format: {0:F}

  1234.567 -> 1234.57

  Format: {0:F3}

  1234.567 -> 1234.567

  G or g

  Displays numeric values in general format (the most compact of either fixed-point or scientific notation). You can specify the number of significant digits.

  Format: {0:G}

  -123.456 -> -123.456

  Format: {0:G2}

  -123.456 -> -120

  N or n

  Displays numeric values in number format (including group separators and optional negative sign). You can specify the number of decimal places.

  Format: {0:N}

  1234.567 -> 1,234.57

  Format: {0:N4}

  1234.567 -> 1,234.5670

  P or p

  Displays numeric values in percent format. You can specify the number of decimal places.

  Format: {0:P}

  1 -> 100.00%

  Format: {0:P1}

  .5 -> 50.0%

  R or r

  Displays , , or BigInteger values in round-trip format.

  Format: {0:R}

  123456789.12345678 -> 123456789.12345678

  X or x

  Displays integer values in hexadecimal format. You can specify the number of digits.

  Format: {0:X}

  255 -> FF

  Format: {0:x4}

  255 -> 00ff

  For more information and for examples that show formatting for other culture values, see Standard Numeric Format Strings. You can also create custom numeric format strings. For more information, see Custom Numeric Format Strings.

  The following table lists format characters for fields. Most of these formatting specifications result in a different output depending on culture settings. The examples are for a value of 6/15/2009 1:45:30 PM with a culture setting of en-US.

  Format character

  Description

  Example

  d

  Short date pattern.

  Format: {0:d}

  6/15/2009 1:45:30 PM -> 6/15/2009

  D

  Long date pattern.

  Format: {0:D}

  6/15/2009 1:45:30 PM ->Monday, June 15, 2009

  f

  Full date/time pattern (short time).

  Format: {0:f}

  6/15/2009 1:45:30 PM -> Monday, June 15, 2009 1:45 PM

  F

  Full date/time pattern (long time).

  Format: {0:F}

  6/15/2009 1:45:30 PM -> Monday, June 15, 2009 1:45:30 PM

  g

  General date/time pattern (short time).

  Format: {0:g}

  6/15/2009 1:45:30 PM -> 6/15/2009 1:45 PM

  G

  General date/time pattern (long time).

  Format: {0:G}

  6/15/2009 1:45:30 PM -> 6/15/2009 1:45:30 PM

  M or m

  Month/day pattern.

  Format: {0:M}

  6/15/2009 1:45:30 PM -> June 15

  O or o

  Round-trip date/time pattern.

  Format: {0:o}

  6/15/2009 1:45:30 PM -> 2009-06-15T13:45:30.0900000

  R or r

  RFC1123 pattern (for information, see ).

  Format: {0:R}

  6/15/2009 1:45:30 PM -> Mon, 15 Jun 2009 20:45:30 GMT

  s

  Sortable date/time pattern.

  Format: {0:s}

  6/15/2009 1:45:30 PM -> 2009-06-15T13:45:30

  t

  Short time pattern.

  Format: {0:t}

  6/15/2009 1:45:30 PM -> 1:45 PM

  T

  Long time pattern.

  Format: {0:T}

  6/15/2009 1:45:30 PM -> 1:45:30 PM

  u

  Universal sortable date/time pattern.

  Format: {0:u}

  6/15/2009 1:45:30 PM -> 2009-06-15 20:45:30Z

  U

  Universal full date/time pattern.

  Format: {0:U}

  6/15/2009 1:45:30 PM -> Monday, June 15, 2009 8:45:30 PM

  Y or y

  Year month pattern.

  Format: {0:Y}

  6/15/2009 1:45:30 PM -> June, 2009

  For more information and for examples that show formatting for other culture values, see Standard Date and Time Format Strings. You can also create custom date and time format strings. For more information, see Custom Date and Time Format Strings.

  Gets or sets the string that specifies the display format for the value of the field.

  2.0.0.0
- Method
  System.Void `` `` `` ``

  The method is provided as a convenient way to retrieve the values of the fields from the specified object in a object.

  This method is used primarily by control developers.

  This method does not have a return value. Instead, the field values are returned by reference through the object passed in for the parameter. After the method has been called, iterate through the object to access the field values.

  If the object contains read-only field values, you must pass in true for the parameter to include those values.

  Fills the specified object with the values from the specified object.

  A used to store the values of the specified cell. The that contains the values to retrieve. One of the values. true to include the values of read-only fields; otherwise, false. 2.0.0.0
- Method
  System.String `` `` To be added.

  The method is a helper method used to transform a field value to the format specified by the property. If a field value is null, the value of the property is returned.

  This method is used primarily by control developers.

  Formats the specified field value for a cell in the object.

  The field value converted to the format specified by .

  true to encode the value; otherwise, false. 2.0.0.0
- Method
  System.Object

  The method is a helper method used to determine what value to display for a field when rendering the object in a designer. If real data cannot be retrieved from the data source at design time, the value returned by this method is displayed instead.

  This method is used primarily by control developers.

  Retrieves the value used for a field's value when rendering the object in a designer.

  The value to display in the designer as the field's value.

  2.0.0.0
- Method
  System.Object ``

  The method is a helper method used to determine the value of a field. If the object is being displayed in a designer and the field value cannot be determined at design time, the value returned from the method is returned instead of the actual field value.

  This method is used primarily by control developers.

  Retrieves the value of the field bound to the object.

  The value of the field bound to the .

  The container for the field value. 2.0.0.0
- Property
  System.String To be added.

  Use the property to identify a field in a data control with a friendly name. The most common application of the property is to provide meaningful column names to data-bound fields in a or control.

  Gets or sets the text that is displayed in the header of a data control.

  2.0.0.0
- Property
  System.ComponentModel.DefaultValue(true)
  System.Boolean To be added.

  Use the property to specify whether field values are HTML-encoded to their respective string representations before they are displayed in a object. For example, if this property is true, a string value of "<script>" would be rendered as "&lt;script&gt;". If this property is false, the string would be rendered unchanged.

  HTML-encoding field values helps to prevent cross-site scripting attacks and malicious content from being displayed. This property should be enabled whenever possible.

  Gets or sets a value indicating whether field values are HTML-encoded before they are displayed in a object.

  2.0.0.0
- Method
  System.Boolean `` ``

  The method is called by the data control with which the object is associated to perform basic object initialization for instances of the field, before the field is ever added to a rows collection. Data controls such as and call the method in their CreateChildControls methods before other methods such as CreateRow are called to create specific rows with data.

  Call this method when you are writing a custom data-bound control that uses objects to perform basic initialization for a object. Implement this method if your -derived type requires any object initialization before it populates objects with data or controls in the method.

  Initializes the object.

  false in all cases.

  true if sorting is supported; otherwise, false. The data control that owns the . 2.0.0.0
- Method
  System.Void `` `` `` ``

  The method is implemented by -derived types to add text and controls to a object of a data control that uses tables to display a user interface (UI). These data controls create the complete table structure row-by-row when the control's CreateChildControls method is called. The method is called by the InitializeRow method of data controls such as and .

  Call this method when you are writing a custom data-bound control that uses objects to initialize the cells of the table structure with data or controls. Implement this method when you are writing a -derived class.

  Initializes the specified object to the specified row state.

  The to initialize. One of the values. One of the values. The zero-based index of the row. 2.0.0.0
- Method
  System.Void `` ``

  The method is a helper method used to initialize a cell in the object.

  Initializes the specified object to the specified row state.

  The to initialize. One of the values. 2.0.0.0
- Property
  System.ComponentModel.DefaultValue("")
  System.String To be added.

  Sometimes a field's value is stored as null in the data source. You can specify a custom caption to display for fields that have a null value by setting the property. If this property is not set, null field values are displayed as empty strings (""). When a record is being updated or inserted in a data-bound control, if the user enters the value specified by this property (other than an empty string) for a field in a data-bound control, that value is automatically converted to null in the data source.

  To convert an empty string field value to a null value, set the property to true.

  Gets or sets the caption displayed for a field when the field's value is null.

  2.0.0.0
- Method
  System.Void `` ``

  The method is a helper method used to bind the value of a field in the data source to a corresponding cell in the object.

  Binds the value of a field to the object.

  The source of the event. An that contains the event data. 2.0.0.0
- Property
  System.ComponentModel.DefaultValue(false)
  System.Boolean To be added.

  Use the property to prevent the values displayed in a object from being modified. When a data-bound control is in edit mode, fields that are read-only are displayed as plain text, without any editing controls.

  The property applies only to edit mode. To prevent fields from showing up in insert mode, use the property.

  Gets or sets a value indicating whether the value of the field can be modified in edit mode.

  2.0.0.0
- Property
  System.Boolean To be added.

  The property is a helper property used by the class and derived classes to determine whether HTML encoding is supported by the class.

  Gets a value indicating whether HTML encoding is supported by a object.

  2.0.0.0
- Field
  System.String

  This field is used to indicate that the object should bind against the data source itself, rather than a field of the data source. In this case, the object's ToString value will be displayed in the field.

  This field is used primarily by control developers.

  Represents the "this" expression.

  2.0.0.0
- Method
  System.Void

  The method is a helper method used to determine whether the controls contained in a object support callbacks. This method has been implemented as an empty method (a method that does not contain any code) to indicate that callbacks are supported.

  This method is used primarily by control developers.

  Determines whether the controls contained in a object support callbacks.

  2.0.0.0