ContentControl ContentControl ContentControl Class

Represents a control with a single piece of content. Controls such as Button, CheckBox, and ScrollViewer directly or indirectly inherit from this class.

Syntax

Declaration

public class ContentControlpublic class ContentControlPublic Class ContentControl
<ContentControl .../>
-or-
<contentControl>
    singleObject
</contentControl>
-or-
<contentControl>stringContent</contentControl>

Inheritance Hierarchy

Inherited Members

Inherited properties

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited events

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited methods

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Remarks

The Content property of a ContentControl can be any type of object, such as a string, a UIElement, or a DateTime. By default, when the Content property is set to a UIElement, the UIElement is displayed in the ContentControl. When Content is set to another type of object, a string representation of the object is displayed in the ContentControl. A ContentControl has a limited default style. If you want to enhance the appearance of the control, you can create a new DataTemplate and set it to the ContentTemplate property of the control.

A ContentControl can use a string as the value for its Content property. However, whether a string is useful as content, and how it displays, is potentially handled differently by each control that derives from ContentControl. Specifically, the ability to display a content string is related to how a control uses a ContentPresenter in its compositing. This behavior can also change by applying a custom control template to an existing control. Examples of content controls where string content displays by default include Button and related button controls. Frame is an example of a ContentControl that does not display string content. If a ContentControl doesn't have a ContentPresenter within it that has a {TemplateBinding} markup extension for Content to Content, then the value of Content might not display anywhere.

Note that string content is specifically enabled only on ContentControl, not Control. For example, TextBox does not support string content like this: <TextBox>Initial text</TextBox>, because it is not derived from ContentControl.

Rather than using a literal string, a ContentControl might use a reference to a string that is defined in a resource dictionary, or a binding. Either of these techniques can simplify the task of localizing the parts of the UI that are defined in Extensible Application Markup Language (XAML), by gathering the necessary string resources in one location rather than scattered throughout various Extensible Application Markup Language (XAML) files. Because apps usually need a way to maintain strings as resources for localization reasons or for general versatility, it is more common to not use string content, and to instead set Content as an attribute, with a value that is a {Binding} or {StaticResource}.

Instead of text, a ContentControl might also display a single element for its own visual root, but using some container or panel so that there can be further UI compositing within. For example, if you really wanted to, you could declare a StackPanel for adaptive layout within a Button as its Content, and then the Button would appear to have multiple UI child elements that are children of the StackPanel.

ContentControl derived classes

ContentControl is the parent class for these immediately derived control classes:

Note

Page is a UserControl, not a ContentControl. ListView and GridView (and others) descend from ItemsControl.

Examples

The following example shows how to set different types of content for two Button controls and a CheckBox, which inherit from ContentControl.

  <!-- Create a Button with a string as its content. -->
  <Button Content="This is string content of a Button"/>

  <!-- Create a Button with a single UIElement as its content. -->
  <Button>
    <Rectangle Height="40" Width="40" Fill="Blue"/>
  </Button>

  <!-- Create a CheckBox with a panel that contains 
       multiple objects as its content. -->
  <CheckBox>
    <StackPanel Margin="3,0,0,0" Orientation="Horizontal">
      <Ellipse Height="10" Width="10" Fill="Green"/>
      <TextBlock Text="A string of text" TextAlignment="Center"></TextBlock>
    </StackPanel>
  </CheckBox>

Constructors summary

Initializes a new instance of the ContentControl class.

Properties summary

Gets or sets the content of a ContentControl.

Identifies the Content dependency property.

Gets or sets the data template that is used to display the content of the ContentControl.

Identifies the ContentTemplate dependency property

Gets the root element of the data template specified by the ContentTemplate property.

Gets or sets a selection object that changes the DataTemplate to apply for content, based on processing information about the content item or its container at run time.

Identifies the ContentTemplateSelector dependency property.

Gets or sets the collection of Transition style elements that apply to the content of a ContentControl.

Identifies the ContentTransitions dependency property.

Methods summary

Invoked when the value of the Content property changes.

Invoked when the value of the ContentTemplate property changes.

Invoked when the value of the ContentTemplateSelector property changes.

Constructors

  • ContentControl()
    ContentControl()
    ContentControl()
    ContentControl()

    Initializes a new instance of the ContentControl class.

    public ContentControl()public New()Public Sub New()public ContentControl()

