Export (0) Print
Expand All

ControlBuilder Class

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

For a list of all members of this type, see ControlBuilder Members.

System.Object
   System.Web.UI.ControlBuilder
      Derived classes

[Visual Basic]
Public Class ControlBuilder
[C#]
public class ControlBuilder
[C++]
public __gc class ControlBuilder
[JScript]
public class ControlBuilder

Thread Safety

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

Remarks

By default, every control on a page is associated with a default ControlBuilder class. This class adds a child control to the Controls collection for every nested control that it encounters within the custom control tags. Additionally, it creates literal controls for the text located between nested control tags. You can override this default behavior by defining your own custom control builder class. This is done by applying a ControlBuilderAttribute to your control builder class as follows: [ControlBuilderAttribute(typeof(ControlBuilderType))]

Example

[Visual Basic, C#, C++] The following 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.

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

csc /t:library /out:myWebAppPath/bin/cs_mycontrolbuilder.dll myControlBuilder.cs

[Visual Basic] 

'File name myControlBuilder.vb.
 
Imports System
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Collections
Imports System.Drawing


Namespace CustomControls
    _
   
   Public Class MyCellVB
      Inherits Control
      Implements INamingContainer   
  ' Class Name: MyCellVB.
  ' 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
            _id = value
         End Set
      End Property 
      
      Public Property Text() As String
         Get
            Return _value
         End Get
         Set
            _value = value
         End Set
      End Property 
      
      
      Public Property BackColor() As Color
         Get
            Return _backColor
         End Get
         Set
            _backColor = value
         End Set
      End Property
   End Class 'MyCellVB
    _ 
   Public Class MyControlBuilderVB
      Inherits ControlBuilder

      <System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.Demand, Name:="FullTrust")> _
      Public Overrides Function GetChildControlType(tagName As String, attribs As IDictionary) As Type
         
         ' Allows TableRow without "runat=server" attribute to be added to the collection.
         If tagName.ToLower().EndsWith("mycellvb") Then
            Return GetType(MyCellVB)
         End If 
         Return Nothing
      End Function 'GetChildControlType
      
      ' Ignores literals between rows.
      <System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.Demand, Name:="FullTrust")> _
      Public Overrides Sub AppendLiteralString(s As String)
      End Sub 'AppendLiteralString

   End Class 'MyControlBuilderVB
   
 <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 String
         Get
            Return _rows
         End Get
         Set
            _rows = CInt(value)
         End Set
      End Property
      
     ' Columns property to be used as the attribute name in the Web page.
        
      Public Property Columns () As String
         Get
            Return _columns
         End Get
         Set
            _columns = CInt(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
            _title = value
         End Set
      End Property
       
      
      Protected Sub createNewRow(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(row As TableRow, rowNumber As Integer, 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 MyCellVB child object.
         
         If Not (_cellObjects(textbox.ID) Is Nothing) Then
            Dim cellLookup As MyCellVB
            cellLookup = CType(_cellObjects(textbox.ID), MyCellVB)
            
            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.
      <System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.Demand, Name:="FullTrust")> _  
      Protected Overrides Sub AddParsedSubObject(obj As Object)  
         
         If TypeOf obj Is MyCellVB Then
            
            Dim cell As MyCellVB
            
            cell = CType(obj, MyCellVB)
            Context.Trace.Write("CellObject", cell.CellID)
            
            _cellObjects.Add(cell.CellID, cell)
            Return
         End If
      End Sub 'AddParsedSubObject
      
      
      <System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.Demand, Name:="FullTrust")> _
      Protected Overrides Sub OnPreRender(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 'CreateChildControls 
   End Class 'MyVB_CustomControl

End Namespace 'CustomControls


[C#] 

/* File name: myControlBuilder.cs. */

using System;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Collections;
using System.Drawing;

namespace CustomControls 
{
  public class MyTableCell : TableCell, INamingContainer {};
     
  public class MyCell  
  /*
   * Class name: MyCell.
   * Declares the class for the child controls to include in the control collection.
   */
  {
    string _id;
    string _value;
    Color _backColor;

    public string CellID 
    {
      get 
        {return _id;}
      set 
        {_id = value;}
    }

    public string Text 
    {
      get 
        {return _value;}
      set 
        {_value = value;}
    }

    public Color BackColor 
    {
      get 
        {return _backColor;}
      set 
        { _backColor = value;}
    }
  };

  public class MyControlBuilder   : ControlBuilder 
  {

    [System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name="FullTrust")]
    public override Type GetChildControlType(string tagName, IDictionary attribs) 
    {
      // Allows TableRow without "runat=server" attribute to be added to the collection.
      if (tagName.ToLower().EndsWith("mycell"))
        return typeof(MyCell);
      return null;
    }

    [System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name="FullTrust")]
    public override void AppendLiteralString(string s) 
    {
      // Ignores literals between rows.
    }

  }

  [ControlBuilderAttribute(typeof(MyControlBuilder))]
  public class MyCS_CustomControl: Control,  INamingContainer
  /*
   * Class name: MyCS_CustomControl.
   * Processes the element declarations within a control declaration. 
   * This builds the actual control.
  */
  {
    // Declares the custom control that must be built programmatically.
    Table _table;

    private String _title;
    private int _rows;
    private int _columns;

    Hashtable _cellObjects = new Hashtable();

   // Rows property to be used as the attribute name in the Web page.  
   public int Rows
   {
     get 
       {return _rows;}
     set 
       {_rows = value;}
   }

   // Columns property to be used as the attribute name in the Web page.
  public int Columns
  {
    get 
      {return _columns;}
    set 
      {_columns = value;}
  }
 
   // Title property to be used as the attribute name in the Web page.
   public string Title
   {
     get 
       {return _title;}
     set 
       {_title = value;}
   } 

   protected void createNewRow( int rowNumber ) 
   {

     // Creates a row and adds it to the table.
     TableRow row;

     row = new TableRow();
     _table.Rows.Add( row );

     // Creates a cell that contains text.

     for( int y=0; y < Columns ; y++ ) 
       appendCell( row, rowNumber, y );

    }

    protected void appendCell( TableRow row, int rowNumber, int cellNumber ) 
    {
      TableCell cell; 
      TextBox 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 ( _cellObjects[textbox.ID] != null ) 
      {
        MyCell cellLookup;
        cellLookup = (MyCell) _cellObjects[textbox.ID];

        textbox.Text = cellLookup.Text;
        textbox.BackColor = cellLookup.BackColor;
      }
      else     
        textbox.Text = "Row: " + rowNumber.ToString()  + " Cell: " +   
        cellNumber.ToString();

        row.Cells.Add( cell );
           
   }

   // Called at runtime when a child object is added to the collection.  
   [System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name="FullTrust")]
   protected override void AddParsedSubObject(object obj) 
   {
     MyCell cell = obj as MyCell;
     if (cell != null) 
     {
        _cellObjects.Add( cell.CellID, cell );
     }

   }

    [System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name="FullTrust")]
    protected override void OnPreRender(EventArgs e)
    /*
     * Function 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 );
      }

      // Checks that each row has the correct number of columns.
      for (int i=0; i<_table.Rows.Count; i++)
      {
        while(_table.Rows[i].Cells.Count<Columns)
        {
          appendCell(_table.Rows[i], i, _table.Rows[i].Cells.Count);
        }

        while(_table.Rows[i].Cells.Count>Columns)
        {
          _table.Rows[i].Cells.RemoveAt(_table.Rows[i].Cells.Count - 1);
        }
       }
    }

    [System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name="FullTrust")]
    protected override void CreateChildControls()
   /*
    * Function name: CreateChildControls.
    * Adds the Table and the text control to the control collection.
    */
    {
      LiteralControl text;

      // Initializes the text control using the Title property.
      text = new LiteralControl("<h5>" + Title + "</h5>");
      Controls.Add(text);

      _table = new Table();
      _table.BorderWidth = 2;
      Controls.Add(_table);
    }
  }
}


