Skip to content

Commit

Permalink
docs: added inline docs for public members
Browse files Browse the repository at this point in the history
  • Loading branch information
pictos authored and nickrandolph committed Jul 25, 2023
1 parent 6efa82c commit 7acc6ad
Show file tree
Hide file tree
Showing 9 changed files with 138 additions and 10 deletions.
22 changes: 22 additions & 0 deletions src/Uno.Extensions.Maui.UI/MauiBinding.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,43 @@

namespace Uno.Extensions.Maui;

/// <summary>
/// A binding extension for Maui apps.
/// </summary>
[ContentProperty(Name = nameof(Path))]
public class MauiBinding : MauiExtensionBase
{
/// <summary>
/// The path to the bound property.
/// </summary>
public string? Path { get; set; }

/// <summary>
/// The direction of the binding mode.
/// </summary>
public BindingMode BindingMode { get; set; } = BindingMode.Default;

/// <summary>
/// The string format of the bound property.
/// </summary>
public string? StringFormat { get; set; }

/// <summary>
/// The converter for the bound property.
/// </summary>
public object? Converter { get; set; }

/// <summary>
/// The parameter for the converter.
/// </summary>
public object? ConverterParameter { get; set; }

/// <summary>
/// The source object for the bound property.
/// </summary>
public object? Source { get; set; }

/// <inheritdoc/>
protected override void SetValue(View view, Type viewType, Type propertyType, Microsoft.Maui.Controls.BindableProperty property, string propertyName)
{
if (string.IsNullOrEmpty(Path))
Expand Down
8 changes: 8 additions & 0 deletions src/Uno.Extensions.Maui.UI/MauiColor.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,19 @@

namespace Uno.Extensions.Maui;


/// <summary>
/// This class represents a markup extension that converts a string representation of a color into a NativeMauiColor object.
/// </summary>
[MarkupExtensionReturnType(ReturnType = typeof(NativeMauiColor))]
public class MauiColor : MauiExtensionBase
{
/// <summary>
/// Gets or sets the string representation of the color value.
/// </summary>
public string Value { get; set; } = string.Empty;

/// <inheritdoc/>
protected override void SetValue(View view, Type viewType, Type propertyType, BindableProperty property, string propertyName)
{
if (!string.IsNullOrEmpty(Value) || !NativeMauiColor.TryParse(Value, out var color))
Expand Down
24 changes: 18 additions & 6 deletions src/Uno.Extensions.Maui.UI/MauiContent.cs
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,26 @@

namespace Uno.Extensions.Maui;

/// <summary>
/// ContentControl implementation that hosts a Maui view.
/// </summary>
[ContentProperty(Name = nameof(View))]
public partial class MauiContent : ContentControl
{
/// <summary>
/// The View property represents the <see cref="View"/> that will be used as content.
/// </summary>
public static readonly DependencyProperty ViewProperty =
DependencyProperty.Register(nameof(View), typeof(View), typeof(MauiContent), new PropertyMetadata(null, OnViewChanged));

private static void OnViewChanged(DependencyObject dependencyObject, DependencyPropertyChangedEventArgs args)
{
if (args.NewValue is null || args.NewValue is not View view || dependencyObject is not MauiContent embeddedView)
{
return;
}

if(embeddedView._host is not null)
if (embeddedView._host is not null)
{
view.Parent = embeddedView._host;
}
Expand All @@ -41,20 +47,26 @@ private static void OnViewChanged(DependencyObject dependencyObject, DependencyP
throw new MauiEmbeddingException(Properties.Resources.UnexpectedErrorConvertingMauiViewToNativeView, ex);
}
}

private static ILogger GetLogger() =>
MauiEmbedding.MauiContext.Services.GetRequiredService<ILogger<MauiContent>>();

private UnoHost? _host;

private readonly IMauiContext MauiContext;

/// <summary>
/// Initializes a new instance of the MauiContent class.
/// </summary>
public MauiContent()
{
MauiContext = MauiEmbedding.MauiContext;
Loading += OnLoading;
}

/// <summary>
/// Gets or sets the <see cref="View"/> that will be used as content.
/// </summary>
public View View
{
get => (View)GetValue(ViewProperty);
Expand All @@ -66,11 +78,11 @@ private void OnLoading(FrameworkElement sender, object args)
Loading -= OnLoading;
DependencyObject? treeElement = this;
var resources = new ResourceDictionary();
while(treeElement is not null)
while (treeElement is not null)
{
if(treeElement is FrameworkElement element && element.Resources.Any())
if (treeElement is FrameworkElement element && element.Resources.Any())
{
foreach((var key, var value) in element.Resources)
foreach ((var key, var value) in element.Resources)
{
if (resources.ContainsKey(key))
{
Expand Down
19 changes: 19 additions & 0 deletions src/Uno.Extensions.Maui.UI/MauiEmbedding.cs
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@

namespace Uno.Extensions.Maui;

/// <summary>
/// Embedding support for Microsoft.Maui controls in Uno Platform app hosts.
/// </summary>
public static class MauiEmbedding
{
#if !NO_PLATFORM
Expand All @@ -21,18 +24,34 @@ public static class MauiEmbedding
: throw new MauiEmbeddingInitializationException();
#endif

/// <summary>
/// Registers Maui embedding in the Uno Platform app builder.
/// </summary>
/// <returns>The updated app builder.</returns>
/// <param name="builder">The Uno app builder.</param>
/// <param name="configure">Optional lambda to configure the Maui app builder.</param>
public static IApplicationBuilder UseMauiEmbedding(this IApplicationBuilder builder, Action<MauiAppBuilder>? configure = null)
{
builder.App.UseMauiEmbedding(configure);
return builder;
}

#if NO_PLATFORM
/// <summary>
/// Not supported platform.
/// </summary>
/// <param name="app">The Uno app.</param>
/// <param name="configure">Optional lambda to configure the Maui app builder.</param>
public static void UseMauiEmbedding(this Microsoft.UI.Xaml.Application app, Action<MauiAppBuilder>? configure = null)
{
throw new PlatformNotSupportedException();
}
#else
/// <summary>
/// Registers Maui embedding with WinUI3 and WPF application builder.
/// </summary>
/// <param name="app">The Uno app.</param>
/// <param name="configure">Optional lambda to configure the Maui app builder.</param>
public static void UseMauiEmbedding(this Microsoft.UI.Xaml.Application app, Action<MauiAppBuilder>? configure = null)
{
var mauiAppBuilder = MauiApp.CreateBuilder()
Expand Down
14 changes: 14 additions & 0 deletions src/Uno.Extensions.Maui.UI/MauiEmbeddingException.cs
Original file line number Diff line number Diff line change
@@ -1,12 +1,26 @@
namespace Uno.Extensions.Maui;

/// <summary>
/// Represents an exception related to Maui embedding.
/// </summary>
public class MauiEmbeddingException : Exception
{
/// <summary>
/// Initializes a new instance of the <see cref="MauiEmbeddingException"/> class
/// with a specified error message.
/// </summary>
/// <param name="message">The message that describes the error.</param>
internal MauiEmbeddingException(string message)
: base(message)
{
}

/// <summary>
/// Initializes a new instance of the <see cref="MauiEmbeddingException"/> class
/// with a specified error message and inner exception.
/// </summary>
/// <param name="message">The message that describes the error.</param>
/// <param name="innerException">The exception that is the cause of the current exception.</param>
internal MauiEmbeddingException(string message, Exception innerException)
: base(message, innerException)
{
Expand Down
Original file line number Diff line number Diff line change
@@ -1,9 +1,18 @@
namespace Uno.Extensions.Maui;

/// <summary>
/// Represents an <see cref="MauiEmbeddingException"/> that occurs during Maui embedding initialization.
/// </summary>
public sealed class MauiEmbeddingInitializationException : MauiEmbeddingException
{
/// <summary>
/// Gets the error message for the <see cref="Exception"/>.
/// </summary>
public static string ErrorMessage => Properties.Resources.MauiEmbeddingInitializationExceptionMessage;

/// <summary>
/// Initializes a new instance of the <see cref="MauiEmbeddingInitializationException"/> class with the error message.
/// </summary>
internal MauiEmbeddingInitializationException()
: base(ErrorMessage)
{
Expand Down
31 changes: 27 additions & 4 deletions src/Uno.Extensions.Maui.UI/MauiExtensionBase.cs
Original file line number Diff line number Diff line change
@@ -1,14 +1,24 @@
using System.Reflection;
using System.Numerics;
using System.Reflection;
using Microsoft.Extensions.Logging;
using Microsoft.Maui.Controls;
using Microsoft.UI.Xaml.Documents;

namespace Uno.Extensions.Maui;

/// <summary>
/// Abstract class for extending <see cref="MarkupExtension"/> in the context of <see cref="Microsoft.Maui.Controls"/>.
/// </summary>
public abstract class MauiExtensionBase : MarkupExtension
{
private ILogger? _logger;

/// <summary>
/// Logger to log messages during runtime.
/// </summary>
protected ILogger Logger => _logger ??= GetLogger();

/// <inheritdoc/>
protected sealed override object? ProvideValue(IXamlServiceProvider serviceProvider)
{
var provideValueTarget = (IProvideValueTarget)serviceProvider.GetService(typeof(IProvideValueTarget));
Expand Down Expand Up @@ -58,16 +68,29 @@ void OnParented(object? sender, EventArgs args)

return base.ProvideValue(serviceProvider);
}

private ILogger GetLogger()
{
var factory = MauiEmbedding.MauiContext.Services.GetRequiredService<ILoggerFactory>();
var implemenatingType = GetType();
return factory.CreateLogger(implemenatingType.Name);
var implementingType = GetType();
return factory.CreateLogger(implementingType.Name);
}

/// <summary>
/// Abstract method to set the value of a <see cref="BindableProperty"/>.
/// </summary>
/// <param name="view">The view to set the property value on.</param>
/// <param name="viewType">The type of view to set the property value on.</param>
/// <param name="propertyType">The type of the property to set.</param>
/// <param name="property">The <see cref="BindableProperty"/> to set.</param>
/// <param name="propertyName">The name of the property to set.</param>
protected abstract void SetValue(View view, Type viewType, Type propertyType, BindableProperty property, string propertyName);

/// <summary>
/// Returns a default value of <paramref name="type"/>.
/// </summary>
/// <param name="type">Type of the target.</param>
/// <returns>Default value of <paramref name="type"/>.</returns>
protected object? Default(Type type) =>
type.IsValueType ? Activator.CreateInstance(type) : null;
}
14 changes: 14 additions & 0 deletions src/Uno.Extensions.Maui.UI/MauiResource.cs
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,26 @@

namespace Uno.Extensions.Maui;

/// <summary>
/// A helper class used to set the value of a view's property by its key.
/// </summary>
[ContentProperty(Name = nameof(Key))]
[MarkupExtensionReturnType(ReturnType = typeof(object))]
public class MauiResource : MauiExtensionBase
{
/// <summary>
/// The key for the resource to be retrieved and set.
/// </summary>
public string Key { get; set; } = string.Empty;

/// <summary>
/// Sets the value of the view's property by the key.
/// </summary>
/// <param name="view">The <see cref="View"/> whose property value will be set.</param>
/// <param name="viewType">The type of the view.</param>
/// <param name="propertyType">The type of the property.</param>
/// <param name="property">The property whose value will be set.</param>
/// <param name="propertyName">The name of the property.</param>
protected override void SetValue(View view, Type viewType, Type propertyType, BindableProperty property, string propertyName)
{
if (string.IsNullOrEmpty(Key))
Expand Down
7 changes: 7 additions & 0 deletions src/Uno.Extensions.Maui.UI/MauiThickness.cs
Original file line number Diff line number Diff line change
@@ -1,10 +1,17 @@
namespace Uno.Extensions.Maui;

/// <summary>
/// Provides a markup extension for creating a <see cref="Microsoft.Maui.Thickness"/> object from a string.
/// </summary>
[MarkupExtensionReturnType(ReturnType = typeof(Microsoft.Maui.Thickness))]
public class MauiThickness : MarkupExtension
{
/// <summary>
/// Gets or sets the string value to convert into a <see cref="Microsoft.Maui.Thickness"/> object.
/// </summary>
public string Value { get; set; } = string.Empty;

/// <inheritdoc />
protected override object ProvideValue()
{
if (string.IsNullOrEmpty(Value))
Expand Down

0 comments on commit 7acc6ad

Please sign in to comment.