System.Design 1.0.5000.0 2.0.0.0 System.Web.UI.Design.HtmlControlDesigner

The class provides a base control designer class that can be inherited from and extended to provide design-time support for a Web server control in a design host, such as vsprvslong.

The object model for working with design-time rendering is improved over earlier versions, with the following new base classes to provide access to the simplified object model:

, which is not new, but has been greatly improved.

.

.

## Automatic Formatting

You can create a variety of automatic and pre-defined formats that can simplify the process of page developers who are applying complex style changes to custom Web server controls. For example, the control, which derives from the class, provides many automatic formats from which to choose. To implement and provide automatic formatting in your custom controls, use the following features:

The property.

The method.

The class.

The class.

## Action Lists (Smart Tags)

Action lists are menus of important or widely used tasks that a page developer who uses a control can perform in a design-time user interface (UI), such as vsprvslong. For example, the design-time view of your control could provide a menu of available tasks. This includes a task to format the control automatically. To learn about action lists, start with the following features:

The property.

The class.

The method.

The class.

The class.

The class.

## Control Designer Regions

Regions are editable areas in the design-time view of a Web server control. This feature offers WYSIWYG-like editing of the template content, inner controls, and properties at design time. You can have the control designer create controls in regions or you can use the Toolbox to drag and drop controls into regions. Regions are managed with the following features:

The method.

The class.

The class.

The method.

The method.

## Templates

The model for creating a UI for design-time editing of templated controls, such as the control, has been greatly improved from earlier versions. You can create complex custom controls that include templates for various parts of the control, and your custom control designer can help page developers who are modifying templates with the following features:

The property.

The property.

The class.

## Design-Time Rendering

The class has the following methods to support design-time rendering of the Web server control. Most of these methods are the same as in earlier versions:

The method.

The method.

The method.

The method.

The method.

Provides a base control designer class for extending the design-mode behavior of a Web server control.

- Constructor
  To be added.

  Initializes a new instance of the class.

  1.0.5000.0
  2.0.0.0
- Property
  2.0.0.0
  System.ComponentModel.Design.DesignerActionListCollection To be added. To be added.

  Gets the action list collection for the control designer.

- Property
  System.Boolean To be added. To be added.

  Gets a value indicating whether the control can be resized in the design-time environment.

  1.0.5000.0
  2.0.0.0
- Property
  2.0.0.0
  System.Web.UI.Design.DesignerAutoFormatCollection To be added.

  A complete Web server control includes not only the control, but also, possibly, a corresponding control designer class that is derived from the class and a formatting class that is derived from the class. The property is a collection of instances of the class. For a working example of automatic formatting in vsprvslong, see .

  Gets the collection of predefined automatic formatting schemes to display in the Auto Format dialog box for the associated control at design time.

- Method
  2.0.0.0
  System.String ``

  Use the method to create HTML markup to display an error message for a control at design time. The value for specifies a localized string that is displayed to the user of the control at design time.

  The class implementation of the method returns a table with two rows, as follows:

  The first row contains the type name and site name for the property of the object.

  The second row contains the input error message string.

  To generate HTML markup for an error message with an associated exception, use the overload. To generate HTML markup for an exception without specifying a localized error message, use the method.

  Creates HTML markup to display a specified error message at design time.

  An HTML markup string that contains the specified error message.

  The error message to include in the generated HTML markup.
- Method
  2.0.0.0
  System.String `` ``

  Use the method to provide simple HTML markup that can be used to display error and exception details for a control at design time. The value for specifies a localized string that is displayed to the user of the control at design time.

  The class implementation of the method returns a table with two rows, as follows:

  The first row contains the type name and site name for the property of the object.

  The second row contains the input error message and the string of the exception.

  To generate HTML markup for an error message without specifying an exception, use the overload. To generate HTML markup for an exception without specifying a localized error message, use the method.

  Creates the HTML markup to display a specified exception error message at design time.

  HTML markup that contains the specified and .

  The error message to include in the generated HTML string. The exception to include in the generated HTML string.
- Method
  System.String To be added.

  Provides a simple rectangular placeholder representation that displays the type and ID of the control.

  A string that contains design-time HTML markup providing basic information about the control.

  1.0.5000.0
  2.0.0.0
- Method
  System.String `` To be added.

  Provides a simple rectangular placeholder representation that displays the type and ID of the control, and also additional specified instructions or information.

  A string that contains design-time HTML markup providing information about the control.

  A string that contains text and markup to add to the HTML output. 1.0.5000.0 2.0.0.0