[C++] 

/* File name: myControlBuilder.cpp. */

#using <mscorlib.dll>
#using <System.Web.dll>
#using <System.dll>
#using <System.Drawing.dll>
using namespace System;
using namespace System::Web;
using namespace System::Web::UI;
using namespace System::Web::UI::WebControls;
using namespace System::Collections;
using namespace System::Drawing;

public __gc class MyTableCell : public TableCell, public INamingContainer
{
};

public __gc class MyCell
{
   /*
   * Class name: MyCell.
   * Declares the class for the child controls to include in the control collection.
   */
   String* _id;
   String* _value;
   Color _backColor;

public:
   __property String* get_CellID() 
   {
      return _id;
   }

   __property void set_CellID(String* value) 
   {
      _id = value;
   }

   __property String* get_Text() 
   {
      return _value;
   }

   __property void set_Text(String* value) 
   {
      _value = value;
   }

   __property Color get_BackColor() 
   {
      return _backColor;
   }

   __property void set_BackColor(Color value) 
   {
      _backColor = value;
   }
};

public __gc class MyControlBuilder : public ControlBuilder 
{
public:

   [System::Security::Permissions::PermissionSet(System::Security::Permissions::SecurityAction::Demand, Name="FullTrust")]
   Type * GetChildControlType(String* tagName, IDictionary* attribs) 
   {
      // Allows TableRow without "runat=server" attribute to be added to the collection.
      if (tagName->ToLower()->EndsWith(S"mycell"))
         return __typeof(MyCell);
      return 0;
   }

   [System::Security::Permissions::PermissionSet(System::Security::Permissions::SecurityAction::Demand, Name="FullTrust")]
   void AppendLiteralString(String* s) 
   {
      // Ignores literals between rows.
   }
};

