WebPartDisplayMode Class


The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Defines a common set of properties for the several display modes that a Web Parts page can enter.

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


public abstract class WebPartDisplayMode


Initializes a value for the name of the display mode.


Gets a value that determines whether users can change the layout of a Web Parts page when the page is in a certain display mode.


Gets a value that indicates whether a certain display mode is associated with a class that derives from the ToolZone class.


Gets the name of a display mode.


Gets a value that indicates whether a particular display mode requires personalization to be enabled.


Gets a value that indicates whether controls that have their Hidden property set to true should be displayed.


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


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


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


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


Gets a value that indicates whether users can personalize a page while the page is in a certain display mode.


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


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

A Web Parts page can enter several different display modes. In each display mode, certain elements of the Web Parts user interface (UI) are either hidden or displayed, and certain kinds of user modifications to a page are either enabled or disabled. The WebPartManager control contains the implementation for the display modes that are available in the Web Parts control set, and manages the display modes for a page.

The following table lists fields that represent the available display modes.

Display mode



Displays Web Parts controls and UI elements in the normal mode in which end users view a page.


Displays zone UI elements and enables users to drag Web Parts controls to change the layout of a page.


Displays special editing UI elements and enables end users to edit the controls on a page.


Displays special catalog UI elements and enables end users to add and remove page controls.


Displays special connections UI elements and enables end users to connect Web Parts controls.

Notes to Inheritors:

Developers can derive from the WebPartDisplayMode class to create custom display modes. To make a custom WebPartDisplayMode available on a Web Parts page, you would also need to derive from the WebPartManager class, and override its CreateDisplayModes method.

The following code examples demonstrate the declarative use of display modes on a Web Parts page. Each of these display modes, as implemented by the Web Parts control set, is derived from the WebPartDisplayMode class.

This code example has four parts:

  • A custom WebPart control.

  • A Web page with a zone to host the custom control.

  • A user control that enables users to change display modes on the Web page.

  • An explanation of how the page works in a browser.

The first part of the example is a custom WebPart control, TextDisplayWebPart. For the code example to run, you must compile this source code. You can compile it explicitly and put the resulting assembly in your Web site's Bin folder or the global assembly cache. Alternatively, you can put the source code in your site's App_Code folder, where it will be dynamically compiled at run time. For a demonstration of both methods of compiling, see Walkthrough: Developing and Using a Custom Web Server Control.

using System;
using System.Security.Permissions;
using System.Web;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;

namespace Samples.AspNet.CS.Controls
  public class TextDisplayWebPart : WebPart
    private String _contentText = null;
    TextBox input;
    Label DisplayContent;
    const string _subTitle = "Contoso, Ltd";

    public TextDisplayWebPart()
      this.AllowClose = false;

      Personalizable(PersonalizationScope.User, true),
    public String ContentText
      get { return _contentText; }
      set { _contentText = value; }

    protected override void CreateChildControls()
      DisplayContent = new Label();
      DisplayContent.BackColor = 
      DisplayContent.Text = this.ContentText;
      input = new TextBox();
      Button update = new Button();
      update.Text = "Set Label Content";
      update.Click += new EventHandler(this.submit_Click);
      ChildControlsCreated = true;

    private void submit_Click(object sender, EventArgs e)
      // Update the label string.
      if (input.Text != String.Empty)
        this.ContentText = Page.Server.HtmlEncode(input.Text) + @"<br />";
        // Clear the input textbox.
        input.Text = String.Empty;
        DisplayContent.Text = this.ContentText;

The second part of the code example is a Web page that references a standard ASP.NET Calendar control within an <asp:webpartzone> element, so that the control is wrapped with a GenericWebPart control and given basic Web Parts functionality at run time. The page also references the TextDisplayWebPart control within an <asp:catalogzone> element, which demonstrates the end user's ability to switch to catalog mode and add controls to the page. The page also includes an <asp:editorzone> element, which enables users to edit the controls contained in the <asp:webpartzone> when the page is in edit mode. Near the top of the page are a register directive for the custom control and another one for the user control.

<%@ page language="C#" %>
<%@ register TagPrefix="uc1" 
  Src="DisplayModeMenuCS.ascx" %>
<%@ register tagprefix="aspSample" 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<script runat="server">
void Button1_Click(object sender, EventArgs e)
  WebPartManager1.DisplayMode = WebPartManager.CatalogDisplayMode;
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
  <title>Web Parts Display Modes</title>
  <form id="Form2" runat="server">
    <asp:webpartmanager id="WebPartManager1" runat="server" />
    <uc1:DisplayModeMenuCS ID="DisplayModeMenu1" runat="server" />
      runat="server" BackImageUrl="~/MyImage.gif">
            Title="My Calendar" />
    <asp:WebPartZone ID="WebPartZone2" Runat="server">
    <asp:EditorZone ID="editzone1" Runat="server">
          Runat="server" />
          Runat="server" />
    <asp:CatalogZone ID="catalogzone1" Runat="server">
            title = "Text Content WebPart" AllowClose="true"/>  
    <br />
      text="Catalog Mode"

