Skip to content

Latest commit

 

History

History
83 lines (60 loc) · 5.66 KB

contentcontrol.md

File metadata and controls

83 lines (60 loc) · 5.66 KB
-api-id -api-type
T:Windows.UI.Xaml.Controls.ContentControl
winrt class

Windows.UI.Xaml.Controls.ContentControl

-description

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

-xaml-syntax

<ContentControl .../>
-or-
<contentControl>
    singleObject
</contentControl>
-or-
<contentControl>stringContent</contentControl>

-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.

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

-see-also

Control