- Method
  2.0.0.0
  System.Web.UI.Control To be added.

  Returns a copy of the associated control for viewing or rendering on the design surface.

  A Web server control.

- Property
  2.0.0.0
  System.Boolean To be added. To be added.

  Gets a value indicating whether data binding is supported by the containing region for the associated control.

- Property
  2.0.0.0
  System.Web.UI.Design.ControlDesignerState To be added.

  The values for the property are persisted even if the user switches from Design to Source view, or reloads the document, or closes and reopens the design host.

  You can get and set values in the returned object as you would in an IDictionary object, with the values automatically persisted.

  Gets an object that is used to persist data for the associated control at design time.

- Property
  System.Object To be added.

  The property is obsolete and there is no replacement for the functionality.

  Gets the view-control object for the control designer.

  1.0.5000.0
  2.0.0.0
  System.Obsolete("It is documented as not in use anymore", true)
- Property
  System.Boolean To be added.

  The default implementation of the property returns false.

  The property is obsolete. Use the method for equivalent control designer functionality.

  Gets a value indicating whether the design host must finish loading before the method can be called.

  1.0.5000.0
  2.0.0.0
  System.Obsolete("Use SetViewFlags(ViewFlags.DesignTimeHtmlRequiresLoadComplete, true)")
- Method
  2.0.0.0
  System.Drawing.Rectangle To be added.

  Retrieves the coordinates of the rectangle representing the boundaries for the control as displayed on the design surface.

  A object representing the boundaries for the control on the design surface relative to the control, not the document.

- Method
  System.String To be added.

  Retrieves the HTML markup that is used to represent the control at design time.

  The HTML markup used to represent the control at design time.

  1.0.5000.0
  2.0.0.0
- Method
  2.0.0.0
  System.String ``

  The design host calls the method to get the design-time HTML markup and the current list of control designer regions. Using the DesignerRegionCollection, the design host can then request the markup for each editable control designer region.

  The method is provided for a derived control designer, such as the class, that must process the content for the region before calling the method.

  Retrieves the HTML markup to display the control and populates the collection with the current control designer regions.

  The design-time HTML markup for the associated control, including all control designer regions.

  A collection of control designer regions for the associated control.
- Method
  2.0.0.0
  System.Web.UI.Design.DesignTimeResourceProviderFactory ``

  A resource provider factory creates resource providers and resource writers, depending on the current settings in the system.web/globalization section of the configuration file (either the Machine.config or Web.config files for both global and local resources). If no globalization settings are found, the parameter is used to create a object using the default implementation for the design host.

  Typically, control developers will not override the method.

  Returns an appropriate resource provider factory, depending on the globalization settings in the configuration file for the site.

  A object, if any are defined in the configuration file; otherwise, null.

  An object that can retrieve global and local services.
- Method
  2.0.0.0
  System.String ``

  The default implementation of the method returns an empty string ("").

  Classes deriving from the class can support region-based editing on the design surface and override the method to return the content for a specified region.

  Returns the content for an editable region of the design-time view of the associated control.

  The persisted content for the region, if the control designer supports editable regions; otherwise, an empty string ("").

  The object to get content for.
- Method
  System.String

  The default behavior of the method is to return a string that contains the name of the component. The method should be called in the implementation of the method when there is no design-time HTML markup.

  Retrieves the HTML markup to represent a Web server control at design time that will have no visual representation at run time.

  The HTML markup used to represent a control at design time that would otherwise have no visual representation. The default is a rectangle that contains the type and ID of the component.

  1.0.5000.0
  2.0.0.0
- Method
  System.String ``

  The method is typically called, if an exception is thrown in the method.

  Retrieves the HTML markup that provides information about the specified exception.

  The design-time HTML markup for the specified exception.

  The exception that occurred. 1.0.5000.0 2.0.0.0
- Method
  2.0.0.0
  System.String To be added.

  Retrieves the persistable inner HTML markup of the control at design time.

  A string representing the persistable inner HTML markup for the associated control. The default is null.

- Method
  System.String

  The method is obsolete. Use the method for equivalent control designer functionality.

  Retrieves the persistable inner HTML markup of the control.

  The persistable inner HTML markup of the control.

  1.0.5000.0
  2.0.0.0
  System.Obsolete("Use GetPersistenceContent() instead")
- Method
  2.0.0.0
  System.Web.UI.Design.ViewRendering To be added.

  Retrieves an object that contains the design-time markup for the content and regions of the associated control.

  A object.

- Method
  2.0.0.0
  System.Web.UI.Design.ViewRendering `` To be added.

  Retrieves an object that contains the design-time markup for the content and regions of the specified control.

  A object.

  A object.
