Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move some absolute layout api docs directly in code #24332

Merged
merged 2 commits into from
Jan 25, 2025
Merged

Move some absolute layout api docs directly in code #24332

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e397dac
Move some absolute layout api docs directly in code
Aug 20, 2024
6318f88
Address comments
jfversluis Jan 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
205 changes: 0 additions & 205 deletions src/Controls/docs/Microsoft.Maui.Controls/AbsoluteLayout.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,152 +25,6 @@
<InterfaceName>Microsoft.Maui.Controls.IElementConfiguration&lt;Microsoft.Maui.Controls.AbsoluteLayout&gt;</InterfaceName>
</Interface>
</Interfaces>
<Docs>
<summary>Positions child elements at absolute positions.</summary>
<remarks>
<para>Application developers can control the placement of child elements by providing proportional coordinates, device coordinates, or a combination of both, depending on the <see cref="T:Microsoft.Maui.Layouts.AbsoluteLayoutFlags" /> values that are passed to <see cref="M:Microsoft.Maui.Controls.AbsoluteLayout.SetLayoutFlags(Microsoft.Maui.Controls.BindableObject,Microsoft.Maui.Layouts.AbsoluteLayoutFlags)" /> method. When one of the proportional <see cref="T:Microsoft.Maui.Layouts.AbsoluteLayoutFlags" /> enumeration values is provided, the corresponding X, or Y arguments that range between 0.0 and 1.0 will always cause the child to be displayed completely on screen. That is, you do not need to subtract or add the height or width of a child in order to display it flush with the left, right, top, or bottom of the <see cref="T:Microsoft.Maui.Controls.AbsoluteLayout" />. For width, height, X, or Y values that are not specified proportionally, application developers use device-dependent units to locate and size the child element.</para>
<example>
<para>The following example shows how to use an <see cref="T:Microsoft.Maui.Controls.AbsoluteLayout" /> with proportional position arguments.</para>
<code lang="csharp lang-csharp"><![CDATA[

Label header = new Label
{
Text = "AbsoluteLayout Demo",
FontSize = Device.GetNamedSize(NamedSize.Large, typeof(Label)),
HorizontalOptions = LayoutOptions.Center
};

AbsoluteLayout simpleLayout = new AbsoluteLayout
{
BackgroundColor = Color.Blue.WithLuminosity(0.9),
VerticalOptions = LayoutOptions.FillAndExpand
};

topLeftLabel = new Label
{
Text = "Top Left",
TextColor = Color.Black
};

centerLabel = new Label
{
Text = "Centered",
TextColor = Color.Black
};

bottomRightLabel = new Label
{
Text = "Bottom Right",
TextColor = Color.Black
};

// PositionProportional flag maps the range (0.0, 1.0) to
// the range "flush [left|top]" to "flush [right|bottom]"
AbsoluteLayout.SetLayoutFlags(bottomRightLabel,
AbsoluteLayoutFlags.PositionProportional);

AbsoluteLayout.SetLayoutBounds(topLeftLabel,
new Rectangle(0f,
0f, AbsoluteLayout.AutoSize, AbsoluteLayout.AutoSize));

AbsoluteLayout.SetLayoutFlags(centerLabel,
AbsoluteLayoutFlags.PositionProportional);

AbsoluteLayout.SetLayoutBounds(centerLabel,
new Rectangle(0.5,
0.5, AbsoluteLayout.AutoSize, AbsoluteLayout.AutoSize));

AbsoluteLayout.SetLayoutFlags(bottomRightLabel,
AbsoluteLayoutFlags.PositionProportional);

AbsoluteLayout.SetLayoutBounds(bottomRightLabel,
new Rectangle(1f,
1f, AbsoluteLayout.AutoSize, AbsoluteLayout.AutoSize));

simpleLayout.Children.Add(topLeftLabel);
simpleLayout.Children.Add(centerLabel);
simpleLayout.Children.Add(bottomRightLabel);
]]></code>
<para>The code sample below shows how to place two labels by specifying device-dependent units.</para>
<code lang="csharp lang-csharp"><![CDATA[

AbsoluteLayout simpleLayout = new AbsoluteLayout
{

BackgroundColor = Color.Blue.WithLuminosity(0.9),
VerticalOptions = LayoutOptions.FillAndExpand
};

Label header = new Label
{
Text = "Device Units Demo",
TextColor = Color.Black,
FontSize = Device.GetNamedSize(NamedSize.Large, typeof(Label))
};

topLeftText = new Label
{
Text = "Left",
TextColor = Color.Black
};

AbsoluteLayout.SetLayoutFlags(topLeftText,
AbsoluteLayoutFlags.None);

AbsoluteLayout.SetLayoutBounds(topLeftText,
new Rectangle(0f, 0f, 100f, 50f));

middleText = new Label
{
Text = "Device-dependent location",
TextColor = Color.Black
};

AbsoluteLayout.SetLayoutFlags(middleText,
AbsoluteLayoutFlags.None);

AbsoluteLayout.SetLayoutBounds(middleText,
new Rectangle(100f, 200f, 200f, 50f));

simpleLayout.Children.Add(topLeftText);
simpleLayout.Children.Add(middleText);

}]]></code>
</example>
<example>
<para>XAML for Microsoft.Maui.Controls supports the following attached properties for the <see cref="T:Microsoft.Maui.Controls.AbsoluteLayout" /> class:</para>
<list type="table">
<listheader>
<term>Attached Property</term>
<description>Value</description>
</listheader>
<item>
<term>AbsoluteLayout.LayoutBounds</term>
<description>
<para>A comma-separated list—possibly with spaces—of four values that specify the bounding rectangle's position and dimensions. The first two values in the list must represent numbers. The latter two values may each either be numbers, or the string "AutoSize". The <c>AbsoluteLayout.LayoutFlags</c> attached property determines how the values in the list are interpreted to create the bounding rectangle.</para>
</description>
</item>
<item>
<term>AbsoluteLayout.LayoutFlags</term>
<description>
<para>
<see cref="T:Microsoft.Maui.Layouts.AbsoluteLayoutFlags" /> enumeration value names: <c>All</c>, <c>None</c>, <c>HeightProportional</c>, <c>WidthProportional</c>, <c>SizeProportional</c>, <c>XProportional</c>, <c>YProportional</c>, or <c>PositionProportional</c>. Application developers can combine any of these flags together by supplying a comma-separated list. </para>
</description>
</item>
</list>
<para>Application developers can use XAML to lay out elements with the <see cref="T:Microsoft.Maui.Controls.AbsoluteLayout" /> class. The example below places a blue <see cref="T:Microsoft.Maui.Controls.BoxView" /> inside an <see cref="T:Microsoft.Maui.Controls.AbsoluteLayout" />: </para>
<code lang="XAML"><![CDATA[<AbsoluteLayout VerticalOptions="FillAndExpand"
HorizontalOptions="FillAndExpand">
<BoxView AbsoluteLayout.LayoutBounds="0.25, 0.25, 0.5, 0.5"
Color="Blue"
AbsoluteLayout.LayoutFlags="All" />
</AbsoluteLayout>
]]></code>
</example>
<para>The <see cref="T:Microsoft.Maui.Controls.AbsoluteLayout" /> class can lay its child elements out in proportional units, device units, or a combination of both. Application developers should remember the following points when specifying a <see cref="T:Microsoft.Maui.Controls.Shapes.Rectangle" /> structure that will define the layout bounds of a child element:
<list type="bullet"><item><term>For elements whose height and width fit on the screen, proportional position dimensions in the range [0,1] represent elements that are completely on the screen, regardless of whether the height, width, or both are specified in device or proportional units.</term></item><item><term>The above point means that, to specify an element in the lower right hand corner of the screen and that is half as wide and half as all as the screen, with a <see cref="T:Microsoft.Maui.Layouts.AbsoluteLayoutFlags" /> value of <c>All</c>, the application developer would specify "1.0, 1.0, 0.5, 0.5".</term></item><item><term>The app developer can inadvertently cause child elements for which one or both size dimensions were specified proportionally to be displayed partially off the screen, or hidden altogether, by specifying device-unit positions that do not leave enough room for the calculated size of the child.</term></item><item><term>Each part of the bounding <see cref="T:Microsoft.Maui.Controls.Shapes.Rectangle" /> structure is interpreted according to the <see cref="T:Microsoft.Maui.Layouts.AbsoluteLayoutFlags" /> value that controls it. A given rectangle might, for example, have an X-coordinate that is in device units, a Y-coordinate that is in proportional units, a height that is in proportional units, and a width that is in device units, or any other combination of device and proportional units. </term></item><item><term>Rectangles that, when interpreted by using the current <see cref="T:Microsoft.Maui.Layouts.AbsoluteLayoutFlags" /> set on the child, represent bounding boxes that are partially or wholly off-screen—for example, by having a width that is larger than the screen width—may give unexpected results.</term></item></list></para>
</remarks>
</Docs>
<Members>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public AbsoluteLayout ();" />
Expand Down Expand Up @@ -213,14 +67,6 @@
<ReturnValue>
<ReturnType>System.Double</ReturnType>
</ReturnValue>
<Docs>
<summary>A value that indicates that the width or height of the child should be sized to that child's native size.</summary>
<value>
</value>
<remarks>
<para>Application developers can set the width or height of the <see cref="P:Microsoft.Maui.Controls.VisualElement.Bounds" /> property to <see cref="P:Microsoft.Maui.Controls.AbsoluteLayout.AutoSize" /> on a visual element when adding to the layout to cause that element to be measured during the layout pass and sized appropriately.</para>
</remarks>
</Docs>
</Member>
<Member MemberName="Children">
<MemberSignature Language="C#" Value="public Microsoft.Maui.Controls.AbsoluteLayout.IAbsoluteList&lt;Microsoft.Maui.Controls.View&gt; Children { get; }" />
Expand Down Expand Up @@ -669,57 +515,6 @@
<Parameter Name="bindable" Type="Microsoft.Maui.Controls.BindableObject" />
<Parameter Name="flags" Type="Microsoft.Maui.Layouts.AbsoluteLayoutFlags" />
</Parameters>
<Docs>
<param name="bindable">The view on which to set the layout flags.</param>
<param name="flags">A <see cref="T:Microsoft.Maui.Layouts.AbsoluteLayoutFlags" /> that describes the how to interpret the layout bounds for <paramref name="bindable" />.</param>
<summary>Sets the layout flags of a view that will be used to interpret the layout bounds set on it when it is added to the layout.</summary>
<remarks>
<para>This method supports the <c>AbsoluteLayout.LayoutFlags</c> XAML attached property. In XAML, Application developers can specify the following <see cref="T:Microsoft.Maui.Layouts.AbsoluteLayoutFlags" /> enumeration value names for the value of this property on the children of a <see cref="T:Microsoft.Maui.Controls.AbsoluteLayout" />:</para>
<list type="bullet">
<item>
<term>
<c>All</c>
</term>
</item>
<item>
<term>
<c>None</c>
</term>
</item>
<item>
<term>
<c>HeightProportional</c>
</term>
</item>
<item>
<term>
<c>WidthProportional</c>
</term>
</item>
<item>
<term>
<c>SizeProportional</c>
</term>
</item>
<item>
<term>
<c>XProportional</c>
</term>
</item>
<item>
<term>
<c>YProportional</c>
</term>
</item>
<item>
<term>
<c>PositionProportional</c>
</term>
</item>
</list>
<para>Application developers can combine any of the above values by supplying a comma-separated list. Application developers can call this method to update the layout flags of a view after it is added.</para>
</remarks>
</Docs>
</Member>
</Members>
</Type>
63 changes: 57 additions & 6 deletions src/Controls/src/Core/Layout/AbsoluteLayout.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,16 @@