The third part of the code example is a user control that enables users to switch display modes on a Web page. Save the source code for this control in a file named DisplayModeMenuCS.ascx or DisplayModeMenuVB.ascx (depending on which language you use for the code example), and put it in the same directory as the Web page. For more details about display modes and a description of the source code in this control, see the topic Walkthrough: Changing Display Modes on a Web Parts Page.

<%@ control language="C#" classname="DisplayModeMenuCS"%>
<script runat="server">

 // Use a field to reference the current WebPartManager.
  WebPartManager _manager;

  void Page_Init(object sender, EventArgs e)
    Page.InitComplete += new EventHandler(InitComplete);

  void InitComplete(object sender, System.EventArgs e)
    _manager = WebPartManager.GetCurrentWebPartManager(Page);

    String browseModeName = WebPartManager.BrowseDisplayMode.Name;

    // Fill the dropdown with the names of supported display modes.
    foreach (WebPartDisplayMode mode in _manager.SupportedDisplayModes)
      String modeName = mode.Name;
      // Make sure a mode is enabled before adding it.
      if (mode.IsEnabled(_manager))
        ListItem item = new ListItem(modeName, modeName);

    // If shared scope is allowed for this user, display the scope-switching
    // UI and select the appropriate radio button for the current user scope.
    if (_manager.Personalization.CanEnterSharedScope)
      Panel2.Visible = true;
      if (_manager.Personalization.Scope == PersonalizationScope.User)
        RadioButton1.Checked = true;
        RadioButton2.Checked = true;


  // Change the page to the selected display mode.
  void DisplayModeDropdown_SelectedIndexChanged(object sender, EventArgs e)
    String selectedMode = DisplayModeDropdown.SelectedValue;

    WebPartDisplayMode mode = _manager.SupportedDisplayModes[selectedMode];
    if (mode != null)
      _manager.DisplayMode = mode;

  // Set the selected item equal to the current display mode.
  void Page_PreRender(object sender, EventArgs e)
    ListItemCollection items = DisplayModeDropdown.Items;
    int selectedIndex = 
    DisplayModeDropdown.SelectedIndex = selectedIndex;

  // Reset all of a user's personalization data for the page.
  protected void LinkButton1_Click(object sender, EventArgs e)

  // If not in User personalization scope, toggle into it.
  protected void RadioButton1_CheckedChanged(object sender, EventArgs e)
    if (_manager.Personalization.Scope == PersonalizationScope.Shared)

  // If not in Shared scope, and if user is allowed, toggle the scope.
  protected void RadioButton2_CheckedChanged(object sender, EventArgs e)
    if (_manager.Personalization.CanEnterSharedScope && 
        _manager.Personalization.Scope == PersonalizationScope.User)
  <asp:Panel ID="Panel1" runat="server" 
    Font-Names="Verdana, Arial, Sans Serif" >
    <asp:Label ID="Label1" runat="server" 
      Text="&nbsp;Display Mode" 
    <asp:DropDownList ID="DisplayModeDropdown" runat="server"  
      OnSelectedIndexChanged="DisplayModeDropdown_SelectedIndexChanged" />
    <asp:LinkButton ID="LinkButton1" runat="server"
      Text="Reset User State" 
      ToolTip="Reset the current user's personalization data for the page."
      OnClick="LinkButton1_Click" />
    <asp:Panel ID="Panel2" runat="server" 
      GroupingText="Personalization Scope"
      Visible="false" >
      <asp:RadioButton ID="RadioButton1" runat="server" 
        GroupName="Scope" OnCheckedChanged="RadioButton1_CheckedChanged" />
      <asp:RadioButton ID="RadioButton2" runat="server" 
        OnCheckedChanged="RadioButton2_CheckedChanged" />

When you load the page in a browser, you can use the Display Mode drop-down list control to switch to different display modes. To edit controls, select Edit in the drop-down list control. To edit a specific control, expose its verbs menu by clicking the arrow in the control's title bar, and then clicking Edit in the verbs menu. When a control is in edit mode, the editing controls added to this page enable you to change the edited control's appearance and layout. When you are finished, select Browse in the Display Mode drop-down list control to return the page to a normal view. To add controls to the page, switch to catalog mode. Notice that you can either use the Display Mode drop-down list control, or click the button near the bottom of the page. The inline code for the Button1_Click method demonstrates how to change display modes programmatically. While you are in catalog mode, you can add the custom TextDisplayWebPart control to the page.

.NET Framework
Available since 2.0

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