ControlBuilder Class

 

Supports the page parser in building a control and the child controls it contains.

Namespace:   System.Web.UI
Assembly:  System.Web (in System.Web.dll)


Public Class ControlBuilder

NameDescription
System_CAPS_pubmethodControlBuilder()

Initializes a new instance of the ControlBuilder class.

NameDescription
System_CAPS_pubpropertyBindingContainerBuilder

System_CAPS_pubpropertyBindingContainerType

Gets the type of the binding container for the control that this builder creates.

System_CAPS_pubpropertyComplexPropertyEntries

Gets a collection of complex property entries.

System_CAPS_pubpropertyControlType

Gets the Type for the control to be created.

System_CAPS_pubpropertyCurrentFilterResolutionService

Gets an IFilterResolutionService object that is used to manage device-filter related services when parsing and persisting controls in the designer.

System_CAPS_pubpropertyDeclareType

Gets the type that will be used by code generation to declare the control.

System_CAPS_protpropertyFChildrenAsProperties

Gets a value that determines whether the control has a ParseChildrenAttribute with ChildrenAsProperties set to true.

System_CAPS_protpropertyFIsNonParserAccessor

Gets a value that determines whether the control implements the IParserAccessor interface.

System_CAPS_pubpropertyHasAspCode

Gets a value indicating whether the control contains any code blocks.

System_CAPS_pubpropertyID

Gets or sets the identifier property for the control to be built.

System_CAPS_protpropertyInDesigner

Returns whether the ControlBuilder is running in the designer.

System_CAPS_protpropertyInPageTheme

Gets a Boolean value indicating whether this ControlBuilder object is used to generate page themes.

System_CAPS_pubpropertyItemType

Gets the type set on the binding container.

System_CAPS_pubpropertyLocalize

Gets a Boolean value indicating whether the control that is created by this ControlBuilder object is localized.

System_CAPS_pubpropertyNamingContainerType

This API supports the product infrastructure and is not intended to be used directly from your code. Gets the type of the naming container for the control that this builder creates.

System_CAPS_pubpropertyPageVirtualPath

Gets the virtual path of a page to be built by this ControlBuilder instance.

System_CAPS_protpropertyParser

This API supports the product infrastructure and is not intended to be used directly from your code. Gets the TemplateParser responsible for parsing the control.

System_CAPS_pubpropertyServiceProvider

Gets the service object for this ControlBuilder object.

System_CAPS_pubpropertySubBuilders

Gets a list of child ControlBuilder objects for this ControlBuilder object.

System_CAPS_pubpropertyTagName

Gets the tag name for the control to be built.

System_CAPS_pubpropertyTemplatePropertyEntries

Gets a collection of template property entries.

System_CAPS_pubpropertyThemeResolutionService

Gets an IThemeResolutionService object that is used in design time to manage control themes and skins.

NameDescription
System_CAPS_pubmethodAllowWhitespaceLiterals()

Determines whether white space literals are permitted in the content between a control's opening and closing tags. This method is called by the ASP.NET page framework.

System_CAPS_pubmethodAppendLiteralString(String)

Adds the specified literal content to a control. This method is called by the ASP.NET page framework.

System_CAPS_pubmethodAppendSubBuilder(ControlBuilder)

Adds builders to the ControlBuilder object for any child controls that belong to the container control.

System_CAPS_pubmethodBuildObject()

Builds a design-time instance of the control that is referred to by this ControlBuilder object.

System_CAPS_pubmethodCloseControl()

Called by the parser to inform the builder that the parsing of the control's opening and closing tags is complete.

System_CAPS_pubmethodSystem_CAPS_staticCreateBuilderFromType(TemplateParser, ControlBuilder, Type, String, String, IDictionary, Int32, String)

Creates a ControlBuilder object from the specified tag name and object type, as well as other parameters defining the builder.

System_CAPS_pubmethodEquals(Object)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodGetChildControlType(String, IDictionary)

Obtains the Type of the control type corresponding to a child tag. This method is called by the ASP.NET page framework.

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetObjectPersistData()

Creates the ObjectPersistData object for this ControlBuilder object.

System_CAPS_pubmethodGetResourceKey()

This API supports the product infrastructure and is not intended to be used directly from your code. Retrieves the resource key for this ControlBuilder object.

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodHasBody()

Determines if a control has both an opening and closing tag. This method is called by the ASP.NET page framework.

System_CAPS_pubmethodHtmlDecodeLiterals()

Determines whether the literal string of an HTML control must be HTML decoded. This method is called by the ASP.NET page framework.

System_CAPS_pubmethodInit(TemplateParser, ControlBuilder, Type, String, String, IDictionary)

Initializes the ControlBuilder for use after it is instantiated. This method is called by the ASP.NET page framework.

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_pubmethodNeedsTagInnerText()

Determines if the control builder needs to get its inner text. If so, the SetTagInnerText method must be called. This method is called by the ASP.NET page framework.

System_CAPS_pubmethodOnAppendToParentBuilder(ControlBuilder)

Notifies the ControlBuilder that it is being added to a parent control builder.

System_CAPS_pubmethodProcessGeneratedCode(CodeCompileUnit, CodeTypeDeclaration, CodeTypeDeclaration, CodeMemberMethod, CodeMemberMethod)

Enables custom control builders to access the generated Code Document Object Model (CodeDom) and insert and modify code during the process of parsing and building controls.

System_CAPS_pubmethodSetResourceKey(String)

This API supports the product infrastructure and is not intended to be used directly from your code. Sets the resource key for this ControlBuilder object.

System_CAPS_pubmethodSetServiceProvider(IServiceProvider)

This API supports the product infrastructure and is not intended to be used directly from your code. Sets the service object for this ControlBuilder object.

System_CAPS_pubmethodSetTagInnerText(String)

Provides the ControlBuilder with the inner text of the control tag.

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

NameDescription
System_CAPS_pubfieldSystem_CAPS_staticDesignerFilter

Represents the "__designer" literal string.

By default, every control on a page is associated with a default ControlBuilder class. During parsing, the ASP.NET page framework builds a tree of ControlBuilder objects corresponding to the tree of controls for the page. The ControlBuilder tree is then used to generate page code to create the control tree. In addition to child controls, the ControlBuilder defines the behavior of how the content within control tags is parsed. You can override this default behavior by defining your own custom control builder class. This is done by applying a ControlBuilderAttribute attribute to your control builder class as follows:

[ControlBuilderAttribute(typeof(ControlBuilderType))]

The following code example creates a Table control whose attributes and content are defined at the time the table is built. The following is the command line to use to build the executable.

[Visual Basic]

vbc /r:System.dll /r:System.Web.dll /r:System.Drawing.dll /t:library /out:myWebAppPath/Bin/vb_mycontrolbuilder.dll myControlBuilder.vb

[C#]

csc /t:library /out:myWebAppPath/Bin/cs_mycontrolbuilder.dll myControlBuilder.cs
Imports System
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Collections
Imports System.Drawing
Imports System.Security.Permissions


Namespace CustomControls

    <AspNetHostingPermission(SecurityAction.Demand, Level:=AspNetHostingPermissionLevel.Minimal)> _
    Public Class MyTableCell
        Inherits TableCell
        Implements INamingContainer
    End Class


    <AspNetHostingPermission(SecurityAction.Demand, Level:=AspNetHostingPermissionLevel.Minimal)> _
    Public Class MyCell
        Inherits Control
        Implements INamingContainer
        ' Class Name: MyCell.
        ' Declares the class for the child controls to be included in the control collection.

        Private _id As String
        Private _value As String
        Private _backColor As Color

        Public Property CellID() As String
            Get
                Return _id
            End Get
            Set(ByVal value As String)
                _id = value
            End Set
        End Property

        Public Property Text() As String
            Get
                Return _value
            End Get
            Set(ByVal value As String)
                _value = value
            End Set
        End Property


        Public Property BackColor() As Color
            Get
                Return _backColor
            End Get
            Set(ByVal value As Color)
                _backColor = value
            End Set
        End Property
    End Class

    <AspNetHostingPermission(SecurityAction.Demand, Level:=AspNetHostingPermissionLevel.Minimal)> _
    Public Class MyControlBuilderVB
        Inherits ControlBuilder

        Public Overrides Function GetChildControlType(ByVal tagName As String, ByVal attribs As IDictionary) As Type

            ' Allows TableRow without "runat=server" attribute to be added to the collection.
            If (String.Compare(tagName, "mycell", True) = 0) Then
                Return GetType(MyCell)
            End If
            Return Nothing
        End Function

        ' Ignores literals between rows.
        Public Overrides Sub AppendLiteralString(ByVal s As String)
            ' Ignores literals between rows.
        End Sub

    End Class

    <AspNetHostingPermission(SecurityAction.Demand, Level:=AspNetHostingPermissionLevel.Minimal), ControlBuilderAttribute(GetType(MyControlBuilderVB))> _
        Public Class MyVB_CustomControl
        Inherits Control
        Implements INamingContainer

        ' Class name: MyVB_CustomControl.
        ' Processes the element declarations within a control 
        ' declaration. This builds the actual control.

        ' Custom control to build programmatically.
        Private _table As Table

        Private _cellObjects As New Hashtable()

        ' Variables that must contain the control attributes as defined in the Web page.
        Private _rows As Integer
        Private _columns As Integer
        Private _title As String

        ' Rows property to be used as the attribute name in the Web page.     
        Public Property Rows() As Integer
            Get
                Return _rows
            End Get
            Set(ByVal value As Integer)
                _rows = value
            End Set
        End Property

        ' Columns property to be used as the attribute name in the Web page.

        Public Property Columns() As Integer
            Get
                Return _columns
            End Get
            Set(ByVal value As Integer)
                _columns = value
            End Set
        End Property

        ' Title property to be used as the attribute name in the Web page   
        Public Property Title() As String
            Get
                Return _title
            End Get
            Set(ByVal value As String)
                _title = value
            End Set
        End Property


        Protected Sub createNewRow(ByVal rowNumber As Integer)

            ' Creates a row and adds it to the table.
            Dim row As TableRow

            row = New TableRow()
            _table.Rows.Add(row)

            ' Creates a cell that contains text.
            Dim y As Integer
            For y = 0 To Columns - 1
                appendCell(row, rowNumber, y)
            Next y
        End Sub 'createNewRow


        Protected Sub appendCell(ByVal row As TableRow, ByVal rowNumber As Integer, ByVal cellNumber As Integer)
            Dim cell As TableCell
            Dim textbox As TextBox

            cell = New TableCell()

            textbox = New TextBox()

            cell.Controls.Add(textbox)

            textbox.ID = "r" + rowNumber.ToString() + "c" + cellNumber.ToString()

            ' Checks for the MyCell child object.
            If Not (_cellObjects(textbox.ID) Is Nothing) Then
                Dim cellLookup As MyCell
                cellLookup = CType(_cellObjects(textbox.ID), MyCell)

                textbox.Text = cellLookup.Text
                textbox.BackColor = cellLookup.BackColor

            Else
                textbox.Text = "Row: " + rowNumber.ToString() + " Cell: " + cellNumber.ToString()
            End If

            row.Cells.Add(cell)
        End Sub 'appendCell

        ' Called at runtime when a child object is added to the collection.
        Protected Overrides Sub AddParsedSubObject(ByVal obj As Object)

            Dim cell As MyCell = CType(obj, MyCell)
            If Not (cell Is Nothing) Then
                _cellObjects.Add(cell.CellID, cell)
            End If
        End Sub 'AddParsedSubObject


        Protected Overrides Sub OnPreRender(ByVal e As EventArgs)
            ' Sub name: OnPreRender.
            ' Carries out changes affecting the control state and renders the resulting UI.

            ' Increases the number of rows if needed.
            While _table.Rows.Count < Rows
                createNewRow(_table.Rows.Count)
            End While

            ' Checks that each row has the correct number of columns.
            Dim i As Integer
            For i = 0 To _table.Rows.Count - 1
                While _table.Rows(i).Cells.Count < Columns
                    appendCell(_table.Rows(i), i, _table.Rows(i).Cells.Count)
                End While

                While _table.Rows(i).Cells.Count > Columns
                    _table.Rows(i).Cells.RemoveAt((_table.Rows(i).Cells.Count - 1))
                End While
            Next i
        End Sub 'OnPreRender


        <System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.Demand, Name:="FullTrust")> _
        Protected Overrides Sub CreateChildControls()
            ' Sub name: CreateChildControls.
            ' Adds the Table and the text controls to the control collection. 


            Dim [text] As LiteralControl

            ' Initializes the text control using the Title property.
            [text] = New LiteralControl("<h5>" + Title + "</h5>")
            Controls.Add([text])


            _table = New Table()

            Controls.Add(_table)
        End Sub
    End Class

End Namespace

The following code example uses the previous custom control. In particular, it builds a table whose attributes and content are defined at run time. Notice that the values shown in the directive reflect the previous command line.

<%@ Page Language="VB" %>
<%@ Register TagPrefix="AspNetSamples" Assembly="vb_mycontrolbuilder" Namespace="CustomControls" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>ControlBuilder Example</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
       <AspNetSamples:MyVB_CustomControl id="Custom1" 
                                         title="Auto-Generated Table"
                                         columns="3"
                                         rows="3"  
                                         runat="server">
         <mycell cellid="r0c0" BackColor="red" text="red cell"></mycell>
         <mycell cellid="r2c2" BackColor="green" text="green cell"></mycell>
       </AspNetSamples:MyVB_CustomControl>
    </div>
    </form>
</body>
</html>

.NET Framework
Available since 1.1

Any public static ( Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show: