diff --git a/README.md b/README.md index df5a8f94d..6c26dfa31 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,87 @@ The toolkit is available via NuGet, and should be installed into all your projec Now all you need to do is use it! -For example, to use the `AvatarView` you first include the toolkit namespace: +## Documentation + +### Toast + +There are 2 different ways to use Toast. +1. On your Page call the method: +```csharp +await MyPage.DisplayToastAsync(message, duration); +``` +where `message` is your text, and duration is optional parameter. Default duration = 3000; + +2. For advanced settings: +```csharp + var messageOptions = new MessageOptions + { + Foreground = Color.Black, + FontSize = 14, + FontFamily = "Arial", + Message = "My text" + }; + var options = new ToastOptions + { + MessageOptions = messageOptions, + Duration = 3000, + BackgroundColor = Color.Default, + IsRtl = false, + }; + await this.DisplayToastAsync(options); +``` + +### Snackbar + +Snackbar has API which is similar to the Toast. +1. On your Page call the method: +```csharp +var result = await MyPage.DisplaySnackbarAsync(message, actionButtonText, action, duration); +``` +where `message` is your text, `actionButtonText` is the text for the button, `action` is a `Func` and duration is optional parameter. Default duration = 3000; + +2. For advanced settings: +```csharp + var messageOptions = new MessageOptions + { + Foreground = Color.Black, + FontSize = 14, + FontFamily = "Arial", + Message = "My text" + }; + var actionOptions = new List + { + new SnackBarActionOptions + { + ForegroundColor = Color.Black, + BackgroundColor = Color.White, + FontSize = 14, + FontFamily = "Arial", + Text = "My text", + Action = () => // null by default + { + Debug.WriteLine("1"); + return Task.CompletedTask; + } + } + }; + var options = new SnackbarOptions + { + MessageOptions = messageOptions, + Duration = 3000, + BackgroundColor = Color.Default, + IsRtl = false, + Actions = actionOptions + }; + var result = await this.DisplayToastAsync(options); +``` +The result is `Boolean`. True - if snackbar is closed by user. False - if snackbar is closed by timeout. + + + +### AvatarView + +You first include the toolkit namespace: ```xaml xmlns:xct="http://xamarin.com/schemas/2020/toolkit" diff --git a/XamarinCommunityToolkit.UnitTests/Views/SnackBar_Tests.cs b/XamarinCommunityToolkit.UnitTests/Views/SnackBar_Tests.cs index 2f953f101..b9901f0e5 100644 --- a/XamarinCommunityToolkit.UnitTests/Views/SnackBar_Tests.cs +++ b/XamarinCommunityToolkit.UnitTests/Views/SnackBar_Tests.cs @@ -36,7 +36,7 @@ public async void PageExtension_DisplayToastAsync_PlatformNotSupportedException( public async void PageExtension_DisplayToastAsyncWithOptions_PlatformNotSupportedException() { var page = new ContentPage(); - await Assert.ThrowsAsync(() => page.DisplayToastAsync(Arg.Any())); + await Assert.ThrowsAsync(() => page.DisplayToastAsync(Arg.Any())); } #endif } diff --git a/XamarinCommunityToolkit/Extensions/PageExtension.shared.cs b/XamarinCommunityToolkit/Extensions/PageExtension.shared.cs index cfab88d8f..f4225e156 100644 --- a/XamarinCommunityToolkit/Extensions/PageExtension.shared.cs +++ b/XamarinCommunityToolkit/Extensions/PageExtension.shared.cs @@ -10,33 +10,40 @@ namespace Xamarin.CommunityToolkit.Extensions { public static class PageExtension { - public static Task DisplayToastAsync(this Page page, string message, int duration = 3000) + public static Task DisplayToastAsync(this Page page, string message, int durationMilliseconds = 3000) { var messageOptions = new MessageOptions { Message = message }; - var args = new SnackBarOptions(messageOptions, - duration, - Color.Default, + var args = new SnackBarOptions + { + MessageOptions = messageOptions, + Duration = TimeSpan.FromMilliseconds(durationMilliseconds), #if NETSTANDARD1_0 - false, + IsRtl = false, #else - CultureInfo.CurrentCulture.TextInfo.IsRightToLeft, + IsRtl = CultureInfo.CurrentCulture.TextInfo.IsRightToLeft, #endif - new List()); + }; var snackBar = new SnackBar(); snackBar.Show(page, args); return args.Result.Task; } - public static Task DisplayToastAsync(this Page page, ActionOptions actionOptions) + public static Task DisplayToastAsync(this Page page, ToastOptions toastOptions) { var snackBar = new SnackBar(); - var arguments = actionOptions ?? new ActionOptions(); - var options = new SnackBarOptions(arguments.MessageOptions, arguments.Duration, arguments.BackgroundColor, arguments.IsRtl, null); + var arguments = toastOptions ?? new ToastOptions(); + var options = new SnackBarOptions + { + MessageOptions = arguments.MessageOptions, + Duration = arguments.Duration, + BackgroundColor = arguments.BackgroundColor, + IsRtl = arguments.IsRtl + }; snackBar.Show(page, options); return options.Result.Task; } - public static Task DisplaySnackBarAsync(this Page page, string message, string actionButtonText, Func action, int duration = 3000) + public static Task DisplaySnackBarAsync(this Page page, string message, string actionButtonText, Func action, int durationMilliseconds = 3000) { var messageOptions = new MessageOptions { Message = message }; var actionOptions = new List @@ -46,18 +53,20 @@ public static Task DisplaySnackBarAsync(this Page page, string message, st Text = actionButtonText, Action = action } }; - var args = new SnackBarOptions(messageOptions, - duration, - Color.Default, + var options = new SnackBarOptions + { + MessageOptions = messageOptions, + Duration = TimeSpan.FromMilliseconds(durationMilliseconds), + Actions = actionOptions, #if NETSTANDARD1_0 - false, + IsRtl = false, #else - CultureInfo.CurrentCulture.TextInfo.IsRightToLeft, + IsRtl = CultureInfo.CurrentCulture.TextInfo.IsRightToLeft, #endif - actionOptions); + }; var snackBar = new SnackBar(); - snackBar.Show(page, args); - return args.Result.Task; + snackBar.Show(page, options); + return options.Result.Task; } public static Task DisplaySnackBarAsync(this Page page, SnackBarOptions snackBarOptions) diff --git a/XamarinCommunityToolkit/Views/SnackBar/Options/ActionOptions.shared.cs b/XamarinCommunityToolkit/Views/SnackBar/Options/ActionOptions.shared.cs deleted file mode 100644 index 601335009..000000000 --- a/XamarinCommunityToolkit/Views/SnackBar/Options/ActionOptions.shared.cs +++ /dev/null @@ -1,56 +0,0 @@ -using System.Threading.Tasks; -using Xamarin.Forms; - -namespace Xamarin.CommunityToolkit.UI.Views.Options -{ - /// - /// Use for any actions: toasts, SnackBars etc. - /// - public class ActionOptions - { - public ActionOptions() - { - MessageOptions = new MessageOptions(); - Duration = 3000; - BackgroundColor = Color.Default; - IsRtl = false; - Result = new TaskCompletionSource(false); - } - - public ActionOptions(MessageOptions messageOptions, int duration, Color backgroundColor, bool isRtl) - { - MessageOptions = messageOptions; - Duration = duration; - BackgroundColor = backgroundColor; - IsRtl = isRtl; - Result = new TaskCompletionSource(false); - } - - /// - /// Gets message options: Message, color, font - /// - public MessageOptions MessageOptions { get; } - - /// - /// Gets background color. - /// - public Color BackgroundColor { get; } - - /// - /// Is Right to left - /// - public bool IsRtl { get; } - - /// - /// Result is true if ActionButton is clicked. - /// - public TaskCompletionSource Result { get; } - - /// - /// Gets the duration for the SnackBar. - /// - public int Duration { get; } - - public void SetResult(bool result) => Result.TrySetResult(result); - } -} \ No newline at end of file diff --git a/XamarinCommunityToolkit/Views/SnackBar/Options/MessageOptions.shared.cs b/XamarinCommunityToolkit/Views/SnackBar/Options/MessageOptions.shared.cs index cb63f5e97..5906da516 100644 --- a/XamarinCommunityToolkit/Views/SnackBar/Options/MessageOptions.shared.cs +++ b/XamarinCommunityToolkit/Views/SnackBar/Options/MessageOptions.shared.cs @@ -7,21 +7,29 @@ public class MessageOptions /// /// Gets or sets the message for the SnackBar. /// - public string Message { get; set; } + public string Message { get; set; } = DefaultMessage; + + public static string DefaultMessage { get; set; } /// /// Gets or sets the font size for the SnackBar message. /// - public double FontSize { get; set; } = 14; + public double FontSize { get; set; } = DefaultFontSize; + + public static double DefaultFontSize { get; set; } = 14; /// /// Gets or sets the font family for the SnackBar message. /// - public string FontFamily { get; set; } = "Arial"; + public string FontFamily { get; set; } = DefaultFontFamily; + + public static string DefaultFontFamily { get; set; } = "Arial"; /// /// Gets or sets the font color for the SnackBar message. /// - public Color Foreground { get; set; } = Color.Black; + public Color Foreground { get; set; } = DefaultForeground; + + public static Color DefaultForeground { get; set; } = Color.Black; } } \ No newline at end of file diff --git a/XamarinCommunityToolkit/Views/SnackBar/Options/SnackBarActionOptions.shared.cs b/XamarinCommunityToolkit/Views/SnackBar/Options/SnackBarActionOptions.shared.cs index 765252c18..d4eca2da0 100644 --- a/XamarinCommunityToolkit/Views/SnackBar/Options/SnackBarActionOptions.shared.cs +++ b/XamarinCommunityToolkit/Views/SnackBar/Options/SnackBarActionOptions.shared.cs @@ -9,31 +9,43 @@ public class SnackBarActionOptions /// /// Gets or sets the action for the SnackBar action button. /// - public Func Action { get; set; } + public Func Action { get; set; } = DefaultAction; + + public static Func DefaultAction { get; set; } = null; /// /// Gets or sets the text for the SnackBar action button. /// - public string Text { get; set; } + public string Text { get; set; } = DefaultText; + + public static string DefaultText { get; set; } /// /// Gets or sets the font size for the SnackBar action button. /// - public double FontSize { get; set; } = 14; + public double FontSize { get; set; } = DefaultFontSize; + + public static double DefaultFontSize { get; set; } = 14; /// /// Gets or sets the font family for the SnackBar action button. /// - public string FontFamily { get; set; } = "Arial"; + public string FontFamily { get; set; } = DefaultFontFamily; + + public static string DefaultFontFamily { get; set; } = "Arial"; /// /// Gets or sets the background color for the SnackBar action button. /// - public Color BackgroundColor { get; set; } = Color.White; + public Color BackgroundColor { get; set; } = DefaultBackgroundColor; + + public static Color DefaultBackgroundColor { get; set; } = Color.White; /// /// Gets or sets the font color for the SnackBar action button. /// - public Color ForegroundColor { get; set; } = Color.Black; + public Color ForegroundColor { get; set; } = DefaultForegroundColor; + + public static Color DefaultForegroundColor { get; set; } = Color.Black; } } \ No newline at end of file diff --git a/XamarinCommunityToolkit/Views/SnackBar/Options/SnackBarOptions.shared.cs b/XamarinCommunityToolkit/Views/SnackBar/Options/SnackBarOptions.shared.cs index f2fdcbac7..b792d1060 100644 --- a/XamarinCommunityToolkit/Views/SnackBar/Options/SnackBarOptions.shared.cs +++ b/XamarinCommunityToolkit/Views/SnackBar/Options/SnackBarOptions.shared.cs @@ -4,17 +4,13 @@ namespace Xamarin.CommunityToolkit.UI.Views.Options { - public class SnackBarOptions : ActionOptions + public class SnackBarOptions : ToastOptions { - public SnackBarOptions(MessageOptions message, int duration, Color backgroundColor, bool isRtl, IEnumerable actions) - : base(message, duration, backgroundColor, isRtl) => - Actions = actions ?? Enumerable.Empty(); - - public SnackBarOptions() => Actions = Enumerable.Empty(); - /// - /// Gets the text for the action buttons + /// Action options /// - public IEnumerable Actions { get; } + public IEnumerable Actions { get; set; } = DefaultActions; + + public static IEnumerable DefaultActions { get; set; } = Enumerable.Empty(); } } \ No newline at end of file diff --git a/XamarinCommunityToolkit/Views/SnackBar/Options/ToastOptions.shared.cs b/XamarinCommunityToolkit/Views/SnackBar/Options/ToastOptions.shared.cs new file mode 100644 index 000000000..2ecafb626 --- /dev/null +++ b/XamarinCommunityToolkit/Views/SnackBar/Options/ToastOptions.shared.cs @@ -0,0 +1,49 @@ +using System; +using System.Threading.Tasks; +using Xamarin.Forms; + +namespace Xamarin.CommunityToolkit.UI.Views.Options +{ + /// + /// Toast options + /// + public class ToastOptions + { + public ToastOptions() => Result = new TaskCompletionSource(false); + + /// + /// Message options: Message, color, font + /// + public MessageOptions MessageOptions { get; set; } = DefaultMessageOptions; + + public static MessageOptions DefaultMessageOptions { get; set; } = new MessageOptions(); + + /// + /// Background color. + /// + public Color BackgroundColor { get; set; } = DefaultBackgroundColor; + + public static Color DefaultBackgroundColor { get; set; } = Color.Default; + + /// + /// Is Right to left + /// + public bool IsRtl { get; set; } = DefaultIsRtl; + + public static bool DefaultIsRtl { get; set; } = false; + + /// + /// The duration for the SnackBar. + /// + public TimeSpan Duration { get; set; } = DefaultDuration; + + public static TimeSpan DefaultDuration { get; set; } = TimeSpan.FromMilliseconds(3000); + + /// + /// Result is true if ActionButton is clicked. + /// + public TaskCompletionSource Result { get; } + + public void SetResult(bool result) => Result.TrySetResult(result); + } +} \ No newline at end of file diff --git a/XamarinCommunityToolkit/Views/SnackBar/SnackBar.android.cs b/XamarinCommunityToolkit/Views/SnackBar/SnackBar.android.cs index de16e9703..b6f23d8cb 100644 --- a/XamarinCommunityToolkit/Views/SnackBar/SnackBar.android.cs +++ b/XamarinCommunityToolkit/Views/SnackBar/SnackBar.android.cs @@ -16,7 +16,7 @@ class SnackBar internal void Show(Page sender, SnackBarOptions arguments) { var view = Platform.GetRenderer(sender).View; - var snackBar = AndroidSnackBar.Make(view, arguments.MessageOptions.Message, arguments.Duration); + var snackBar = AndroidSnackBar.Make(view, arguments.MessageOptions.Message, (int)arguments.Duration.TotalMilliseconds); var snackBarView = snackBar.View; snackBarView.SetBackgroundColor(arguments.BackgroundColor.ToAndroid()); diff --git a/XamarinCommunityToolkit/Views/SnackBar/SnackBar.gtk.cs b/XamarinCommunityToolkit/Views/SnackBar/SnackBar.gtk.cs index 25e50307b..af64daefd 100644 --- a/XamarinCommunityToolkit/Views/SnackBar/SnackBar.gtk.cs +++ b/XamarinCommunityToolkit/Views/SnackBar/SnackBar.gtk.cs @@ -17,7 +17,7 @@ public void Show(Page page, SnackBarOptions arguments) var mainWindow = (Platform.GetRenderer(page).Container.Child as Forms.Platform.GTK.Controls.Page)?.Children[0] as VBox; var snackBarLayout = GetSnackBarLayout(mainWindow, arguments); AddSnackBarContainer(mainWindow, snackBarLayout); - snackBarTimer = new Timer(arguments.Duration); + snackBarTimer = new Timer(arguments.Duration.TotalMilliseconds); snackBarTimer.Elapsed += (sender, e) => { mainWindow.Remove(snackBarLayout); diff --git a/XamarinCommunityToolkit/Views/SnackBar/SnackBar.ios.macos.cs b/XamarinCommunityToolkit/Views/SnackBar/SnackBar.ios.macos.cs index 1bcd9a4ff..a8b142e40 100644 --- a/XamarinCommunityToolkit/Views/SnackBar/SnackBar.ios.macos.cs +++ b/XamarinCommunityToolkit/Views/SnackBar/SnackBar.ios.macos.cs @@ -21,7 +21,7 @@ internal void Show(Page sender, SnackBarOptions arguments) var snackBar = MacOSSnackBar.MakeSnackBar(arguments.MessageOptions.Message) #endif - .SetDuration(arguments.Duration) + .SetDuration(arguments.Duration.TotalMilliseconds) .SetTimeoutAction(() => { arguments.SetResult(false); diff --git a/XamarinCommunityToolkit/Views/SnackBar/SnackBar.tizen.cs b/XamarinCommunityToolkit/Views/SnackBar/SnackBar.tizen.cs index dc5bfb980..8c1161cd6 100644 --- a/XamarinCommunityToolkit/Views/SnackBar/SnackBar.tizen.cs +++ b/XamarinCommunityToolkit/Views/SnackBar/SnackBar.tizen.cs @@ -13,7 +13,7 @@ internal void Show(Forms.Page sender, SnackBarOptions arguments) Forms.Platform.Tizen.Native.Dialog.CreateDialog(Forms.Forms.NativeParent, arguments.Actions.Any()); - snackBarDialog.Timeout = TimeSpan.FromMilliseconds(arguments.Duration).TotalSeconds; + snackBarDialog.Timeout = arguments.Duration.TotalSeconds; var message = arguments.MessageOptions.Message.Replace("&", "&").Replace("<", "<").Replace(">", ">") .Replace(Environment.NewLine, "
"); diff --git a/XamarinCommunityToolkit/Views/SnackBar/SnackBar.uwp.cs b/XamarinCommunityToolkit/Views/SnackBar/SnackBar.uwp.cs index 6f67b17ac..7251957c8 100644 --- a/XamarinCommunityToolkit/Views/SnackBar/SnackBar.uwp.cs +++ b/XamarinCommunityToolkit/Views/SnackBar/SnackBar.uwp.cs @@ -41,7 +41,7 @@ internal void Show(Forms.Page page, SnackBarOptions arguments) var pageControl = Platform.GetRenderer(page).ContainerElement.Parent; var grid = FindVisualChildByName(pageControl, "BottomCommandBarArea").Parent as Grid; var snackBarRow = new RowDefinition() { Height = GridLength.Auto }; - snackBarTimer = new DispatcherTimer { Interval = TimeSpan.FromMilliseconds(arguments.Duration) }; + snackBarTimer = new DispatcherTimer { Interval = arguments.Duration }; snackBarTimer.Tick += (sender, e) => { grid.Children.Remove(snackBarLayout); diff --git a/XamarinCommunityToolkit/Views/SnackBar/SnackBar.wpf.cs b/XamarinCommunityToolkit/Views/SnackBar/SnackBar.wpf.cs index 00ef758f4..464dc6659 100644 --- a/XamarinCommunityToolkit/Views/SnackBar/SnackBar.wpf.cs +++ b/XamarinCommunityToolkit/Views/SnackBar/SnackBar.wpf.cs @@ -16,7 +16,7 @@ internal void Show(Page page, SnackBarOptions arguments) var formsAppBar = System.Windows.Application.Current.MainWindow.FindChild("PART_BottomAppBar"); var currentContent = formsAppBar.Content; var snackBar = new SnackBarLayout(arguments); - snackBarTimer = new Timer { Interval = arguments.Duration }; + snackBarTimer = new Timer { Interval = (int)arguments.Duration.TotalMilliseconds }; snackBarTimer.Tick += (sender, e) => { formsAppBar.Content = currentContent; diff --git a/XamarinCommunityToolkitSample.Tizen/Xamarin.CommunityToolkit.Sample.Tizen.csproj b/XamarinCommunityToolkitSample.Tizen/Xamarin.CommunityToolkit.Sample.Tizen.csproj index 333ee63c3..8c60ba8bd 100644 --- a/XamarinCommunityToolkitSample.Tizen/Xamarin.CommunityToolkit.Sample.Tizen.csproj +++ b/XamarinCommunityToolkitSample.Tizen/Xamarin.CommunityToolkit.Sample.Tizen.csproj @@ -1,4 +1,4 @@ - + Exe diff --git a/XamarinCommunityToolkitSample/Pages/Views/SnackBarPage.xaml.cs b/XamarinCommunityToolkitSample/Pages/Views/SnackBarPage.xaml.cs index 794a73b91..a46c730a2 100644 --- a/XamarinCommunityToolkitSample/Pages/Views/SnackBarPage.xaml.cs +++ b/XamarinCommunityToolkitSample/Pages/Views/SnackBarPage.xaml.cs @@ -6,6 +6,7 @@ using Xamarin.CommunityToolkit.Extensions; using Xamarin.CommunityToolkit.UI.Views.Options; using Xamarin.Forms; +using System.Globalization; namespace Xamarin.CommunityToolkit.Sample.Pages.Views { @@ -25,8 +26,8 @@ async void DisplaySnackBarClicked(object sender, EventArgs args) async void DisplayToastClicked(object sender, EventArgs args) { - var result = await this.DisplayToastAsync(GenerateLongText(5)); - StatusText.Text = result ? "SnackBar is closed by user" : "SnackBar is closed by timeout"; + await this.DisplayToastAsync(GenerateLongText(5)); + StatusText.Text = "Toast is closed by timeout"; } async void DisplaySnackBarAdvancedClicked(object sender, EventArgs args) @@ -68,14 +69,21 @@ async void DisplaySnackBarAdvancedClicked(object sender, EventArgs args) } } }; - var options = new SnackBarOptions(messageOptions, 5000, Color.Coral, true, actionOptions); + var options = new SnackBarOptions + { + MessageOptions = messageOptions, + Duration = TimeSpan.FromMilliseconds(5000), + BackgroundColor = Color.Coral, + IsRtl = CultureInfo.CurrentCulture.TextInfo.IsRightToLeft, + Actions = actionOptions + }; var result = await this.DisplaySnackBarAsync(options); StatusText.Text = result ? "SnackBar is closed by user" : "SnackBar is closed by timeout"; } string GenerateLongText(int stringDuplicationTimes) { - const string message = "It is a very long message to test multiple strings. A B C D E F G H I I J K LO P Q R S T U V W X Y Z"; + const string message = "It is a very long message to test multiple strings. A B C D E F G H I I J K L M N O P Q R S T U V W X Y Z"; var result = new StringBuilder(); for (var i = 0; i < stringDuplicationTimes; i++) {