[ControlBuilderAttribute(__typeof(MyControlBuilder))]
  public __gc class MyCS_CustomControl: public Control,  public INamingContainer
  {
     /*
     * Class name: MyCS_CustomControl.
     * Processes the element declarations within a control declaration.
     * This builds the actual control.
     */
     // Declares the custom control that must be built programmatically.
     Table* _table;

  private:
     String*  _title;
     int  _rows;
     int  _columns;

     Hashtable* _cellObjects;

     // Rows property to be used as the attribute name in the Web page.
  public:

     MyCS_CustomControl()
     {
        _cellObjects = new Hashtable();
     }

     __property int get_Rows() 
     {
        return _rows;
     }

     __property void set_Rows(int value) 
     {
        _rows = value;
     }

     // Columns property to be used as the attribute name in the Web page.
     __property int get_Columns() 
     {
        return _columns;
     }

     __property void set_Columns(int value) 
     {
        _columns = value;
     }

     // Title property to be used as the attribute name in the Web page.
     __property String* get_Title() 
     {
        return _title;
     }

     __property void set_Title(String* value) 
     {
        _title = value;
     }

  protected:
     void createNewRow(int rowNumber) 
     {
        // Creates a row and adds it to the table.
        TableRow * row;
        row = new TableRow();
        _table->Rows->Add(row);

        // Creates a cell that contains text.
        for (int y = 0; y < Columns ; y++)
           appendCell(row, rowNumber, y);
     }

     void appendCell(TableRow* row, int rowNumber, int cellNumber) 
     {
        TableCell * cell;
        TextBox * textbox;
        cell = new TableCell();
        textbox = new TextBox();
        cell->Controls->Add(textbox);
        textbox->ID = String::Concat(S"r", __box(rowNumber), S"c", __box(cellNumber));

        // Checks for the MyCell child object.
        if (_cellObjects->Item[textbox->ID] != 0) 
        {
           MyCell * cellLookup;
           cellLookup = dynamic_cast<MyCell*>(_cellObjects->Item[textbox->ID]);

           textbox->Text = cellLookup->Text;
           textbox->BackColor = cellLookup->BackColor;
        } 
        else
           textbox->Text = String::Concat(S"Row: ", __box(rowNumber), S"Cell: ", __box(cellNumber));

        row->Cells->Add(cell);
     }

     // Called at runtime when a child object is added to the collection.
     [System::Security::Permissions::PermissionSet(System::Security::Permissions::SecurityAction::Demand, Name="FullTrust")]
     void AddParsedSubObject(Object* obj) 
     {
        MyCell * cell = dynamic_cast<MyCell*>(obj);
        if (cell != 0)
           _cellObjects->Add(cell->CellID, cell);
     }

     [System::Security::Permissions::PermissionSet(System::Security::Permissions::SecurityAction::Demand, Name="FullTrust")]
     void OnPreRender(EventArgs* e)
     {
        /*
        * Function 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);

        // Checks that each row has the correct number of columns.
        for (int i=0; i<_table->Rows->Count; i++) 
           while(_table->Rows->Item[i]->Cells->Count<Columns)
              appendCell(_table->Rows->Item[i], i, _table->Rows->Item[i]->Cells->Count);

        while(_table->Rows->Item[i]->Cells->Count>Columns)
           _table->Rows->Item[i]->Cells->RemoveAt(_table->Rows->Item[i]->Cells->Count - 1);
     }

     [System::Security::Permissions::PermissionSet(System::Security::Permissions::SecurityAction::Demand, Name="FullTrust")]
     void CreateChildControls()
     {
        /*
        * Function name: CreateChildControls.
        * Adds the Table and the text control to the control collection.
        */
        LiteralControl * text;

        // Initializes the text control using the Title property.
        text = new LiteralControl(String::Concat(S"<h5>",Title,S"</h5>"));
        Controls->Add(text);
        _table = new Table();
        _table->BorderWidth = 2;
        Controls->Add(_table);
     }
  };