- Method
  2.0.0.0
  System.Web.UI.Design.ViewRendering `` To be added.

  Retrieves an object that contains the design-time markup for the content and regions of the associated control for the specified control designer.

  A object.

  A control designer that derives from .
- Property
  2.0.0.0
  System.Boolean To be added.

  The ID property is never hidden. The method uses the property to determine whether properties, other than the ID property, should be hidden from the property grids while the control is in template editing mode.

  Gets a value indicating whether the properties of the associated control are hidden when the control is in template mode.

- Property
  System.String To be added.

  The property is used internally within the control designer and for interaction with the Properties window. The property shadows the run-time property.

  Gets or sets the ID string for the control.

  1.0.5000.0
  2.0.0.0
- Method
  System.Void ``

  The method is called by the design host to complete the following actions:

  Load the control designer with the component to design.

  Set up the view on the control using the method.

  Verify that the associated control is of the right type.

  Initializes the control designer and loads the specified component.

  The control being designed. 1.0.5000.0 2.0.0.0
- Property
  2.0.0.0
  System.Boolean To be added.

  A Web server control is in template mode when a read-only template is currently being viewed or an editable template is being edited in a design host such as vsprvslong.

  The class supplies a default object to update the value when the template mode changes for the associated control. Custom designers that are derived from the class can override the method to perform additional processing when the template editing mode changes for a control in the design host.

  Gets a value indicating whether the control is in either template viewing or editing mode in the design host. The property is read-only.

- Method
  2.0.0.0
  System.Void

  To enable the control designer to handle paint events, use the method in the method.

  The method provides the design host with a way to instruct the control designer to redraw the control. Essentially, this is the same as calling method, because it causes the whole control to be redrawn.

  Invalidates the whole area of the control that is displayed on the design surface and signals the control designer to redraw the control.

- Method
  2.0.0.0
  System.Void ``

  To enable the control designer to handle paint events, use the method in the method.

  The method provides the design host with a way to instruct the control designer to redraw a specific part of the control.

  Invalidates the specified area of the control that is displayed on the design surface and signals the control designer to redraw the control.

  A object that represents the area to invalidate, relative to the upper-left corner of the control.
- Method
  2.0.0.0
  System.Void `` `` `` ``

  The implementation of the method notifies the design host, which is determined by the property of , that a change is occurring in the associated control and, if the change is not canceled by the design host, invokes the specified using the specified , and then notifies the design host that the change has completed.

  If the design host or the associated control throws a static Canceled exception field of a exception, the transaction is canceled without invoking .

  Wraps a series of changes into a transaction, using the specified parameters that can be rolled back as a unit with the undo functionality of the design host.

  The control associated with the control designer. A object representing a function to call in the control designer as part of the transaction. An object that contains the argument for callback. A description of the effect of allowing the transaction to complete, which is used by the design host to give the user an opportunity to cancel the transaction.
- Method
  2.0.0.0
  System.Void `` `` `` `` ``

  The implementation of the method notifies the design host, which is determined by the property of , that a change is occurring to the specified (property or method) of the associated control and, if the change is not canceled by the design host, invokes the specified using the specified as the argument, and then notifies the design host that the change has completed.

  If the design host or associated control throws a static Canceled exception field of a exception, the transaction is canceled without invoking .

  Wraps a series of changes into a transaction, using the specified parameters that can be rolled back as a unit with the undo functionality of the design host.

  The control associated with the control designer. A object representing a function to call in the control designer as part of the transaction. An object that contains the argument for callback. A description of the effect of allowing the transaction to complete, which is used by the design host to give the user an opportunity to cancel the transaction. A object (typically, either an or a object) that describes the member of the associated control that is being invoked as part of the transaction.
- Method
  2.0.0.0
  System.Void `` `` `` `` `` ``

  The implementation of the method notifies the design host, which is represented by , that a change is occurring to the specified (property or method) of the associated control and, if the change is not canceled by the design host, invokes the specified using the specified as the argument, and then notifies the design host that the change has completed.

  If the design host or the associated control throws a static Canceled exception field of a exception, the transaction is canceled without invoking .

  Wraps a series of changes into a transaction, using the specified parameters that can be rolled back as a unit with the undo functionality of the design host.

  An object representing the design host that provides control designer services for the associated control. The control associated with the control designer. A object representing a function to call in the control designer as part of the transaction. An object that contains the argument for callback. A description of the effect of allowing the transaction to complete, which is used by the design host to give the user an opportunity to cancel the transaction. A object (typically either an or a object) that describes the member of the associated control that is being invoked as part of the transaction.
