ContentControl
ContentControl
ContentControl
ContentControl
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// This API is not available in Javascript.
<ContentControl .../>
-or-
<contentControl>
singleObject
</contentControl>
-or-
<contentControl>stringContent</contentControl>
- Inheritance
-
ContentControlContentControlContentControlContentControl
- Attributes
| 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:
- AppBar
- ButtonBase
- FlyoutPresenter
- Frame
- GroupItem
- ListViewBaseHeaderItem
- ScrollViewer
- SelectorItem
- SettingsFlyout
- ToolTip
Note
Page is a UserControl, not a ContentControl. ListView and GridView (and others) descend from ItemsControl.
Constructors
ContentControl() ContentControl() ContentControl() ContentControl()
Initializes a new instance of the ContentControl class.
public : ContentControl()public ContentControl()Public Sub New()// This API is not available in Javascript.
Properties
Content 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// This API is not available in Javascript.
<contentControl>
singleObject
</contentControl>
-or-
<contentControl>stringContent</contentControl>
- Value
- PlatForm::Object 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 DependencyProperty// This API is not available in Javascript.
The identifier for the Content dependency property.
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 DataTemplate// This API is not available in Javascript.
<contentControl>
<contentControl.ContentTemplate>
dataTemplate
</contentControl.ContentTemplate>
</contentControl>
The data template that is used to display the content of the ContentControl.
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 DependencyProperty// This API is not available in Javascript.
The identifier for the ContentTemplate dependency property.
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 UIElement// This API is not available in Javascript.
The root element of the data template specified by the ContentTemplate property. The default is null.
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 DataTemplateSelector// This API is not available in Javascript.
<contentControl ContentTemplateSelector="selectorReference" />
A selection object that changes the DataTemplate to apply for content.
- See Also
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 DependencyProperty// This API is not available in Javascript.
The identifier for the ContentTemplateSelector dependency property.
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 TransitionCollection// This API is not available in Javascript.
<contentControl>
<contentControl.ContentTransitions>
<TransitionCollection>
oneOrMoreTransitions
</TransitionCollection>
</contentControl.ContentTransitions>
</contentControl>
The strongly typed collection of Transition style elements.
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 DependencyProperty// This API is not available in Javascript.
The identifier for the ContentTransitions dependency property.
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(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// This API is not available in Javascript.
- oldContent
- PlatForm::Object Object Object Object
The old value of the Content property.
- newContent
- PlatForm::Object Object Object Object
The new value of the Content property.
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) 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// This API is not available in Javascript.
- oldContentTemplate
- DataTemplate DataTemplate DataTemplate DataTemplate
The old value of the ContentTemplate property.
- newContentTemplate
- DataTemplate DataTemplate DataTemplate DataTemplate
The new value of the ContentTemplate property.
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 void// This API is not available in Javascript.
- oldContentTemplateSelector
- DataTemplateSelector DataTemplateSelector DataTemplateSelector DataTemplateSelector
The old value of the ContentTemplateSelector property.
- newContentTemplateSelector
- DataTemplateSelector DataTemplateSelector DataTemplateSelector DataTemplateSelector
The new value of the ContentTemplateSelector property.
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.