Content​Control Content​Control Content​Control Class

Definition

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

public : class ContentControl : Control, IContentControl, IContentControl2, IContentControlOverridespublic class ContentControl : Control, IContentControl, IContentControl2, IContentControlOverridesPublic Class ContentControl Inherits Control Implements IContentControl, IContentControl2, IContentControlOverrides
<ContentControl .../>
-or-
<contentControl>
    singleObject
</contentControl>
-or-
<contentControl>stringContent</contentControl>
Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Inherited Members

Inherited properties

Inherited events

Inherited methods

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>

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 ContentControl.Content to ContentPresenter.Content, then the value of ContentControl.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.

Constructors

ContentControl() ContentControl() ContentControl()

Initializes a new instance of the ContentControl class.

public : ContentControl()public ContentControl()Public Sub New()
Attributes

Properties

Content Content Content

Gets or sets the content of a ContentControl.

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

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

Attributes

ContentProperty ContentProperty ContentProperty

Identifies the Content dependency property.

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

The identifier for the Content dependency property.

Attributes

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 DataTemplate
<contentControl>
  <contentControl.ContentTemplate>
    dataTemplate
  </contentControl.ContentTemplate>
</contentControl>
Value
DataTemplate DataTemplate DataTemplate

The data template that is used to display the content of the ContentControl.

Attributes

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

Identifies the ContentTemplate dependency property

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

The identifier for the ContentTemplate dependency property.

Attributes

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 UIElement
Value
UIElement UIElement UIElement

The root element of the data template specified by the ContentTemplate property. The default is null.

Attributes

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 DataTemplateSelector
<contentControl ContentTemplateSelector="selectorReference" />

Value
DataTemplateSelector DataTemplateSelector DataTemplateSelector

A selection object that changes the DataTemplate to apply for content.

Attributes
See Also

ContentTemplateSelectorProperty ContentTemplateSelectorProperty ContentTemplateSelectorProperty

Identifies the ContentTemplateSelector dependency property.

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

The identifier for the ContentTemplateSelector dependency property.

Attributes

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 TransitionCollection
<contentControl>
  <contentControl.ContentTransitions>
    <TransitionCollection>
      oneOrMoreTransitions
    </TransitionCollection>
  </contentControl.ContentTransitions>
</contentControl>
Value
TransitionCollection TransitionCollection TransitionCollection

The strongly typed collection of Transition style elements.

Attributes

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

Identifies the ContentTransitions dependency property.

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

The identifier for the ContentTransitions dependency property.

Attributes

Methods

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

Invoked when the value of the Content property changes.

protected : virtual void OnContentChanged(PlatForm::Object oldContent, PlatForm::Object newContent)protected virtual void OnContentChanged(Object oldContent, Object newContent)Protected Overridable Function OnContentChanged(oldContent As Object, newContent As Object) As void
Parameters
oldContent
PlatForm::Object Object Object

The old value of the Content property.

newContent
PlatForm::Object Object Object

The new value of the Content property.

Attributes

Remarks

If a value for ContentTemplateSelector exists, then the default implementation calls SelectTemplate 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)

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 void
Parameters
oldContentTemplate
DataTemplate DataTemplate DataTemplate

The old value of the ContentTemplate property.

newContentTemplate
DataTemplate DataTemplate DataTemplate

The new value of the ContentTemplate property.

Attributes

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)

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 void
Parameters
oldContentTemplateSelector
DataTemplateSelector DataTemplateSelector DataTemplateSelector

The old value of the ContentTemplateSelector property.

newContentTemplateSelector
DataTemplateSelector DataTemplateSelector DataTemplateSelector

The new value of the ContentTemplateSelector property.

Attributes

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.

See Also