- Property
  System.Boolean To be added.

  The property is obsolete. Use the property and the method on the property for equivalent control designer functionality.

  Gets or sets a value indicating whether the Web server control has been marked as changed.

  1.0.5000.0
  2.0.0.0
  System.Obsolete("Use Tag.SetDirty() and Tag.IsDirty instead.")
- Method
  System.Boolean ``

  The method is obsolete. Use the method on the property for equivalent control designer functionality.

  Retrieves a value indicating whether the specified property on the associated control is data-bound.

  true, if the property is data-bound; otherwise, false.

  The property to test for data binding. 1.0.5000.0 2.0.0.0 System.Obsolete("Use DataBindings.Contains(string) instead")
- Method
  2.0.0.0
  System.Void ``

  The method is called by the design host to create resource entries for each property that is marked with a object and any properties that use an explicit resource expression as a value.

  Uses the provided resource writer to persist the localizable properties of the associated control to a resource in the design host.

  An object derived from the object that is used to write resources into the design-time response stream.
- Method
  2.0.0.0
  System.Void ``

  The method is called after a object has applied a predefined format to the associated control. A object defines the automatic formatting scheme name and style settings that are applied to the control.

  Classes deriving from the class override the method to perform additional processing when an automatic formatting scheme is applied to the associated control.

  Called when a predefined, automatic formatting scheme has been applied to the associated control.

  A object that defines a style.
- Method
  System.Void

  The method is obsolete. Use the and methods on the property for equivalent control designer functionality.

  Called when the control designer is attached to a Behavior object.

  1.0.5000.0
- Method
  System.Void ``

  The method is called when the data-binding collection has been changed by an external caller.

  The method is obsolete. Use the event on the collection for equivalent control designer functionality.

  Called when the data-binding collection changes.

  The property to test for changes in its bindings collection. 1.0.5000.0 2.0.0.0 System.Obsolete("Use DataBindings.Changed event instead")
- Method
  2.0.0.0
  System.Void ``

  The event is raised by the design host for certain actions on a control in the design surface. For example, an event is raised for the following conditions:

  The user clicks the control.

  The control designer paints on the design surface.

  The user enters or exits template editing mode for the control.

  The class supplies a default delegate to handle the event. Classes deriving from override the method to process events that are raised when the user clicks a control.

  The method allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

  The default implementation of the method returns without performing any processing.

  Called by the design host when the user clicks the associated control at design time.

  A object that specifies the location and, possibly, the control designer region that the user clicked.
- Method
  System.Void `` ``

  The method is called when a property on the associated control is changed. It allows the implementer to do any processing that might be required after a property change. Calling the method causes the design host to call the method. The base implementation of the method also persists the control in the page markup.

  Called when the associated control changes.

  The source of the event. A object that contains the event data. 1.0.5000.0 2.0.0.0
- Method
  2.0.0.0
  System.Void `` ``

  When either the or method is called, the event occurs before any changes are made to the associated control. After the changes are complete, the method occurs.

  Represents the method that will handle the event for the associated control.

  The object that is the source of the event. A object that contains the event data.
- Method
  System.Void

  The method is obsolete. Use the method for equivalent control designer functionality.

  The method typically is called only by the design-time environment when a user action causes the associated Web server control to be resized. The method might be called several times during a resizing process to display the updated size of the control before the resizing is completed. The width and height properties of the control are updated before the method is called.

  Called when the associated Web server control has been resized in the design host at design time.

  1.0.5000.0
  2.0.0.0
  System.Obsolete("Use OnComponentChanged() instead")
- Method
  2.0.0.0
  System.Void ``

  The event is raised by the design host for certain actions on a control in the design surface. For example, an event is raised for the following conditions:

  The user clicks the control.

  The design host requests HTML markup to render the associated control on the design surface.

  The user enters or exits template editing mode for the control.

  The class supplies a default delegate to handle the event. Classes deriving from should set the value and override the method to process events that are raised when the design host draws the control on the design surface.

  The method allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

  The default implementation of the method returns without performing any processing.

  Called when the control designer draws the associated control on the design surface, if the value is true.

  A object that specifies the graphics and rectangle boundaries used to draw the control.
- Method
  System.Void ``

  With the method, you can add items to the dictionary of properties that a control designer exposes through a object.

  The keys in the dictionary of properties are the names of the properties. The objects are of type .

  Adds properties to or removes properties from the Properties grid in a design host at design time or provides new design-time properties that might correspond to properties on the associated control.

  The properties for the class of the component. 1.0.5000.0 2.0.0.0
