diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/Browser.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/Browser.xml deleted file mode 100644 index 67b66f3b85d6..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/Browser.xml +++ /dev/null @@ -1,159 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Object - - - - Provides a way to display a web page inside an app. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task - - - - - - Uri to launch. - Open the browser to specified uri. - Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task - - - - - - Uri to launch. - Open the browser to specified uri. - Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task - - - - - - - Uri to launch. - How to launch the browser. - Open the browser to specified uri. - Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task - - - - - - - Uri to launch. - Launch options for the browser. - Open the browser to specified uri. - Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task - - - - - - - Uri to launch. - How to launch the browser. - Open the browser to specified uri. - Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task<System.Boolean> - - - - - - - Uri to launch. - Launch options for the browser. - Open the browser to specified uri. - Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. - - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/BrowserLaunchFlags.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/BrowserLaunchFlags.xml deleted file mode 100644 index 9c5a2421a692..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/BrowserLaunchFlags.xml +++ /dev/null @@ -1,91 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Enum - - - - System.Flags - - - - Additional flags that can be set to control how the browser opens. - - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.BrowserLaunchFlags - - 1 - - On Android to launch the new activity adjacent to the current one if available. - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.BrowserLaunchFlags - - 0 - - No additional flags. This is the default. - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.BrowserLaunchFlags - - 4 - - On iOS to launch the browser as a form sheet with system preferred browser where supported. - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.BrowserLaunchFlags - - 2 - - On iOS to launch the browser as a page sheet with system preferred browser where supported. - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/BrowserLaunchMode.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/BrowserLaunchMode.xml deleted file mode 100644 index 2de7a074c114..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/BrowserLaunchMode.xml +++ /dev/null @@ -1,52 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Enum - - - Launch type of the browser. - Recommended to use the SystemBrowser as it is the default and falls back to UriLauncher. - - - - - - - Field - - 1.0.0.0 - Microsoft.Maui.Essentials - - - Microsoft.Maui.Essentials.BrowserLaunchMode - - 1 - - Use the default external launcher to open the browser outside of the app. - - - - - - - Field - - 1.0.0.0 - Microsoft.Maui.Essentials - - - Microsoft.Maui.Essentials.BrowserLaunchMode - - 0 - - Launch the optimized system browser and stay inside of your application. (Chrome Custom Tabs and SFSafariViewController). - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/BrowserLaunchOptions.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/BrowserLaunchOptions.xml deleted file mode 100644 index 06bb55492020..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/BrowserLaunchOptions.xml +++ /dev/null @@ -1,124 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Object - - - - Optional setting to open the browser with. - These settings do not apply to all operation systems. Check documentation for more information. - - - - - - - Constructor - - Microsoft.Maui.Essentials - 1.0.0.0 - - - - Default constructor. - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.BrowserLaunchFlags - - - Additional launch flags that may or may not take effect based on the device and launch mode. - To be added. - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.BrowserLaunchMode - - - Launch type of the browser. - The launch type. - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Nullable<System.Drawing.Color> - - - Preferred color of the controls on the browser. - Gets the color for controls. - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Nullable<System.Drawing.Color> - - - Preferred color of the background toolbar. - Gets the toolbar color. - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.BrowserTitleMode - - - Preferred mode for the title display. - Gets the title display mode. - - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/BrowserTitleMode.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/BrowserTitleMode.xml deleted file mode 100644 index 6041f8b1f094..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/BrowserTitleMode.xml +++ /dev/null @@ -1,71 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Enum - - - Mode for the title. - - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.BrowserTitleMode - - 0 - - Uses the system default showing it. - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.BrowserTitleMode - - 2 - - - Hide the title. - - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.BrowserTitleMode - - 1 - - Show the title. - - - - diff --git a/src/Essentials/src/Browser/Browser.netstandard.tvos.watchos.cs b/src/Essentials/src/Browser/Browser.netstandard.tvos.watchos.cs index 819aaabdd592..33beb4b247bd 100755 --- a/src/Essentials/src/Browser/Browser.netstandard.tvos.watchos.cs +++ b/src/Essentials/src/Browser/Browser.netstandard.tvos.watchos.cs @@ -4,7 +4,6 @@ namespace Microsoft.Maui.ApplicationModel { - /// partial class BrowserImplementation : IBrowser { public Task OpenAsync(Uri uri, BrowserLaunchOptions options) => diff --git a/src/Essentials/src/Browser/Browser.shared.cs b/src/Essentials/src/Browser/Browser.shared.cs index 1e23bb7856af..8f4e09ba3268 100755 --- a/src/Essentials/src/Browser/Browser.shared.cs +++ b/src/Essentials/src/Browser/Browser.shared.cs @@ -4,34 +4,76 @@ namespace Microsoft.Maui.ApplicationModel { + /// + /// Provides a way to display a web page inside an app. + /// public interface IBrowser { + /// + /// Open the browser to specified URI. + /// + /// URI to open. + /// Launch options for the browser. + /// Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. Task OpenAsync(Uri uri, BrowserLaunchOptions options); } - /// + /// + /// Provides a way to display a web page inside an app. + /// public static class Browser { - /// + /// + /// Open the browser to specified URI. + /// + /// URI to open. + /// Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. public static Task OpenAsync(string uri) => Default.OpenAsync(uri); - /// + /// + /// Open the browser to specified URI. + /// + /// URI to open. + /// How to launch the browser. + /// Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. public static Task OpenAsync(string uri, BrowserLaunchMode launchMode) => Default.OpenAsync(uri, launchMode); - /// + /// + /// Open the browser to specified URI. + /// + /// URI to open. + /// Launch options for the browser. + /// Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. public static Task OpenAsync(string uri, BrowserLaunchOptions options) => Default.OpenAsync(uri, options); - /// + /// + /// Open the browser to specified URI. + /// + /// URI to open. + /// Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. public static Task OpenAsync(Uri uri) => Default.OpenAsync(uri); - /// + /// + /// Open the browser to specified URI. + /// + /// URI to open. + /// How to launch the browser. + /// Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. public static Task OpenAsync(Uri uri, BrowserLaunchMode launchMode) => Default.OpenAsync(uri, launchMode); - /// + /// + /// Open the browser to specified URI. + /// + /// URI to open. + /// Launch options for the browser. + /// Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. public static Task OpenAsync(Uri uri, BrowserLaunchOptions options) => Default.OpenAsync(uri, options); static IBrowser? defaultImplementation; + /// + /// Provides the default implementation for static usage of this API. + /// public static IBrowser Default => defaultImplementation ??= new BrowserImplementation(); @@ -39,20 +81,56 @@ internal static void SetDefault(IBrowser? implementation) => defaultImplementation = implementation; } + /// + /// This class contains static extension methods for use with . + /// public static class BrowserExtensions { + /// + /// Open the browser to specified URI. + /// + /// The instance to invoke this method on. + /// URI to open. + /// Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. public static Task OpenAsync(this IBrowser browser, string uri) => browser.OpenAsync(new Uri(uri), new BrowserLaunchOptions()); + /// + /// Open the browser to specified URI. + /// + /// The instance to invoke this method on. + /// URI to open. + /// How to launch the browser. + /// Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. public static Task OpenAsync(this IBrowser browser, string uri, BrowserLaunchMode launchMode) => browser.OpenAsync(new Uri(uri), new BrowserLaunchOptions { LaunchMode = launchMode }); + /// + /// Open the browser to specified URI. + /// + /// The instance to invoke this method on. + /// URI to open. + /// Launch options for the browser. + /// Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. public static Task OpenAsync(this IBrowser browser, string uri, BrowserLaunchOptions options) => browser.OpenAsync(new Uri(uri), options); + /// + /// Open the browser to specified URI. + /// + /// The instance to invoke this method on. + /// URI to open. + /// Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. public static Task OpenAsync(this IBrowser browser, Uri uri) => browser.OpenAsync(uri, new BrowserLaunchOptions()); + /// + /// Open the browser to specified URI. + /// + /// The instance to invoke this method on. + /// URI to open. + /// How to launch the browser. + /// Completed task when browser is launched, but not necessarily closed. Result indicates if launching was successful or not. public static Task OpenAsync(this IBrowser browser, Uri uri, BrowserLaunchMode launchMode) => browser.OpenAsync(uri, new BrowserLaunchOptions { LaunchMode = launchMode }); } diff --git a/src/Essentials/src/Browser/BrowserLaunchMode.shared.cs b/src/Essentials/src/Browser/BrowserLaunchMode.shared.cs index c9ca6e257d6c..62a56cc06490 100755 --- a/src/Essentials/src/Browser/BrowserLaunchMode.shared.cs +++ b/src/Essentials/src/Browser/BrowserLaunchMode.shared.cs @@ -1,12 +1,16 @@ #nullable enable namespace Microsoft.Maui.ApplicationModel { - /// + /// + /// Launch type of the browser. + /// + /// It's recommended to use the as it is the default and gracefully falls back if needed. public enum BrowserLaunchMode { - /// + /// Launch the optimized system browser and stay inside of your application. Chrome Custom Tabs on Android and SFSafariViewController on iOS. SystemPreferred = 0, - /// + + /// Use the default external launcher to open the browser outside of the app. External = 1 } } diff --git a/src/Essentials/src/Browser/BrowserLaunchOptions.shared.cs b/src/Essentials/src/Browser/BrowserLaunchOptions.shared.cs index 672d8b4e61ab..44e254fd11b3 100755 --- a/src/Essentials/src/Browser/BrowserLaunchOptions.shared.cs +++ b/src/Essentials/src/Browser/BrowserLaunchOptions.shared.cs @@ -4,38 +4,61 @@ namespace Microsoft.Maui.ApplicationModel { - /// + /// + /// Optional setting to open the browser with. + /// + /// Not all settings apply to all operating systems. Check documentation for more information. public class BrowserLaunchOptions { - /// + /// + /// Gets or sets the preferred color of the toolbar background of the in-app browser. + /// + /// This setting only applies to iOS and Android. public Color? PreferredToolbarColor { get; set; } - /// + /// + /// Gets or sets the preferred color of the controls on the in-app browser. + /// + /// This setting only applies to iOS. public Color? PreferredControlColor { get; set; } - /// + /// + /// Gets or sets how the browser should be launched. + /// + /// The default value is . public BrowserLaunchMode LaunchMode { get; set; } = BrowserLaunchMode.SystemPreferred; - /// + /// + /// Gets or sets the preferred mode for the title display. + /// + /// The default value is . This setting only applies to Android. public BrowserTitleMode TitleMode { get; set; } = BrowserTitleMode.Default; - /// + /// + /// Gets or sets additional launch flags that may or may not take effect based on the device and . + /// + /// The default value is . Not all flags work on all platforms, check the flag descriptions. public BrowserLaunchFlags Flags { get; set; } = BrowserLaunchFlags.None; internal bool HasFlag(BrowserLaunchFlags flag) => Flags.HasFlag(flag); } - /// + /// + /// Additional flags that can be set to control how the browser opens. + /// [Flags] public enum BrowserLaunchFlags { - /// + /// No additional flags. This is the default. None = 0, - /// + + /// Only applicable to Android: launches a new activity adjacent to the current activity if available. LaunchAdjacent = 1, - /// + + /// Only applicable to iOS: launches the browser as a page sheet with the system preferred browser where supported. PresentAsPageSheet = 2, - /// + + /// Only applicable to iOS: launches the browser as a form sheet with the system preferred browser where supported. PresentAsFormSheet = 4 } } diff --git a/src/Essentials/src/Browser/BrowserTitleMode.shared.cs b/src/Essentials/src/Browser/BrowserTitleMode.shared.cs index 38febc41d83a..04d322f9703e 100755 --- a/src/Essentials/src/Browser/BrowserTitleMode.shared.cs +++ b/src/Essentials/src/Browser/BrowserTitleMode.shared.cs @@ -1,14 +1,19 @@ #nullable enable namespace Microsoft.Maui.ApplicationModel { - /// + /// + /// Mode for the in-app browser title. + /// + /// These values only apply to Android. public enum BrowserTitleMode { - /// + /// Uses the system default. Default = 0, - /// + + /// Show the title. Show = 1, - /// + + /// Hide the title. Hide = 2 } }