Properties

  • Content
    Content
    Content
    Content

    Gets or sets the content of a ContentControl.

    public object Content { get; set; }public object Content { get; set; }Public ReadWrite Property Content As objectpublic object Content { get; set; }
    <contentControl>
        singleObject
    </contentControl>
    -or-
    <contentControl>stringContent</contentControl>
    

    Property Value

    • object
      object
      object

      An object that contains the control's content. The default is null.

  • ContentProperty
    ContentProperty
    ContentProperty
    ContentProperty

    Identifies the Content dependency property.

    public static DependencyProperty ContentProperty { get; }public static DependencyProperty ContentProperty { get; }Public Static ReadOnly Property ContentProperty As DependencyPropertypublic static DependencyProperty ContentProperty { get; }

    Property Value

  • ContentTemplate
    ContentTemplate
    ContentTemplate
    ContentTemplate

    Gets or sets the data template that is used to display the content of the ContentControl.

    public DataTemplate ContentTemplate { get; set; }public DataTemplate ContentTemplate { get; set; }Public ReadWrite Property ContentTemplate As DataTemplatepublic DataTemplate ContentTemplate { get; set; }
    <contentControl>
      <contentControl.ContentTemplate>
        dataTemplate
      </contentControl.ContentTemplate>
    </contentControl>
    

    Property Value

    Remarks

    Instead of declaring a fixed DataTemplate, you can also implement a DataTemplateSelector and use it to set the ContentTemplateSelector property. This technique enables custom template switching based on input data, at the application level. For more information, see DataTemplateSelector.

  • ContentTemplateProperty
    ContentTemplateProperty
    ContentTemplateProperty
    ContentTemplateProperty

    Identifies the ContentTemplate dependency property

    public static DependencyProperty ContentTemplateProperty { get; }public static DependencyProperty ContentTemplateProperty { get; }Public Static ReadOnly Property ContentTemplateProperty As DependencyPropertypublic static DependencyProperty ContentTemplateProperty { get; }

    Property Value

  • ContentTemplateRoot
    ContentTemplateRoot
    ContentTemplateRoot
    ContentTemplateRoot

    Gets the root element of the data template specified by the ContentTemplate property.

    public UIElement ContentTemplateRoot { get; }public UIElement ContentTemplateRoot { get; }Public ReadOnly Property ContentTemplateRoot As UIElementpublic UIElement ContentTemplateRoot { get; }

    Property Value

  • ContentTemplateSelector
    ContentTemplateSelector
    ContentTemplateSelector
    ContentTemplateSelector

    Gets or sets a selection object that changes the DataTemplate to apply for content, based on processing information about the content item or its container at run time.

    public DataTemplateSelector ContentTemplateSelector { get; set; }public DataTemplateSelector ContentTemplateSelector { get; set; }Public ReadWrite Property ContentTemplateSelector As DataTemplateSelectorpublic DataTemplateSelector ContentTemplateSelector { get; set; }
    <contentControl ContentTemplateSelector="selectorReference" />
    
    

    Property Value

  • ContentTemplateSelectorProperty
    ContentTemplateSelectorProperty
    ContentTemplateSelectorProperty
    ContentTemplateSelectorProperty

    Identifies the ContentTemplateSelector dependency property.

    public static DependencyProperty ContentTemplateSelectorProperty { get; }public static DependencyProperty ContentTemplateSelectorProperty { get; }Public Static ReadOnly Property ContentTemplateSelectorProperty As DependencyPropertypublic static DependencyProperty ContentTemplateSelectorProperty { get; }

    Property Value

  • ContentTransitions
    ContentTransitions
    ContentTransitions
    ContentTransitions

    Gets or sets the collection of Transition style elements that apply to the content of a ContentControl.

    public TransitionCollection ContentTransitions { get; set; }public TransitionCollection ContentTransitions { get; set; }Public ReadWrite Property ContentTransitions As TransitionCollectionpublic TransitionCollection ContentTransitions { get; set; }
    <contentControl>
      <contentControl.ContentTransitions>
        <TransitionCollection>
          oneOrMoreTransitions
        </TransitionCollection>
      </contentControl.ContentTransitions>
    </contentControl>
    

    Property Value

    Remarks

    Important

    The XAML syntax for all properties that use a TransitionCollection value is unusual in that you must declare an explicit TransitionCollection object element as the value, and then provide object elements as child elements of TransitionCollection for each of the transition animations you want to use. For most other XAML collection properties you could omit the collection object element because it can be implicit, but properties that use TransitionCollection don't support the implicit collection usage. For more info on implicit collections and XAML, see XAML syntax guide.

    Transition animations play a particular role in UI design of your app. The basic idea is that when there is a change or transition, the animation draws the attention of the user to the change.

    It's not common to set the value of the ContentTransitions property directly on a ContentControl type that is a direct element of app UI. It's more common to have a transitions collection be a part of a visual state, template or style. In this case you use mechanisms such as Setter of a Style to specify the ContentTransitions property. Styles are typically stored as a XAML resource.

  • ContentTransitionsProperty
    ContentTransitionsProperty
    ContentTransitionsProperty
    ContentTransitionsProperty

    Identifies the ContentTransitions dependency property.

    public static DependencyProperty ContentTransitionsProperty { get; }public static DependencyProperty ContentTransitionsProperty { get; }Public Static ReadOnly Property ContentTransitionsProperty As DependencyPropertypublic static DependencyProperty ContentTransitionsProperty { get; }

    Property Value