[Visual Basic, C#, C++] The following example uses the previous custom control. In particular, it builds a table whose attributes and content are defined at runtime. Notice that, the values shown in the Register directive reflect the previous command line.

[Visual Basic] 
<%@ Register TagPrefix="custom" Assembly="vb_mycontrolbuilder" Namespace="CustomControls" %>
<html>
<body>
 <h4>Using the ControlBuilder Class</h4>
 <form runat="server">
 <custom:MyVB_CustomControl Rows="2" Columns="2" Title="VB Custom Control Table" runat="server">
 <custom:MyCellVB CellID="r0c0" BackColor="magenta" Text="Hello"/>
 <custom:MyCellVB CellID="r0c1" BackColor="aqua" Text="Customer,"/>
 <custom:MyCellVB CellID="r1c0" BackColor="yellow" Text="How Are"/>
 <custom:MyCellVB CellID="r1c1" BackColor="red" Text="You?"/>
 </custom:MyVB_CustomControl>
 </form>
</body>
</html>
[C#] 
<%@ Register TagPrefix="custom" Assembly="cs_mycontrolbuilder" Namespace="CustomControls" %>
<html>
 <body>
 <h4>Using the ControlBuilder Class</h4>
 <form runat="server">
 <custom:MyCS_CustomControl ID="csTableId" rows="2" columns="2" Title="C# Custom Control Table" runat=server>
 <custom:MyCell CellID="r0c0" BackColor="red" Text="Hello"/>
 <custom:MyCell CellID="r0c1" BackColor="yellow" Text="Customer,"/>
 <custom:MyCell CellID="r1c0" BackColor="aqua" Text="How Are"/>
 <custom:MyCell CellID="r1c1" BackColor="magenta" Text="You?"/>
 </custom:MyCS_CustomControl>
 </form>
 </body>
</html>

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Namespace: System.Web.UI

Platforms: Windows 2000, Windows XP Professional, Windows Server 2003 family

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

See Also

ControlBuilder Members | System.Web.UI Namespace | Control | Page | ControlBuilderAttribute

Show:
© 2014 Microsoft