FrameworkElement.Margin Property
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Gets or sets the outer margin of a FrameworkElement.
Namespace: System.Windows
Assembly: System.Windows (in System.Windows.dll)
Syntax
'Declaration
Public Property Margin As Thickness
public Thickness Margin { get; set; }
<frameworkElement Margin="uniform"/>
- or -
<frameworkElement Margin="left+right,top+bottom"/>
- or -
<frameworkElement Margin="left,top,right,bottom"/>
XAML Values
uniform
A value measured by pixels that specifies a uniform Thickness. The uniform value is applied to all four Thickness properties (Left, Top, Right, Bottom).left+right
A value measured by pixels that specifies the Left and Right of a symmetrical Thickness.top+bottom
A value measured by pixels that specifies the Top and Bottom of a symmetrical Thickness.left top right bottom
Values measured by pixels that specify the four possible dimension properties of a Thickness structure (Left, Top, Right, Bottom).
In the XAML syntaxes shown previously, you can also use a space instead of a comma as the delimiter between values.
See Remarks for value type, value bounds and edge-case considerations that affect both code and XAML usages of Margin.
Property Value
Type: System.Windows.Thickness
Provides margin values for the object. The default value is a default Thickness with all properties (dimensions) equal to 0.
Remarks
Dependency property identifier field: MarginProperty
The margin is the space between this object and other objects that will be adjacent when layout creates the UI. The other objects participating in layout might be peer objects (such as other objects in the collection of a common parent control), or might also be this object's parent in the visual tree.
Margin can be set as discrete Thickness values instead of as a uniform value so that the margin around an object can be set asymmetrically. The Thickness structure itself supports string type conversion so that you can specify an asymmetric Margin in XAML attribute syntax. For example, in XAML, an object that has a margin specified as Margin="15,10,0,10" would have a margin of 15 pixels on the left, 10 on the top, 0 on the right, and 10 on the bottom.
<Grid x:Name="LayoutRoot" Background="Coral" Width="300" Height="100" ShowGridLines="True">
<Grid.ColumnDefinitions>
<ColumnDefinition />
<ColumnDefinition />
</Grid.ColumnDefinitions>
<Grid.RowDefinitions>
<RowDefinition />
<RowDefinition />
</Grid.RowDefinitions>
<TextBlock Grid.Column="0" Grid.Row="0" Text="First Name" HorizontalAlignment="Center" VerticalAlignment="Center" />
<TextBlock Grid.Column="0" Grid.Row="1" Text="Last Name" HorizontalAlignment="Center" VerticalAlignment="Center" />
<TextBox Grid.Column="1" Grid.Row="0" Margin="15,10,15,10" />
<TextBox Grid.Column="1" Grid.Row="1" Margin="15,10,15,10" />
</Grid>
The following illustration shows the effect of setting the Margin property.
.png "margin and alignment diagram")
Margin Behavior and Layout
A margin value greater than 0 applies space outside the layout's ActualWidth and ActualHeight.
Margins are additive for peer objects in a layout; for example, two horizontally or vertically adjacent objects both with a margin of 30 set on the adjoining edge would have 60 pixels of space between them.
Objects that have margins set will not typically constrain the size of the specified Margin if the allotted rectangle space is not large enough for the margin plus the object's content area. The content area will be constrained instead when layout is calculated. The only case where margins would be constrained also is if the content is already constrained all the way to zero. However, this behavior is ultimately controlled by the specific type that is interpreting Margin, as well as the layout container of that object.
Negative values for margin dimensions are permitted, but should be used with caution (and be aware that negative margins can be interpreted differently by different class layout implementations). Negative margins typically clip the content of the object in that direction.
Non-integral values for margin values are technically permitted, but should generally be avoided and are typically rounded by the default layout rounding behavior. See Layout Rounding.
There is no prescribed upper bound for margin dimensions, and it is possible (though rarely desirable) to set a margin that positions object content outside the Silverlight content area so that the object content does not display in view.
Margin and Padding
A related concept is padding. For an object and its bounding box, the margin is extra space that is allocated to the outside of the bounding box when the UI element is contained and rendered. Padding is the area inside the bounding box, and affects the layout of any additional content or child objects inside the element. FrameworkElement does not yet define a content model; therefore, the properties for padding are instead defined by subclasses that do define a content model. The most common such property is TextBlock.Padding. Other properties are TextBlock.Padding and Border.Padding. For more information about the relationship between margin and padding, see Silverlight Layout System.
Animating a Margin
Silverlight does not currently support direct animation of a margin, because there is no ThicknessAnimation type in Silverlight (the type is located in WPF). Border has the same issue because BorderThickness also uses the Thickness type. One possible workaround is to wrap the element in a transparent panel and animate relevant Double properties of the panel.
Examples
The following example sets margins for various elements in XAML.
<Canvas>
<Rectangle Height="500" Width="500" Margin="50,50,0,0" Stroke="Black" />
<InkPresenter x:Name="MyIP" Height="500" Width="500" Background="Transparent" Margin="50,50,0,0"
MouseLeftButtonDown="MyIP_MouseLeftButtonDown"
MouseMove="MyIP_MouseMove"
LostMouseCapture="MyIP_LostMouseCapture"/>
<Button x:Name="BtPen" Content="Pen" Margin="70,490,0,0" Height="25" Width="90" Click="BtPen_Click" />
<Button x:Name="BtMarker" Content="Marker" Margin="180,490,0,0" Height="25" Width="90" Click="BtMarker_Click" />
<Button x:Name="BtHighlighter" Content="Highlighter" Margin="290,490,0,0" Height="25" Width="90" Click="BtHighlighter_Click" />
<Button x:Name="BtEraser" Content="Erase All" Margin="400,490,0,0" Height="25" Width="90" Click="BtEraser_Click" />
</Canvas>
The following example shows how to set a Margin in code, by creating a new Thickness inline. This is shown in the context where setting Margin in code might be necessary: when you are creating the full UI element where the Margin is being set with code instead of XAML.
Dim button1 As New Button()
button1.Width = 50
button1.Height = 30
Dim panel1 As New StackPanel()
panel1.Orientation = Orientation.Horizontal
Dim rect1 As New Rectangle()
rect1.Width = 10
rect1.Fill = New SolidColorBrush(Colors.Green)
Dim tb3 As New TextBlock()
tb3.Margin = New Thickness(2)
tb3.Text = "Green"
tb3.TextAlignment = TextAlignment.Center
panel1.Children.Add(tb3)
panel1.Children.Add(rect1)
button1.Content = panel1
LayoutRoot.Children.Add(button1)
Button button1 = new Button();
button1.Width = 50;
button1.Height = 30;
StackPanel panel1 = new StackPanel();
panel1.Orientation = Orientation.Horizontal;
Rectangle rect1 = new Rectangle();
rect1.Width = 10;
rect1.Fill = new SolidColorBrush(Colors.Green);
TextBlock tb3 = new TextBlock();
tb3.Margin = new Thickness(2);
tb3.Text = "Green";
tb3.TextAlignment = TextAlignment.Center;
panel1.Children.Add(tb3);
panel1.Children.Add(rect1);
button1.Content = panel1;
LayoutRoot.Children.Add(button1);
Version Information
Silverlight
Supported in: 5, 4, 3
Silverlight for Windows Phone
Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0
Platforms
For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.
See Also