namespace Microsoft.Maui.Controls
{
/// <include file="../../../docs/Microsoft.Maui.Controls/AbsoluteLayout.xml" path="Type[@FullName='Microsoft.Maui.Controls.AbsoluteLayout']/Docs/*" />
/// <summary>Positions child elements at absolute positions.</summary>
/// <remarks>
/// Application developers can control the placement of child elements by providing proportional coordinates, device coordinates, or a combination of both,
/// depending on the <see cref="AbsoluteLayoutFlags" /> values that are passed to
/// <see cref="SetLayoutFlags(BindableObject,AbsoluteLayoutFlags)" /> method.
/// When one of the proportional <see cref="AbsoluteLayoutFlags" /> enumeration values is provided, the corresponding X, or Y arguments that
/// range between 0.0 and 1.0 will always cause the child to be displayed completely on screen. That is, you do not need to subtract or add the height or width of a
/// child in order to display it flush with the left, right, top, or bottom of the <see cref="AbsoluteLayout" />. For width, height, X, or
/// Y values that are not specified proportionally, application developers use device-dependent units to locate and size the child element.
/// </remarks>
public class AbsoluteLayout : Layout, IAbsoluteLayout
{
readonly Dictionary<IView, AbsoluteLayoutInfo> _viewInfo = new();
Expand All @@ -16,7 +25,11 @@ protected override ILayoutManager CreateLayoutManager()
return new AbsoluteLayoutManager(this);
}

/// <include file="../../../docs/Microsoft.Maui.Controls/AbsoluteLayout.xml" path="//Member[@MemberName='AutoSize']/Docs/*" />
/// <summary>A value that indicates that the width or height of the child should be sized to that child's native size.</summary>
/// <remarks>
/// Application developers can set the width or height of the <see cref="VisualElement.Bounds" /> property to <see cref="AutoSize" />
/// on a visual element when adding to the layout to cause that element to be measured during the layout pass and sized appropriately.
/// </remarks>
public static double AutoSize = -1;

#region Attached Properties
Expand All @@ -37,33 +50,56 @@ static void LayoutBoundsPropertyChanged(BindableObject bindable, object oldValue
}
}

/// <include file="../../../docs/Microsoft.Maui.Controls/AbsoluteLayout.xml" path="//Member[@MemberName='GetLayoutFlags'][1]/Docs/*" />
/// <summary>
/// Gets the layout flags of a view that will be used to interpret the layout bounds set on it when it is added to the layout.
/// </summary>
/// <param name="bindable">The bindable object to retrieve the layout flags for.</param>
/// <returns>The layout flags applied to the given bindable object.</returns>
public static AbsoluteLayoutFlags GetLayoutFlags(BindableObject bindable)
{
return (AbsoluteLayoutFlags)bindable.GetValue(LayoutFlagsProperty);
}

/// <include file="../../../docs/Microsoft.Maui.Controls/AbsoluteLayout.xml" path="//Member[@MemberName='GetLayoutBounds'][1]/Docs/*" />
/// <summary>
/// Gets the layout bounds of a view that will be used to interpret the layout bounds set on it when it is added to the layout.
/// </summary>
/// <param name="bindable">The bindable object to determine the layout bounds for.</param>
/// <returns>A <see cref="Rect"/> with the layout bounds for the given bindable object.</returns>
[System.ComponentModel.TypeConverter(typeof(BoundsTypeConverter))]
public static Rect GetLayoutBounds(BindableObject bindable)
{
return (Rect)bindable.GetValue(LayoutBoundsProperty);
}

/// <include file="../../../docs/Microsoft.Maui.Controls/AbsoluteLayout.xml" path="//Member[@MemberName='SetLayoutFlags'][1]/Docs/*" />
/// <summary>
/// Sets the layout flags of a view that will be used to interpret the layout bounds set on it when it is added to the layout.
/// </summary>
/// <remarks>
/// This method supports the <c>AbsoluteLayout.LayoutFlags</c> XAML attached property.
/// In XAML, application developers can specify one or more of the <see cref="AbsoluteLayoutFlags" /> enumeration value names for the value of this property on the children of a <see cref="AbsoluteLayout" />.
/// </remarks>
public static void SetLayoutFlags(BindableObject bindable, AbsoluteLayoutFlags flags)
{
bindable.SetValue(LayoutFlagsProperty, flags);
}

/// <include file="../../../docs/Microsoft.Maui.Controls/AbsoluteLayout.xml" path="//Member[@MemberName='SetLayoutBounds'][1]/Docs/*" />
/// <summary>
/// Sets the layout bounds of a view that will be used to interpret the layout bounds set on it when it is added to the layout.
/// </summary>
/// <param name="bindable">The bindable object to set the layout bounds for.</param>
/// <param name="bounds">The bounds to set on the given bindable object.</param>
public static void SetLayoutBounds(BindableObject bindable, Rect bounds)
{
bindable.SetValue(LayoutBoundsProperty, bounds);
}

#endregion

/// <summary>
/// Gets the layout flags of a view that will be used to interpret the layout bounds set on it when it is added to the layout.
/// </summary>
/// <param name="view">The view to retrieve the layout flags for.</param>
/// <returns>The layout flags applied to the given view.</returns>
public AbsoluteLayoutFlags GetLayoutFlags(IView view)
{
return view switch
Expand All @@ -73,6 +109,11 @@ public AbsoluteLayoutFlags GetLayoutFlags(IView view)
};
}

/// <summary>
/// Gets the layout bounds of a view that will be used to interpret the layout bounds set on it when it is added to the layout.
/// </summary>
/// <param name="view">The view to determine the layout bounds for.</param>
/// <returns>A <see cref="Rect"/> with the layout bounds for the given view.</returns>
public Rect GetLayoutBounds(IView view)
{
return view switch
Expand All @@ -82,6 +123,11 @@ public Rect GetLayoutBounds(IView view)
};
}

/// <summary>
/// Sets the layout flags of a view that will be used to interpret the layout bounds set on it when it is added to the layout.
/// </summary>
/// <param name="view">The view to apply the layout flags to.</param>
/// <param name="flags">The flags to apply to the view.</param>
public void SetLayoutFlags(IView view, AbsoluteLayoutFlags flags)
{
switch (view)
Expand All @@ -95,6 +141,11 @@ public void SetLayoutFlags(IView view, AbsoluteLayoutFlags flags)
}
}

/// <summary>
/// Sets the layout bounds of a view that will be used to interpret the layout bounds set on it when it is added to the layout.
/// </summary>
/// <param name="view">The view to set the layout bounds for.</param>
/// <param name="bounds">The bounds to set on the given view.</param>
public void SetLayoutBounds(IView view, Rect bounds)
{
switch (view)
Expand Down
Loading