diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/IScreenshotResult.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/IScreenshotResult.xml deleted file mode 100644 index 897886c5c220..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/IScreenshotResult.xml +++ /dev/null @@ -1,96 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - - To be added. - To be added. - - - - - - - Constructor - - Microsoft.Maui.Essentials - 1.0.0.0 - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Int32 - - - To be added. - To be added. - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task<System.IO.Stream> - - - - - - To be added. - To be added. - To be added. - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Int32 - - - To be added. - To be added. - To be added. - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/Screenshot.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/Screenshot.xml deleted file mode 100644 index 41c17e1532cf..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/Screenshot.xml +++ /dev/null @@ -1,56 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Object - - - - Take a screenshot depicting the current View. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task<Microsoft.Maui.Essentials.IScreenshotResult> - - - - Capture the screen. - Returns the caprured screenshot. - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - Gets a value indicating whether capturing screenshots are supported. - - - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/ScreenshotFormat.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/ScreenshotFormat.xml deleted file mode 100644 index 73ccdff852fe..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/ScreenshotFormat.xml +++ /dev/null @@ -1,52 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Enum - - - The format to read screenshot images. - - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.ScreenshotFormat - - 1 - - Read the screenshot image as a JPEG. - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.ScreenshotFormat - - 0 - - Read the screenshot image as a PNG. - - - - diff --git a/src/Essentials/src/Screenshot/Screenshot.shared.cs b/src/Essentials/src/Screenshot/Screenshot.shared.cs index 6ee85f558177..445d2bf8bc99 100644 --- a/src/Essentials/src/Screenshot/Screenshot.shared.cs +++ b/src/Essentials/src/Screenshot/Screenshot.shared.cs @@ -6,56 +6,145 @@ namespace Microsoft.Maui.Media { + /// + /// The Screenshot API lets you take a capture of the current displayed screen of the app. + /// public interface IScreenshot { + /// + /// Gets a value indicating whether capturing screenshots is supported on this device. + /// bool IsCaptureSupported { get; } + /// + /// Captures a screenshot of the current screen of the running application. + /// + /// An instance of with information about the captured screenshot. Task CaptureAsync(); } + /// + /// Provides abstractions for the platform screenshot methods when using Screenshot. + /// public interface IPlatformScreenshot : IScreenshot { #if ANDROID + /// + /// Captures a screenshot of the specified activity. + /// + /// The activity to capture. + /// An instance of with information about the captured screenshot. Task CaptureAsync(Android.App.Activity activity); + + /// + /// Captures a screenshot of the specified view. + /// + /// The view to capture. + /// An instance of with information about the captured screenshot. Task CaptureAsync(Android.Views.View view); #elif IOS || MACCATALYST + /// + /// Captures a screenshot of the specified window. + /// + /// The window to capture. + /// An instance of with information about the captured screenshot. Task CaptureAsync(UIKit.UIWindow window); + + /// + /// Captures a screenshot of the specified view. + /// + /// The view to capture. + /// An instance of with information about the captured screenshot. Task CaptureAsync(UIKit.UIView view); + + /// + /// Captures a screenshot of the specified layer. + /// + /// The layer to capture. + /// Specifies whether to include the child layers or not. + /// An instance of with information about the captured screenshot. Task CaptureAsync(CoreAnimation.CALayer layer, bool skipChildren); #elif WINDOWS + /// + /// Captures a screenshot of the specified window. + /// + /// The window to capture. + /// An instance of with information about the captured screenshot. Task CaptureAsync(UI.Xaml.Window window); + + /// + /// Captures a screenshot of the specified user-interface element. + /// + /// The user-interface element to capture. + /// An instance of with information about the captured screenshot. Task CaptureAsync(UI.Xaml.UIElement element); #elif TIZEN + + /// + /// Captures a screenshot of the specified window. + /// + /// The window to capture. + /// An instance of with information about the captured screenshot. Task CaptureAsync(Tizen.NUI.Window window); + + /// + /// Captures a screenshot of the specified view. + /// + /// The view to capture. + /// An instance of with information about the captured screenshot. Task CaptureAsync(Tizen.NUI.BaseComponents.View view); #endif } - /// + /// + /// A representation of a screenshot, as a result of a screenshot captured by the user. + /// public interface IScreenshotResult { - /// + /// + /// The width of this screenshot in pixels. + /// int Width { get; } - /// + /// + /// The height of this screenshot in pixels. + /// int Height { get; } - /// -#pragma warning disable CS1573 // Parameter has no matching param tag in the XML comment (but other parameters do) + /// + /// Opens a to the corresponding screenshot file on the filesystem. + /// + /// The image format used to read this screenshot. + /// The quality used to read this screenshot. + /// A containing the screenshot file data. Task OpenReadAsync(ScreenshotFormat format = ScreenshotFormat.Png, int quality = 100); -#pragma warning restore CS1573 // Parameter has no matching param tag in the XML comment (but other parameters do) + /// + /// + /// + /// The destination to copy the screenshot file data to. + /// The image format used to copy this screenshot. + /// The quality used to copy this screenshot. + /// A object with the current status of the asynchronous operation. Task CopyToAsync(Stream destination, ScreenshotFormat format = ScreenshotFormat.Png, int quality = 100); } - /// + /// + /// The Screenshot API lets you take a capture of the current displayed screen of the app. + /// public static partial class Screenshot { - /// + /// + /// Gets a value indicating whether capturing screenshots is supported on this device. + /// public static bool IsCaptureSupported => Default.IsCaptureSupported; - /// + /// + /// Captures a screenshot of the current screen of the running application. + /// + /// An instance of with information about the captured screenshot. + /// Thrown when is . public static Task CaptureAsync() { if (!IsCaptureSupported) @@ -66,6 +155,9 @@ public static Task CaptureAsync() static IScreenshot? defaultImplementation; + /// + /// Provides the default implementation for static usage of this API. + /// public static IScreenshot Default => defaultImplementation ??= new ScreenshotImplementation(); @@ -73,6 +165,9 @@ internal static void SetDefault(IScreenshot? implementation) => defaultImplementation = implementation; } + /// + /// This class contains static extension methods for use with . + /// public static class ScreenshotExtensions { static IPlatformScreenshot AsPlatform(this IScreenshot screenshot) @@ -84,52 +179,108 @@ static IPlatformScreenshot AsPlatform(this IScreenshot screenshot) } #if ANDROID - + /// + /// Captures a screenshot of the specified activity. + /// + /// The object this method is invoked on. + /// The activity to capture. + /// An instance of with information about the captured screenshot. public static Task CaptureAsync(this IScreenshot screenshot, Android.App.Activity activity) => screenshot.AsPlatform().CaptureAsync(activity); + /// + /// Captures a screenshot of the specified view. + /// + /// The object this method is invoked on. + /// The view to capture. + /// An instance of with information about the captured screenshot. public static Task CaptureAsync(this IScreenshot screenshot, Android.Views.View view) => screenshot.AsPlatform().CaptureAsync(view); #elif IOS || MACCATALYST - + /// + /// Captures a screenshot of the specified window. + /// + /// The object this method is invoked on. + /// The window to capture. + /// An instance of with information about the captured screenshot. public static Task CaptureAsync(this IScreenshot screenshot, UIKit.UIWindow window) => screenshot.AsPlatform().CaptureAsync(window); + /// + /// Captures a screenshot of the specified view. + /// + /// The object this method is invoked on. + /// The view to capture. + /// An instance of with information about the captured screenshot. public static Task CaptureAsync(this IScreenshot screenshot, UIKit.UIView view) => screenshot.AsPlatform().CaptureAsync(view); + /// + /// Captures a screenshot of the specified layer. + /// + /// The object this method is invoked on. + /// The layer to capture. + /// Specifies whether to include the child layers or not. + /// An instance of with information about the captured screenshot. public static Task CaptureAsync(this IScreenshot screenshot, CoreAnimation.CALayer layer, bool skipChildren) => screenshot.AsPlatform().CaptureAsync(layer, skipChildren); #elif WINDOWS - + /// + /// Captures a screenshot of the specified window. + /// + /// The object this method is invoked on. + /// The window to capture. + /// An instance of with information about the captured screenshot. public static Task CaptureAsync(this IScreenshot screenshot, UI.Xaml.Window window) => screenshot.AsPlatform().CaptureAsync(window); + /// + /// Captures a screenshot of the specified user-interface element. + /// + /// The object this method is invoked on. + /// The user-interface element to capture. + /// An instance of with information about the captured screenshot. public static Task CaptureAsync(this IScreenshot screenshot, UI.Xaml.UIElement element) => screenshot.AsPlatform().CaptureAsync(element); #elif TIZEN - + /// + /// Captures a screenshot of the specified window. + /// + /// The object this method is invoked on. + /// The window to capture. + /// An instance of with information about the captured screenshot. public static Task CaptureAsync(this IScreenshot screenshot, Tizen.NUI.Window window) => screenshot.AsPlatform().CaptureAsync(window); + /// + /// Captures a screenshot of the specified view. + /// + /// The object this method is invoked on. + /// The view to capture. + /// An instance of with information about the captured screenshot. public static Task CaptureAsync(this IScreenshot screenshot, Tizen.NUI.BaseComponents.View view) => screenshot.AsPlatform().CaptureAsync(view); - #endif } - /// + /// + /// The possible formats for reading screenshot images. + /// public enum ScreenshotFormat { - /// + /// Read the screenshot image as a PNG image. Png, - /// + + /// Read the screenshot image as a JPEG image. Jpeg } + /// + /// A representation of a screenshot, as a result of a screenshot captured by the user. + /// partial class ScreenshotResult : IScreenshotResult { public int Width { get; }