Methods

  • OnContentChanged(Object, Object)
    OnContentChanged(Object, Object)
    OnContentChanged(Object, Object)
    OnContentChanged(Object, Object)

    Invoked when the value of the Content property changes.

    protected virtual void OnContentChanged(Object oldContent, Object newContent)protected virtual void OnContentChanged(Object oldContent, Object newContent)Protected Overridable Function OnContentChanged(oldContent As Object, newContent As Object) As voidprotected virtual void OnContentChanged(Object oldContent, Object newContent)

    Parameters

    • oldContent
      System.Object
      System.Object
      System.Object

      The old value of the Content property.

    • newContent
      System.Object
      System.Object
      System.Object

      The new value of the Content property.

    Remarks

    If a value for ContentTemplateSelector exists, then the default implementation calls SelectTemplate(Object, DependencyObject) on the implemented DataTemplateSelector, passing the newContent value as item, and the calling ContentControl as container. The return value then sets ContentTemplate automatically on the caller.

  • OnContentTemplateChanged(DataTemplate, DataTemplate)
    OnContentTemplateChanged(DataTemplate, DataTemplate)
    OnContentTemplateChanged(DataTemplate, DataTemplate)
    OnContentTemplateChanged(DataTemplate, DataTemplate)

    Invoked when the value of the ContentTemplate property changes.

    protected virtual void OnContentTemplateChanged(DataTemplate oldContentTemplate, DataTemplate newContentTemplate)protected virtual void OnContentTemplateChanged(DataTemplate oldContentTemplate, DataTemplate newContentTemplate)Protected Overridable Function OnContentTemplateChanged(oldContentTemplate As DataTemplate, newContentTemplate As DataTemplate) As voidprotected virtual void OnContentTemplateChanged(DataTemplate oldContentTemplate, DataTemplate newContentTemplate)

    Parameters

    Remarks

    Classes that derive from ContentControl can override this method in order to perform any custom logic that should apply, in cases where the DataTemplate that presents the content changes.

  • OnContentTemplateSelectorChanged(DataTemplateSelector, DataTemplateSelector)
    OnContentTemplateSelectorChanged(DataTemplateSelector, DataTemplateSelector)
    OnContentTemplateSelectorChanged(DataTemplateSelector, DataTemplateSelector)
    OnContentTemplateSelectorChanged(DataTemplateSelector, DataTemplateSelector)

    Invoked when the value of the ContentTemplateSelector property changes.

    protected virtual void OnContentTemplateSelectorChanged(DataTemplateSelector oldContentTemplateSelector, DataTemplateSelector newContentTemplateSelector)protected virtual void OnContentTemplateSelectorChanged(DataTemplateSelector oldContentTemplateSelector, DataTemplateSelector newContentTemplateSelector)Protected Overridable Function OnContentTemplateSelectorChanged(oldContentTemplateSelector As DataTemplateSelector, newContentTemplateSelector As DataTemplateSelector) As voidprotected virtual void OnContentTemplateSelectorChanged(DataTemplateSelector oldContentTemplateSelector, DataTemplateSelector newContentTemplateSelector)

    Parameters

    Remarks

    Classes that derive from ContentControl can override this method in order to perform any custom logic that should apply, in cases where the selector logic that automatically chooses the DataTemplate based on context changes.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.UI.Xaml.Markup.ContentPropertyAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll