diff --git a/src/Controls/src/Xaml/Controls.Xaml.csproj b/src/Controls/src/Xaml/Controls.Xaml.csproj index 33b2deef045d..060a5e1741e7 100644 --- a/src/Controls/src/Xaml/Controls.Xaml.csproj +++ b/src/Controls/src/Xaml/Controls.Xaml.csproj @@ -7,7 +7,8 @@ Microsoft.Maui.Controls.Xaml false <_MauiDesignDllBuild Condition=" '$(OS)' != 'Unix' ">True - $(NoWarn);CA2200;CS1591;RS0041 + $(NoWarn);CA2200;RS0041 + $(WarningsAsErrors);CS1591 true diff --git a/src/Controls/src/Xaml/Hosting/AppHostBuilderExtensions.cs b/src/Controls/src/Xaml/Hosting/AppHostBuilderExtensions.cs index 37d545a56d7c..471986614305 100644 --- a/src/Controls/src/Xaml/Hosting/AppHostBuilderExtensions.cs +++ b/src/Controls/src/Xaml/Hosting/AppHostBuilderExtensions.cs @@ -35,6 +35,11 @@ public static partial class AppHostBuilderExtensions return builder; } + /// + /// Registers the .NET MAUI Controls handlers with the handlers collection. + /// + /// The handlers collection to register handlers with. + /// The handlers collection for chaining. public static IMauiHandlersCollection AddMauiControlsHandlers(this IMauiHandlersCollection handlersCollection) => handlersCollection.AddControlsHandlers(); diff --git a/src/Controls/src/Xaml/MarkupExtensions/AppThemeBindingExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/AppThemeBindingExtension.cs index 96beb9a4f134..96e37d4dd0df 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/AppThemeBindingExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/AppThemeBindingExtension.cs @@ -5,6 +5,9 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that creates a binding with different values for light and dark themes. + /// [ContentProperty(nameof(Default))] [RequireService( [typeof(IProvideValueTarget), @@ -20,6 +23,9 @@ public class AppThemeBindingExtension : IMarkupExtension object _dark; bool _hasdark; + /// + /// Gets or sets the default value to use when no theme-specific value is set. + /// public object Default { get => _default; set @@ -28,6 +34,10 @@ public object Default _hasdefault = true; } } + + /// + /// Gets or sets the value to use when the light theme is active. + /// public object Light { get => _light; set @@ -36,6 +46,10 @@ public object Light _haslight = true; } } + + /// + /// Gets or sets the value to use when the dark theme is active. + /// public object Dark { get => _dark; set @@ -44,6 +58,10 @@ public object Dark _hasdark = true; } } + + /// + /// Gets the current value based on the active theme. + /// public object Value { get; private set; } public object ProvideValue(IServiceProvider serviceProvider) => (this as IMarkupExtension).ProvideValue(serviceProvider); diff --git a/src/Controls/src/Xaml/MarkupExtensions/ArrayExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/ArrayExtension.cs index 00cfb14d3186..7a6bc2cffe58 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/ArrayExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/ArrayExtension.cs @@ -5,6 +5,9 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that creates an array of objects. + /// [ContentProperty(nameof(Items))] [AcceptEmptyServiceProvider] #if !NETSTANDARD @@ -12,13 +15,22 @@ namespace Microsoft.Maui.Controls.Xaml #endif public class ArrayExtension : IMarkupExtension { + /// + /// Initializes a new instance of the class. + /// public ArrayExtension() { Items = new List(); } + /// + /// Gets the list of items to include in the array. + /// public IList Items { get; } + /// + /// Gets or sets the type of elements in the array. + /// public Type Type { get; set; } public Array ProvideValue(IServiceProvider serviceProvider) diff --git a/src/Controls/src/Xaml/MarkupExtensions/BindingExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/BindingExtension.cs index 745cd723fee4..02228ad40da6 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/BindingExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/BindingExtension.cs @@ -5,19 +5,59 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that creates a from a XAML attribute value. + /// [ContentProperty(nameof(Path))] [RequireService([typeof(IXamlTypeResolver), typeof(IXamlDataTypeProvider)])] public sealed class BindingExtension : IMarkupExtension { + /// + /// Gets or sets the path to the binding source property. + /// public string Path { get; set; } = Binding.SelfPath; + + /// + /// Gets or sets the binding mode. + /// public BindingMode Mode { get; set; } = BindingMode.Default; + + /// + /// Gets or sets the converter to use when converting between source and target values. + /// public IValueConverter Converter { get; set; } + + /// + /// Gets or sets a parameter to pass to the converter. + /// public object ConverterParameter { get; set; } + + /// + /// Gets or sets a format string to use when converting the bound value to a string. + /// public string StringFormat { get; set; } + + /// + /// Gets or sets the source object for the binding. + /// public object Source { get; set; } + + /// + /// Gets or sets the name of the event that triggers the source update in TwoWay bindings. + /// public string UpdateSourceEventName { get; set; } + + /// + /// Gets or sets the value to use when the target property value is . + /// public object TargetNullValue { get; set; } + + /// + /// Gets or sets the value to use when the binding cannot return a value. + /// public object FallbackValue { get; set; } + + /// For internal use only. This API can be changed or removed without notice at any time. [EditorBrowsable(EditorBrowsableState.Never)] public TypedBindingBase TypedBinding { get; set; } BindingBase IMarkupExtension.ProvideValue(IServiceProvider serviceProvider) diff --git a/src/Controls/src/Xaml/MarkupExtensions/DataTemplateExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/DataTemplateExtension.cs index ec78d9d1a80b..c5d5c0ba4860 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/DataTemplateExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/DataTemplateExtension.cs @@ -3,11 +3,17 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that creates a for a specified type. + /// [ContentProperty(nameof(TypeName))] [ProvideCompiled("Microsoft.Maui.Controls.Build.Tasks.DataTemplateExtension")] [RequiresUnreferencedCode(TrimmerConstants.XamlRuntimeParsingNotSupportedWarning)] public sealed class DataTemplateExtension : IMarkupExtension { + /// + /// Gets or sets the type name for which to create the data template. + /// public string TypeName { get; set; } public DataTemplate ProvideValue(IServiceProvider serviceProvider) diff --git a/src/Controls/src/Xaml/MarkupExtensions/DynamicResourceExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/DynamicResourceExtension.cs index aa73f39ab195..e41a7c8d075c 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/DynamicResourceExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/DynamicResourceExtension.cs @@ -3,10 +3,16 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that creates a for dynamic resource lookup. + /// [ContentProperty(nameof(Key))] [RequireService([typeof(IXmlLineInfoProvider)])] public sealed class DynamicResourceExtension : IMarkupExtension { + /// + /// Gets or sets the key of the dynamic resource to retrieve. + /// public string Key { get; set; } public object ProvideValue(IServiceProvider serviceProvider) => ((IMarkupExtension)this).ProvideValue(serviceProvider); diff --git a/src/Controls/src/Xaml/MarkupExtensions/FontImageExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/FontImageExtension.cs index fb9198169a8c..3f662db966ff 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/FontImageExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/FontImageExtension.cs @@ -3,6 +3,9 @@ namespace Microsoft.Maui.Controls.Xaml; +/// +/// Provides a XAML markup extension that creates a font image. Use instead. +/// [Obsolete("Use FontImageSource")] public class FontImageExtension : FontImageSource { diff --git a/src/Controls/src/Xaml/MarkupExtensions/NullExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/NullExtension.cs index b20a59803b2b..5ce944cc824b 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/NullExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/NullExtension.cs @@ -2,6 +2,9 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that returns . + /// [ProvideCompiled("Microsoft.Maui.Controls.Build.Tasks.NullExtension")] [AcceptEmptyServiceProvider] public class NullExtension : IMarkupExtension diff --git a/src/Controls/src/Xaml/MarkupExtensions/OnIdiomExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/OnIdiomExtension.cs index c92eef52a5c7..d228894cbbfb 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/OnIdiomExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/OnIdiomExtension.cs @@ -8,6 +8,9 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that returns different values depending on the device idiom. + /// [ContentProperty(nameof(Default))] [RequireService( [typeof(IProvideValueTarget), @@ -19,15 +22,44 @@ public class OnIdiomExtension : IMarkupExtension { // See Device.Idiom + /// + /// Gets or sets the default value to use if no idiom-specific value is set. + /// public object Default { get; set; } + + /// + /// Gets or sets the value to use on phone devices. + /// public object Phone { get; set; } + + /// + /// Gets or sets the value to use on tablet devices. + /// public object Tablet { get; set; } + + /// + /// Gets or sets the value to use on desktop devices. + /// public object Desktop { get; set; } + + /// + /// Gets or sets the value to use on TV devices. + /// public object TV { get; set; } + + /// + /// Gets or sets the value to use on watch devices. + /// public object Watch { get; set; } + /// + /// Gets or sets a converter to apply to the idiom-specific value. + /// public IValueConverter Converter { get; set; } + /// + /// Gets or sets a parameter to pass to the converter. + /// public object ConverterParameter { get; set; } public object ProvideValue(IServiceProvider serviceProvider) diff --git a/src/Controls/src/Xaml/MarkupExtensions/OnPlatformExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/OnPlatformExtension.cs index 2e3065b2cf4b..5d8d080e6ca7 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/OnPlatformExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/OnPlatformExtension.cs @@ -7,6 +7,9 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that returns different values depending on the platform the app is running on. + /// [ContentProperty(nameof(Default))] [RequireService( [typeof(IProvideValueTarget), @@ -18,20 +21,56 @@ public class OnPlatformExtension : IMarkupExtension { static object s_notset = new object(); + /// + /// Gets or sets the default value to use if no platform-specific value is set. + /// public object Default { get; set; } = s_notset; + + /// + /// Gets or sets the value to use on Android. + /// public object Android { get; set; } = s_notset; + internal object GTK { get; set; } = s_notset; + + /// + /// Gets or sets the value to use on iOS. + /// public object iOS { get; set; } = s_notset; + internal object macOS { get; set; } = s_notset; + + /// + /// Gets or sets the value to use on Mac Catalyst. + /// public object MacCatalyst { get; set; } = s_notset; + + /// + /// Gets or sets the value to use on Tizen. + /// public object Tizen { get; set; } = s_notset; + + /// + /// Gets or sets the value to use on UWP. Use instead. + /// [Obsolete("Use WinUI instead.")] public object UWP { get; set; } = s_notset; + internal object WPF { get; set; } = s_notset; + + /// + /// Gets or sets the value to use on Windows (WinUI). + /// public object WinUI { get; set; } = s_notset; + /// + /// Gets or sets a converter to apply to the platform-specific value. + /// public IValueConverter Converter { get; set; } + /// + /// Gets or sets a parameter to pass to the converter. + /// public object ConverterParameter { get; set; } public object ProvideValue(IServiceProvider serviceProvider) diff --git a/src/Controls/src/Xaml/MarkupExtensions/ReferenceExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/ReferenceExtension.cs index cf870f3dae08..52cd98f1112b 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/ReferenceExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/ReferenceExtension.cs @@ -4,10 +4,16 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that returns an object by its x:Name from the current XAML namescope. + /// [ContentProperty(nameof(Name))] [RequireService([typeof(IReferenceProvider), typeof(IProvideValueTarget)])] public class ReferenceExtension : IMarkupExtension { + /// + /// Gets or sets the x:Name of the element to reference. + /// public string Name { get; set; } public object ProvideValue(IServiceProvider serviceProvider) diff --git a/src/Controls/src/Xaml/MarkupExtensions/RelativeSourceExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/RelativeSourceExtension.cs index b70626f799de..d4b0bd2fba4b 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/RelativeSourceExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/RelativeSourceExtension.cs @@ -3,22 +3,34 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that returns a for relative bindings. + /// [ContentProperty("Mode")] [AcceptEmptyServiceProvider] public sealed class RelativeSourceExtension : IMarkupExtension { + /// + /// Gets or sets the mode of the relative binding source. + /// public RelativeBindingSourceMode Mode { get; set; } + /// + /// Gets or sets the level of ancestor to look for when Mode is FindAncestor or FindAncestorBindingContext. + /// public int AncestorLevel { get; set; } + /// + /// Gets or sets the type of ancestor to look for when Mode is FindAncestor or FindAncestorBindingContext. + /// public Type AncestorType { get; diff --git a/src/Controls/src/Xaml/MarkupExtensions/StaticExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/StaticExtension.cs index 8a946fc644d3..fbd764026394 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/StaticExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/StaticExtension.cs @@ -6,12 +6,18 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that returns the value of a static field or property. + /// [ContentProperty(nameof(Member))] [ProvideCompiled("Microsoft.Maui.Controls.Build.Tasks.StaticExtension")] [RequiresUnreferencedCode(TrimmerConstants.XamlRuntimeParsingNotSupportedWarning)] [RequireService([typeof(IXamlTypeResolver)])] public class StaticExtension : IMarkupExtension { + /// + /// Gets or sets the name of the static member in the form [prefix:]typeName.memberName. + /// public string Member { get; set; } public object ProvideValue(IServiceProvider serviceProvider) diff --git a/src/Controls/src/Xaml/MarkupExtensions/StaticResourceExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/StaticResourceExtension.cs index a08beaadc691..ef8757d883e2 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/StaticResourceExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/StaticResourceExtension.cs @@ -4,11 +4,17 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that resolves a resource from a . + /// [ContentProperty(nameof(Key))] [RequireService([typeof(IXmlLineInfoProvider), typeof(IProvideParentValues), typeof(IRootObjectProvider)])] [ProvideCompiled("Microsoft.Maui.Controls.Build.Tasks.StaticResourceExtension")] public sealed class StaticResourceExtension : IMarkupExtension { + /// + /// Gets or sets the key of the resource to retrieve. + /// public string Key { get; set; } public object ProvideValue(IServiceProvider serviceProvider) diff --git a/src/Controls/src/Xaml/MarkupExtensions/StyleSheetExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/StyleSheetExtension.cs index 8497accc921c..cca7710f3713 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/StyleSheetExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/StyleSheetExtension.cs @@ -6,13 +6,22 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that loads a CSS style sheet from a source or inline content. + /// [ContentProperty(nameof(Style))] [ProvideCompiled("Microsoft.Maui.Controls.XamlC.StyleSheetProvider")] [RequireService([typeof(IXmlLineInfoProvider), typeof(IRootObjectProvider)])] public sealed class StyleSheetExtension : IValueProvider { + /// + /// Gets or sets the inline CSS style sheet content. + /// public string Style { get; set; } + /// + /// Gets or sets the URI to the CSS style sheet resource. + /// [System.ComponentModel.TypeConverter(typeof(UriTypeConverter))] public Uri Source { get; set; } diff --git a/src/Controls/src/Xaml/MarkupExtensions/TemplateBindingExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/TemplateBindingExtension.cs index 22985b7c45cb..e5bc88f8613b 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/TemplateBindingExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/TemplateBindingExtension.cs @@ -5,27 +5,49 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that creates a binding to the templated parent. + /// [ContentProperty(nameof(Path))] [AcceptEmptyServiceProvider] [RequiresUnreferencedCode(TrimmerConstants.StringPathBindingWarning, Url = TrimmerConstants.ExpressionBasedBindingsDocsUrl)] public sealed class TemplateBindingExtension : IMarkupExtension { + /// + /// Initializes a new instance of the class. + /// public TemplateBindingExtension() { Mode = BindingMode.Default; Path = Binding.SelfPath; } + /// + /// Gets or sets the path to the binding source property on the templated parent. + /// public string Path { get; set; } + /// + /// Gets or sets the binding mode. + /// public BindingMode Mode { get; set; } + /// + /// Gets or sets the converter to use when converting between source and target values. + /// public IValueConverter Converter { get; set; } + /// + /// Gets or sets a parameter to pass to the converter. + /// public object ConverterParameter { get; set; } + /// + /// Gets or sets a format string to use when converting the bound value to a string. + /// public string StringFormat { get; set; } + /// For internal use only. This API can be changed or removed without notice at any time. [EditorBrowsable(EditorBrowsableState.Never)] public TypedBindingBase TypedBinding { get; set; } BindingBase IMarkupExtension.ProvideValue(IServiceProvider serviceProvider) diff --git a/src/Controls/src/Xaml/MarkupExtensions/TypeExtension.cs b/src/Controls/src/Xaml/MarkupExtensions/TypeExtension.cs index 16286a82a402..a5fdf41b5c9c 100644 --- a/src/Controls/src/Xaml/MarkupExtensions/TypeExtension.cs +++ b/src/Controls/src/Xaml/MarkupExtensions/TypeExtension.cs @@ -2,11 +2,17 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides a XAML markup extension that returns a object for a specified type name. + /// [ContentProperty(nameof(TypeName))] [ProvideCompiled("Microsoft.Maui.Controls.Build.Tasks.TypeExtension")] [RequireService([typeof(IXamlTypeResolver), typeof(IXmlLineInfoProvider)])] public class TypeExtension : IMarkupExtension { + /// + /// Gets or sets the type name to resolve. + /// public string TypeName { get; set; } public Type ProvideValue(IServiceProvider serviceProvider) diff --git a/src/Controls/src/Xaml/ViewExtensions.cs b/src/Controls/src/Xaml/ViewExtensions.cs index 047c0058d595..64537e0e6201 100644 --- a/src/Controls/src/Xaml/ViewExtensions.cs +++ b/src/Controls/src/Xaml/ViewExtensions.cs @@ -31,18 +31,35 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Provides extension methods for loading XAML into objects. + /// [RequiresUnreferencedCode(TrimmerConstants.XamlRuntimeParsingNotSupportedWarning)] #if !NETSTANDARD [RequiresDynamicCode(TrimmerConstants.XamlRuntimeParsingNotSupportedWarning)] #endif public static class Extensions { + /// + /// Loads the XAML associated with the specified type into the view. + /// + /// The type of the view. + /// The view to load XAML into. + /// The type used to locate the XAML resource. + /// The view with XAML loaded. public static TXaml LoadFromXaml(this TXaml view, Type callingType) { XamlLoader.Load(view, callingType); return view; } + /// + /// Loads the specified XAML string into the view. + /// + /// The type of the view. + /// The view to load XAML into. + /// The XAML string to load. + /// The view with XAML loaded. public static TXaml LoadFromXaml(this TXaml view, string xaml) { XamlLoader.Load(view, xaml); diff --git a/src/Controls/src/Xaml/XamlFilePathAttribute.cs b/src/Controls/src/Xaml/XamlFilePathAttribute.cs index a96fc750fea1..67f59d552390 100644 --- a/src/Controls/src/Xaml/XamlFilePathAttribute.cs +++ b/src/Controls/src/Xaml/XamlFilePathAttribute.cs @@ -5,11 +5,21 @@ namespace Microsoft.Maui.Controls.Xaml { + /// + /// Specifies the file path of the XAML file associated with a type. + /// [AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)] public sealed class XamlFilePathAttribute : Attribute { + /// + /// Initializes a new instance of the with the file path of the caller. + /// + /// The file path, automatically set by the compiler. public XamlFilePathAttribute([CallerFilePath] string filePath = "") => FilePath = filePath; + /// + /// Gets the file path of the XAML file. + /// public string FilePath { get; } internal static string GetFilePathForObject(object view) => (view?.GetType().GetCustomAttributes(typeof(XamlFilePathAttribute), false).FirstOrDefault() as XamlFilePathAttribute)?.FilePath;