From 0af67851ed0fe82ab6e05e58101ae598076f4deb Mon Sep 17 00:00:00 2001 From: Mackinnon Buck Date: Fri, 8 Jul 2022 15:57:35 -0700 Subject: Updated API baselines, added XML docs. --- src/Components/Components/src/NavigationManager.cs | 38 ++++++++++++++++++++-- .../Components/src/PublicAPI.Unshipped.txt | 9 +++-- .../src/Routing/IHandleLocationChanging.cs | 8 +++++ .../src/Routing/InternalNavigationLock.cs | 6 ++++ .../src/Routing/LocationChangingContext.cs | 22 +++++++++++++ .../Components/src/Routing/NavigationPrompt.cs | 13 ++++++++ 6 files changed, 91 insertions(+), 5 deletions(-) (limited to 'src') diff --git a/src/Components/Components/src/NavigationManager.cs b/src/Components/Components/src/NavigationManager.cs index 0ecc7d9b03..4e48b77f8f 100644 --- a/src/Components/Components/src/NavigationManager.cs +++ b/src/Components/Components/src/NavigationManager.cs @@ -269,7 +269,14 @@ public abstract class NavigationManager } } - public async ValueTask NotifyLocationChanging(string uri, bool intercepted, bool forceLoad) + /// + /// Notifies the registered handlers of the current location change. + /// + /// The destination URI. This can be absolute, or relative to the base URI. + /// Whether this navigation was intercepted from a link. + /// Whether the navigation is attempting to bypass client-side routing. + /// A representing the completion of the operaiton. + public async ValueTask NotifyLocationChanging(string uri, bool isNavigationIntercepted, bool forceLoad) { _locationChangingCts?.Cancel(); _locationChangingCts = null; @@ -282,7 +289,7 @@ public abstract class NavigationManager _locationChangingCts = new(); var cancellationToken = _locationChangingCts.Token; - var context = new LocationChangingContext(uri, intercepted, forceLoad, cancellationToken); + var context = new LocationChangingContext(uri, isNavigationIntercepted, forceLoad, cancellationToken); var handlerCount = _locationChangingHandlers.Count; var locationChangingHandlersCopy = ArrayPool.Shared.Rent(handlerCount); _locationChangingHandlers.CopyTo(locationChangingHandlersCopy); @@ -316,11 +323,19 @@ public abstract class NavigationManager } } + /// + /// Sets whether there are active location changing handlers. + /// + /// Whether there are active location changing handlers. + /// if the change was applied successfully, otherwise . protected virtual bool SetHasLocationChangingHandlers(bool value) { return true; } + /// + /// Invokes if the existence of location changing handlers has changed. + /// protected void UpdateHasLocationChangingHandlers() { var hasLocationChangingHandlers = _locationChangingHandlers.Count != 0; @@ -333,6 +348,10 @@ public abstract class NavigationManager } } + /// + /// Adds a handler to process incoming navigation events. + /// + /// The handler to process incoming navigation events. public void AddLocationChangingHandler(IHandleLocationChanging locationChangingHandler) { AssertInitialized(); @@ -340,6 +359,11 @@ public abstract class NavigationManager UpdateHasLocationChangingHandlers(); } + /// + /// Removes a previously-added location changing handler. + /// + /// The handler to remove. + /// if the handler was removed, otherwise . public bool RemoveLocationChangingHandler(IHandleLocationChanging locationChangingHandler) { AssertInitialized(); @@ -353,9 +377,19 @@ public abstract class NavigationManager return false; } + /// + /// Enables a navigation prompt to be displayed before navigation events complete. + /// + /// The message to display in the prompt. Note that some browsers will ignore this message for external navigations. + /// If , the prompt will not display for internal page navigations. + /// A representing the completion of the operation. protected internal virtual ValueTask EnableNavigationPromptAsync(string message, bool externalNavigationsOnly) => ValueTask.CompletedTask; + /// + /// Disables the current navigation prompt. + /// + /// A representing the completion of the operation. protected internal virtual ValueTask DisableNavigationPromptAsync() => ValueTask.CompletedTask; diff --git a/src/Components/Components/src/PublicAPI.Unshipped.txt b/src/Components/Components/src/PublicAPI.Unshipped.txt index e00577c4e3..0c1b058a6f 100644 --- a/src/Components/Components/src/PublicAPI.Unshipped.txt +++ b/src/Components/Components/src/PublicAPI.Unshipped.txt @@ -1,13 +1,13 @@ #nullable enable Microsoft.AspNetCore.Components.NavigationManager.AddLocationChangingHandler(Microsoft.AspNetCore.Components.Routing.IHandleLocationChanging! locationChangingHandler) -> void -Microsoft.AspNetCore.Components.NavigationManager.NotifyLocationChanging(string! uri, bool intercepted, bool forceLoad) -> System.Threading.Tasks.ValueTask +Microsoft.AspNetCore.Components.NavigationManager.NotifyLocationChanging(string! uri, bool isNavigationIntercepted, bool forceLoad) -> System.Threading.Tasks.ValueTask Microsoft.AspNetCore.Components.NavigationManager.RemoveLocationChangingHandler(Microsoft.AspNetCore.Components.Routing.IHandleLocationChanging! locationChangingHandler) -> bool Microsoft.AspNetCore.Components.NavigationManager.UpdateHasLocationChangingHandlers() -> void Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder.AddContent(int sequence, Microsoft.AspNetCore.Components.MarkupString? markupContent) -> void Microsoft.AspNetCore.Components.Routing.IHandleLocationChanging -Microsoft.AspNetCore.Components.Routing.IHandleLocationChanging.OnLocationChanging(Microsoft.AspNetCore.Components.Routing.LocationChangingContext! context) -> System.Threading.Tasks.ValueTask +Microsoft.AspNetCore.Components.Routing.IHandleLocationChanging.OnLocationChanging(Microsoft.AspNetCore.Components.Routing.LocationChangingContext! context) -> System.Threading.Tasks.ValueTask Microsoft.AspNetCore.Components.Routing.InternalNavigationLock -Microsoft.AspNetCore.Components.Routing.InternalNavigationLock.InternalNavigationLock(Microsoft.AspNetCore.Components.NavigationManager! navigationManager) -> void +Microsoft.AspNetCore.Components.Routing.InternalNavigationLock.InternalNavigationLock() -> void Microsoft.AspNetCore.Components.Routing.InternalNavigationLock.OnLocationChanging.get -> Microsoft.AspNetCore.Components.EventCallback Microsoft.AspNetCore.Components.Routing.InternalNavigationLock.OnLocationChanging.set -> void Microsoft.AspNetCore.Components.Routing.LocationChangingContext @@ -22,6 +22,7 @@ Microsoft.AspNetCore.Components.Routing.NavigationPrompt.ExternalNavigationsOnly Microsoft.AspNetCore.Components.Routing.NavigationPrompt.ExternalNavigationsOnly.set -> void Microsoft.AspNetCore.Components.Routing.NavigationPrompt.Message.get -> string! Microsoft.AspNetCore.Components.Routing.NavigationPrompt.Message.set -> void +Microsoft.AspNetCore.Components.Routing.NavigationPrompt.NavigationPrompt() -> void static Microsoft.AspNetCore.Components.CompilerServices.RuntimeHelpers.CreateInferredEventCallback(object! receiver, Microsoft.AspNetCore.Components.EventCallback callback, T value) -> Microsoft.AspNetCore.Components.EventCallback static Microsoft.AspNetCore.Components.CompilerServices.RuntimeHelpers.InvokeAsynchronousDelegate(System.Action! callback) -> System.Threading.Tasks.Task! static Microsoft.AspNetCore.Components.CompilerServices.RuntimeHelpers.InvokeAsynchronousDelegate(System.Func! callback) -> System.Threading.Tasks.Task! @@ -58,4 +59,6 @@ static Microsoft.AspNetCore.Components.EventCallbackFactoryBinderExtensions.Crea static Microsoft.AspNetCore.Components.EventCallbackFactoryBinderExtensions.CreateBinder(this Microsoft.AspNetCore.Components.EventCallbackFactory! factory, object! receiver, Microsoft.AspNetCore.Components.EventCallback setter, short? existingValue, System.Globalization.CultureInfo? culture = null) -> Microsoft.AspNetCore.Components.EventCallback static Microsoft.AspNetCore.Components.EventCallbackFactoryBinderExtensions.CreateBinder(this Microsoft.AspNetCore.Components.EventCallbackFactory! factory, object! receiver, Microsoft.AspNetCore.Components.EventCallback setter, string! existingValue, System.Globalization.CultureInfo? culture = null) -> Microsoft.AspNetCore.Components.EventCallback static Microsoft.AspNetCore.Components.EventCallbackFactoryBinderExtensions.CreateBinder(this Microsoft.AspNetCore.Components.EventCallbackFactory! factory, object! receiver, Microsoft.AspNetCore.Components.EventCallback setter, T existingValue, System.Globalization.CultureInfo? culture = null) -> Microsoft.AspNetCore.Components.EventCallback +virtual Microsoft.AspNetCore.Components.NavigationManager.DisableNavigationPromptAsync() -> System.Threading.Tasks.ValueTask +virtual Microsoft.AspNetCore.Components.NavigationManager.EnableNavigationPromptAsync(string! message, bool externalNavigationsOnly) -> System.Threading.Tasks.ValueTask virtual Microsoft.AspNetCore.Components.NavigationManager.SetHasLocationChangingHandlers(bool value) -> bool diff --git a/src/Components/Components/src/Routing/IHandleLocationChanging.cs b/src/Components/Components/src/Routing/IHandleLocationChanging.cs index 7a30d27800..cd0d45678a 100644 --- a/src/Components/Components/src/Routing/IHandleLocationChanging.cs +++ b/src/Components/Components/src/Routing/IHandleLocationChanging.cs @@ -3,7 +3,15 @@ namespace Microsoft.AspNetCore.Components.Routing; +/// +/// Used to intercept changes to the browser's location. +/// public interface IHandleLocationChanging { + /// + /// Invoked before the browser's location changes. + /// + /// The context for the navigation event. + /// A representing the completion of the operation. ValueTask OnLocationChanging(LocationChangingContext context); } diff --git a/src/Components/Components/src/Routing/InternalNavigationLock.cs b/src/Components/Components/src/Routing/InternalNavigationLock.cs index eb89c54794..bd1925ad91 100644 --- a/src/Components/Components/src/Routing/InternalNavigationLock.cs +++ b/src/Components/Components/src/Routing/InternalNavigationLock.cs @@ -3,6 +3,9 @@ namespace Microsoft.AspNetCore.Components.Routing; +/// +/// A component that can be used to intercept internal navigation events. +/// public class InternalNavigationLock : IComponent, IHandleLocationChanging, IDisposable { private bool _isInitialized; @@ -10,6 +13,9 @@ public class InternalNavigationLock : IComponent, IHandleLocationChanging, IDisp [Inject] private NavigationManager NavigationManager { get; set; } = default!; + /// + /// A callback to be invoked when an internal navigation event occurs. + /// [Parameter] [EditorRequired] public EventCallback OnLocationChanging { get; set; } diff --git a/src/Components/Components/src/Routing/LocationChangingContext.cs b/src/Components/Components/src/Routing/LocationChangingContext.cs index 1196827329..d030d1545d 100644 --- a/src/Components/Components/src/Routing/LocationChangingContext.cs +++ b/src/Components/Components/src/Routing/LocationChangingContext.cs @@ -3,6 +3,9 @@ namespace Microsoft.AspNetCore.Components.Routing; +/// +/// Contains context for a change to the browser's current location. +/// public class LocationChangingContext { internal LocationChangingContext(string location, bool isNavigationIntercepted, bool forceLoad, CancellationToken cancellationToken) @@ -13,16 +16,35 @@ public class LocationChangingContext CancellationToken = cancellationToken; } + /// + /// Gets the URI being navigated to. + /// public string Location { get; } + /// + /// Gets whether this navigation was intercepted from a link. + /// public bool IsNavigationIntercepted { get; } + /// + /// Gets whether the navigation is attempting to bypass client-side routing. + /// public bool ForceLoad { get; } + /// + /// Gets a that can be used to determine if this navigation gets canceled + /// by a successive navigation. + /// public CancellationToken CancellationToken { get; } + /// + /// Gets whether this navigation has been canceled. + /// public bool IsCanceled { get; private set; } + /// + /// Cancels this navigation. + /// public void Cancel() { IsCanceled = true; diff --git a/src/Components/Components/src/Routing/NavigationPrompt.cs b/src/Components/Components/src/Routing/NavigationPrompt.cs index c9641110c4..4eb82a7307 100644 --- a/src/Components/Components/src/Routing/NavigationPrompt.cs +++ b/src/Components/Components/src/Routing/NavigationPrompt.cs @@ -3,15 +3,28 @@ namespace Microsoft.AspNetCore.Components.Routing; +/// +/// A component that displays a browser prompt when the user navigates away from the page. +/// public class NavigationPrompt : IComponent, IAsyncDisposable { [Inject] private NavigationManager NavigationManager { get; set; } = default!; + /// + /// Gets or sets message to be displayed when the user navigates away from the page. + /// + /// + /// Some browsers will not display this message for external navigations. + /// For more info, see . + /// [Parameter] [EditorRequired] public string Message { get; set; } = default!; + /// + /// Gets or sets whether the prompt will only display for external navigations. + /// [Parameter] public bool ExternalNavigationsOnly { get; set; } -- cgit v1.2.3