- Method
  System.Void

  The method is obsolete and there is no replacement for this feature.

  Raises the event.

  1.0.5000.0
  2.0.0.0
  System.Obsolete("Use OnComponentChanged() instead")
- Property
  System.Boolean To be added.

  The class is read-only, by nature. Read/write features are provided by adding a object or using base classes, such as the class.

  The property is obsolete. Derive from the class to which you can add editable designer regions or from the object to which you can create editable designer regions in templates.

  Gets or sets a value indicating whether the properties of the control are read-only at design time.

  1.0.5000.0
  2.0.0.0
  System.Obsolete("Use ContainerControlDesigner and EditableDesignerRegion")
- Method
  2.0.0.0
  System.Void `` ``

  Whenever an item is cloned, there might be some internal data structures, such as meta: attributes, that should be included in the cloned control by the control designer. A page developer might add meta: attributes to the markup of a control and there is no way, nor is there a reason, for the control to distinguish what those tags might be. Therefore, if your control designer provides a way to edit complex properties or formats before applying changes to a page, you would create a clone of the control, pass both the original control and the clone to this method, and then, when the changes are persisted to the tag, all meta: attributes are also persisted.

  Registers internal data in a cloned control.

  The control associated with the control designer. The cloned copy of the associated control.
- Property
  2.0.0.0
  System.Web.UI.Design.WebFormsRootDesigner To be added.

  The property represents the control designer for the Web Forms page that contains the control. Use the property to access and manipulate the containing Web Forms page at design time.

  Gets the control designer for the Web Forms page that contains the associated control.

- Method
  2.0.0.0
  System.Void `` ``

  Classes deriving from the class can support region-based editing on the design surface and override the method to set the content for a specified region.

  Specifies the content for an editable region of the control at design time.

  An editable design region contained within the control. The content to assign for the editable design region.
- Method
  2.0.0.0
  System.Void `` ``

  Normally, the method is not overridden in derived designers. The base class causes the design host to call the method for the region. Override the method when custom data is required for the control before calling method.

  Use the method to insert HTML markup into a region of the control.

  Specifies the content for an editable region in the design-time view of the control.

  An editable design region contained within the design-time view of the control. The content to assign for the editable design region.
- Method
  2.0.0.0
  System.Void `` ``

  There are several flags that can be set. For example, use the method to set the value of the current property for the control designer, instead of the obsolete property.

  Assigns the specified bitwise enumeration to the specified flag value.

  A value. true to set the flag, false to remove the flag.
- Property
  2.0.0.0
  System.Web.UI.Design.IControlDesignerTag To be added.

  Typically, the property is used only for communication between the design host and the control designer and is not used by control developers.

  Gets an object representing the HTML markup element for the associated control.

- Property
  2.0.0.0
  System.Web.UI.Design.TemplateGroupCollection To be added. To be added.

  Gets a collection of template groups, each containing one or more template definitions.

- Method
  System.Void

  The method is called by the design host to update the display of the associated Web server control at design time, such as when the control has been modified. Also, a control designer can call the method after modifying values of the control to update the display of the control.

  If you are calling the event, or using the object to set properties, the interface calls the method for you.

  Refreshes the design-time HTML markup for the associated Web server control by calling the method.

  1.0.5000.0
  2.0.0.0
- Property
  2.0.0.0
  System.Boolean To be added.

  If the property is true, the property returns a temporary copy of the control. Changes to the temporary control are not persisted to the document.

  If the property is false, the property returns an instance of the property for the control. Changes to the instance of the control are persisted.

  The setting in the object is used to set the value of the property. Therefore, the setting determines the type of control that is returned by the property in the base class. If the is not specified in the control designer declaration, the object behavior is equivalent to specifying the property as false.

  Gets a value indicating whether the control designer uses a temporary preview control to generate the design-time HTML markup.

- Property
  2.0.0.0
  System.Web.UI.Control To be added.

  The property uses the property to determine its return value.

  If the property is true, the property returns a temporary copy of the control. Changes to the temporary control are not persisted.

  If the property is false, the property returns an instance of the property for the control. Changes to the instance of the control are persisted.

  The setting in the object is used to set the value of the property. Therefore, the setting determines the type of control that is returned by the property in the base class. If the is not specified in the control designer declaration, the object behavior is equivalent to specifying the property as false.

  Gets or sets a Web server control that can be used for previewing the design-time HTML markup.

- Property
  2.0.0.0
  System.Boolean To be added. To be added.

  Gets or sets a value indicating whether a View control has been created for display on the design surface.