CellFormatting Event

Occurs when the cell contents need to be formatted for display.

Syntax

Visual Basic (Declaration)
Visual Basic (Usage)
C#

<FeatureAttribute(Name="DataTranslation", Version="v5.0")>
<SRDescriptionAttribute("Occurs when the contents of a cell need to be formatted for display.")>
<SRCategoryAttribute("Display")>
Public Event CellFormatting As EventHandler(Of CellFormattingEventArgs)

Dim instance As GcMultiRow
Dim handler As EventHandler(Of CellFormattingEventArgs)
 
AddHandler instance.CellFormatting, handler

[Feature(Name="DataTranslation", Version="v5.0")]
[SRDescription("Occurs when the contents of a cell need to be formatted for display.")]
[SRCategory("Display")]
public event EventHandler<CellFormattingEventArgs> CellFormatting

Event Data

The event handler receives an argument of type CellFormattingEventArgs containing data related to this event. The following CellFormattingEventArgs properties provide information specific to this event.

Property	Description
CellIndex	Gets the cell index in its parent Section.
CellName	Gets the name of the cell.
CellStyle	Gets or sets the cell style that is being formatted.
DesiredType	(Inherited from System.Windows.Forms.ConvertEventArgs)
FormattingApplied	Gets or sets a value that indicates whether the cell value has been successfully formatted.
RowIndex	Gets the index of the owner Row that the event occurs for.
Scope	Gets the cell area that the event occurs for.
SectionIndex	Gets the index of the owner Section that the event occurs for.
Value	(Inherited from System.Windows.Forms.ConvertEventArgs)

Remarks

By default, the GcMultiRow control attempts to convert a cell's value into a format suitable for display. For example, it converts a numerical value into a string for display in a text box cell. You can indicate the formatting convention to use by setting the CellStyle.Format property of the CellStyle. The cell style can be returned with the DefaultCellStyle property.

If the standard formatting is insufficient, you can customize the formatting by handling the CellFormatting event. This event lets you indicate the exact display value as well as the cell styles, such as background and foreground color, to use for the cell display. This means you can handle this event for any kind of cell formatting, regardless of whether the cell value itself needs formatting.

The CellFormatting event occurs every time each cell is painted, so you should avoid lengthy processing when handling this event. This event also occurs when the cell FormattedValue is retrieved.

When you handle the CellFormatting event, the System.Windows.Forms.ConvertEventArgs.Value property is initialized with the cell value. If you provide custom conversion from the cell value to the display value, set the System.Windows.Forms.ConvertEventArgs.Value property to the converted value, which ensures that the new value is of the type specified by the cell FormattedValueType property. To indicate that no further value formatting is necessary, set the FormattingApplied property to true.

When the event handler completes, if the System.Windows.Forms.ConvertEventArgs.Value is a null reference (Nothing in Visual Basic) or is not of the correct type, or the FormattingApplied property is false, the value is formatted using the CellStyle.Format, NullValue, DataSourceNullValue, and FormatProvider properties of the cell style. The cell style is returned by the CellStyle property, which is initialized using the cell InheritedStyle property.

Regardless of the value of the FormattingApplied property, the display properties of the object returned by the CellStyle property are used to render the cell.

To customize the conversion of a formatted, user specified value into an actual cell value, handle the CellParsing event.

Example

The following code example shows how to use this event to customize the cell's appearance. This code example is part of a larger example provided for the CellStyle class.

void gcMultiRow1_CellFormatting(object sender, CellFormattingEventArgs e)
        {
            // Customize cell style in cell formating.
            if (e.Scope == CellScope.Row)
            {
                if (e.Value != null)
                {
                    int value;
                    if (int.TryParse(e.Value.ToString(), out value))
                    {
                        // When cell's value is more than 2 and less than 4, change forecolor to red.
                        if (value >= 2 && value <= 4)
                        {
                            e.CellStyle.ForeColor = Color.Red;
                        }
                    }
                }
            }
        }

VB.NET

Private Sub gcMultiRow1_CellFormatting(ByVal sender As Object, ByVal e As CellFormattingEventArgs) Handles 
gcMultiRow1.CellFormatting
        ' Customize cell style in cell formating.
        If e.Scope = CellScope.Row Then
            If e.Value <> Nothing Then
                Dim value As Integer
                If Integer.TryParse(e.Value.ToString(), value) Then
                    ' When cell's value is more than 2 and less than 4, change forecolor to red.
                    If value >= 2 AndAlso value <= 4 Then
                        e.CellStyle.ForeColor = Color.Red
                    End If
                End If
            End If
        End If
    End Sub

Requirements

Target Platforms: Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference

GcMultiRow Class
GcMultiRow Members