Merge pull request #4 from RadekVyM/dev

1.0.0
RadekVyM · Sep 19, 2022 · 6821bff · 6821bff
2 parents 633d328 + 1fc0f7c
commit 6821bff
Show file tree

Hide file tree

Showing 49 changed files with 1,460 additions and 577 deletions.
diff --git a/README.md b/README.md
diff --git a/docs/SimpleToolkit.Core/ContentButton.md b/docs/SimpleToolkit.Core/ContentButton.md
@@ -0,0 +1,45 @@
+# ContentButton
+
+In order to use the control, you need to call the `UseSimpleToolkit()` extension method in your `MauiProgram.cs` file:
+
+```csharp
+builder.UseSimpleToolkit();
+```
+
+`ContentButton` is just a button that can hold whatever content you want:
+
+```xml
+<simpleCore:ContentButton Clicked="StarButtonClicked">
+    <Border Background="Orange">
+        <Border.StrokeShape>
+            <RoundRectangle CornerRadius="6"/>
+        </Border.StrokeShape>
+        <HorizontalStackLayout Padding="12,10" Spacing="10">
+            <simpleCore:Icon
+                Source="star.png" TintColor="White"
+                VerticalOptions="Center"
+                HeightRequest="18" WidthRequest="18"/>
+            <Label
+                Text="Star this repo" TextColor="White"
+                FontAttributes="Bold"
+                VerticalOptions="Center"/>
+        </HorizontalStackLayout>
+    </Border>
+</simpleCore:ContentButton>
+```
+
+Output:
+
+<p align="center">
+    <img src="../images/star_button.png" data-canonical-src="../images/star_button.png" />
+</p>
+
+## Implementation details
+
+The `ContentButton` class is inherited from the .NET MAUI `ContentView` control. `ContentButton` has these events and properties in addition to `ContentView`s events and properties:
+
+- `Clicked` - an event that fires when the button is clicked
+- `Pressed` - an event that fires when the button is pressed
+- `Released` - an event that fires when the button is released
+- `Command` - a command that is invoked when the button is clicked
+- `CommandParameter` - a parameter to pass to the `Command` property
diff --git a/docs/SimpleToolkit.Core/Icon.md b/docs/SimpleToolkit.Core/Icon.md
@@ -0,0 +1,36 @@
+# Icon
+
+In order to use the control, you need to call the `UseSimpleToolkit()` extension method in your `MauiProgram.cs` file:
+
+```csharp
+builder.UseSimpleToolkit();
+```
+
+Thanks to the `Icon` control, you are able to display a tinted image:
+
+```xml
+<simpleCore:Icon Source="star.png"/>
+<simpleCore:Icon Source="star.png" TintColor="Gray"/>
+<simpleCore:Icon Source="star.png" TintColor="Orange"/>
+```
+
+Output:
+
+<p align="center">
+    <img src="../images/stars.png" data-canonical-src="../images/stars.png" />
+</p>
+
+## Implementation details
+
+The `Icon` class is inherited from the .NET MAUI `Image` class, but behind the scenes it is implemented in the same way as .NET MAUI `Image` **only** on Android and iOS. WinUI implementation is based on `BitmapIcon` and `FontIcon` controls. Because of that, the control supports only these image sources on Windows:
+
+- `FileImageSource`
+- `UriImageSource`
+- `FontImageSource`
+
+These `Image` properties are **not supported** at all:
+
+- `Aspect` - the default behavior is `AspectFit`
+- `IsAnimationPlaying`
+- `IsLoading`
+- `IsOpaque`
diff --git a/docs/SimpleToolkit.Core/Popover.md b/docs/SimpleToolkit.Core/Popover.md
@@ -0,0 +1,101 @@
+# Popover
+
+In order to use the control, you need to call the `UseSimpleToolkit()` extension method in your `MauiProgram.cs` file:
+
+```csharp
+builder.UseSimpleToolkit();
+```
+
+`Popover` allows you to display custom popovers (flyouts) anchored to any control:
+
+```xml
+<Button
+    VerticalOptions="Center" HorizontalOptions="Center"
+    Clicked="ButtonClicked"
+    Text="Show popover"
+    Background="Orange">
+    <simpleCore:Popover.AttachedPopover>
+        <simpleCore:Popover>
+            <Border
+                Background="DarkOrange">
+                <Border.StrokeShape>
+                    <RoundRectangle CornerRadius="6"/>
+                </Border.StrokeShape>
+
+                <VerticalStackLayout Padding="12,10" Spacing="10">
+                    <simpleCore:Icon
+                        Source="star.png" TintColor="White"
+                        VerticalOptions="Center"
+                        HeightRequest="25" WidthRequest="25"/>
+                    <Label
+                        Text="Star this repo" TextColor="White"
+                        FontAttributes="Bold"
+                        VerticalOptions="Center"/>
+                </VerticalStackLayout>
+            </Border>
+        </simpleCore:Popover>
+    </simpleCore:Popover.AttachedPopover>
+</Button>
+```
+
+Code behind:
+
+```csharp
+private void ButtonClicked(object sender, EventArgs e)
+{
+    var button = sender as Button;
+
+    button.ShowAttachedPopover();
+}
+```
+
+Output:
+
+<p align="center">
+    <table>
+        <tr>
+            <th>
+                <p align="center">Android</p>
+            </th>
+            <th>
+                <p align="center">iOS</p>
+            </th>
+            <th>
+                <p align="center">Windows</p>
+            </th>
+        </tr>
+        <tr>
+            <td>
+                <img src="../images/android_popover.gif" data-canonical-src="../images/android_popover.gif" width="200"/>
+            </td>
+            <td>
+                <img src="../images/ios_popover.gif" data-canonical-src="../images/android_popover.gif" width="200"/>
+            </td>
+            <td>
+                <img src="../images/windows_popover.gif" data-canonical-src="../images/android_popover.gif" width="200"/>
+            </td>
+        </tr>
+    </table>
+</p>
+
+## Implementation details
+
+The `Popover` class is inherited from the .NET MAUI `Element` class. `Popover` offers these properties and methods in addition to `Element`s properties and methods:
+
+- `Content` - the popover content of type `View`
+- `Show()` - shows the popover anchored to a view you pass as a parameter
+- `Hide()` - hides the popover
+
+Use of the methods mentioned above:
+
+```csharp
+popover.Show(anchorView);
+popover.Hide();
+```
+
+Popover can be attached to a view using the `AttachedPopover` attached property. Such a popover can be displayed or hidden (dismissed) by calling the `ShowAttachedPopover()` and `HideAttachedPopover()` extension methods on the view:
+
+```csharp
+button.ShowAttachedPopover();
+button.HideAttachedPopover();
+```
diff --git a/docs/SimpleToolkit.Core/README.md b/docs/SimpleToolkit.Core/README.md
@@ -0,0 +1,28 @@
+# SimpleToolkit.Core
+
+[![SimpleToolkit.Core](https://img.shields.io/nuget/v/SimpleToolkit.Core.svg?label=SimpleToolkit.Core)](https://www.nuget.org/packages/SimpleToolkit.Core/)
+
+The *SimpleToolkit.Core* package is a set of simple .NET MAUI controls and helpers.
+
+## Controls
+
+These are all the controls this package has to offer:
+
+- [Icon](Icon.md) - control that allows you to display a tinted image
+- [ContentButton](ContentButton.md) - button that can hold whatever content you want
+- [Popover](Popover.md) - control that allows you to display custom popovers (flyouts) anchored to any control
+
+### Getting Started
+
+In order to use the controls listed above, you need to call the `UseSimpleToolkit()` extension method in your `MauiProgram.cs` file:
+
+```csharp
+builder.UseSimpleToolkit();
+```
+
+## Helpers
+
+These are all the helpers this package has to offer:
+
+- [Safe area helpers](SafeAreaHelpers.md) - helpers for managing the safe area of an application window
+- [System bars helpers](SystemBarsHelpers.md) - helpers for changing the appearance of system bars on Android
diff --git a/docs/SimpleToolkit.Core/SafeAreaHelpers.md b/docs/SimpleToolkit.Core/SafeAreaHelpers.md
@@ -0,0 +1,78 @@
+# Safe area helpers
+
+Helpers for managing the safe area of an application window.
+
+## Application content behind system bars
+
+Thanks to the `DisplayContentBehindBars()` extension method, you can force application content to be displayed behind system bars (status and navigation bars) on **Android** and **iOS**. Just call the method on a `MauiAppBuilder` instance in your `MauiProgram.cs` file:
+
+```csharp
+builder.DisplayContentBehindBars();
+```
+
+Output:
+
+<p align="center">
+    <img src="../images/pixel_behind_bars_image.png" data-canonical-src="../images/pixel_behind_bars_image.png" width="230" />
+    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+    <img src="../images/iphone_behind_bars_image.png" data-canonical-src="../images/iphone_behind_bars_image.png" width="230" />
+</p>
+
+<p align="center">
+    <em><a href="https://www.freepik.com/free-photo/sandy-beach-sunset-sea-with-colorful-clouds-orange-sunlight-vertical-frame-autumn-sunsets-early-autumn-velvet-season-idea-background-splash-screen_31598694.htm#query=maui&position=2&from_view=search">Image by ededchechine</a> on Freepik</em>
+</p>
+
+The method also sets the status bar background color to transparent and the text color to dark color on Android to match the look with iOS.
+
+> 
+
+### Implementation details
+
+A different approach is used on each platform:
+
+- **Android** - the `WindowCompat.SetDecorFitsSystemWindows()` method is called on creation of each activity that represents a window.
+- **iOS** - the `IgnoreSafeArea` property is set to `true` on each layout that is inherited from the `Layout` class. This overrides set values of this property on all layouts.
+- **Windows** - this feature has not been implemented on Windows yet.
+
+## Safe area insets
+
+Safe area insets can be obtained by subscribing to safe area changes using the `SubscribeToSafeAreaChanges()` extension method of a window:
+
+```csharp
+protected override void OnNavigatedTo(NavigatedToEventArgs args)
+{
+    base.OnNavigatedTo(args);
+
+    this.Window.SubscribeToSafeAreaChanges(OnSafeAreaChanged);
+}
+
+private void OnSafeAreaChanged(Thickness safeAreaPadding)
+{
+    this.Padding = safeAreaPadding;
+}
+```
+
+The `SubscribeToSafeAreaChanges()` method requires a method (listener) of type `Action<Thickness>` as a parameter. The passed method is called during the call of the `SubscribeToSafeAreaChanges()` method, and then every time the safe area of the window changes.
+
+Subscription of the safe area changes can be canceled using the `UnsubscribeFromSafeAreaChanges()` extension method. This method takes as a parameter the method you want to unsubscribe:
+
+```csharp
+protected override void OnNavigatedFrom(NavigatedFromEventArgs args)
+{
+    base.OnNavigatedFrom(args);
+
+    this.Window.UnsubscribeFromSafeAreaChanges(OnSafeAreaChanged);
+}
+```
+
+Output:
+
+<p align="center">
+    <img src="../images/pixel_safe_area_image.png" data-canonical-src="../images/pixel_safe_area_image.png" width="230" />
+    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+    <img src="../images/iphone_safe_area_image.png" data-canonical-src="../images/iphone_safe_area_image.png" width="230" />
+</p>
+
+<p align="center">
+    <em><a href="https://www.freepik.com/free-photo/sandy-beach-sunset-sea-with-colorful-clouds-orange-sunlight-vertical-frame-autumn-sunsets-early-autumn-velvet-season-idea-background-splash-screen_31598694.htm#query=maui&position=2&from_view=search">Image by ededchechine</a> on Freepik</em>
+</p>
diff --git a/docs/SimpleToolkit.Core/SystemBarsHelpers.md b/docs/SimpleToolkit.Core/SystemBarsHelpers.md
@@ -0,0 +1,38 @@
+# System bars helpers
+
+Helpers for changing the system bars appearance **on Android**:
+
+```csharp
+#if ANDROID
+
+this.Window.SetStatusBarAppearance(color: Colors.DarkOrange, lightElements: true);
+this.Window.SetNavigationBarAppearance(color: Colors.White, lightElements: false);
+
+#endif
+```
+
+The status bar appearance of a window can be changed using the `SetStatusBarAppearance()` extension method. The navigation bar appearance of a window can be changed using the `SetNavigationBarAppearance()` extension method. Both methods take two parameters:
+
+- `color` - new background color of the bar
+- `lightElements` - whether text and icons should be light or dark
+
+Output:
+
+<p align="center">
+    <img src="../images/pixel_system_bars.png" data-canonical-src="../images/pixel_system_bars.png" width="220" />
+</p>
+
+> This can also be done using [.NET MAUI Community Toolkit](https://github.com/CommunityToolkit/Maui) features that offer more options.
+
+## Default appearance
+
+Default appearance of the bars for each window can be changed using the `SetDefaultStatusBarAppearance()` and `SetDefaultNavigationBarAppearance()` extension methods. These methods has to be called on a `MauiAppBuilder` instance in your `MauiProgram.cs` file:
+
+```csharp
+#if ANDROID
+
+builder.SetDefaultStatusBarAppearance(color: Colors.DarkOrange, lightElements: true);
+builder.SetDefaultNavigationBarAppearance(color: Colors.White, lightElements: false);
+
+#endif
+```
diff --git a/docs/SimpleToolkit.SimpleShell.Controls/README.md b/docs/SimpleToolkit.SimpleShell.Controls/README.md
@@ -0,0 +1,19 @@
+# SimpleToolkit.SimpleShell.Controls
+
+[![SimpleToolkit.SimpleShell.Controls](https://img.shields.io/nuget/v/SimpleToolkit.SimpleShell.Controls.svg?label=SimpleToolkit.SimpleShell.Controls)](https://www.nuget.org/packages/SimpleToolkit.SimpleShell.Controls/)
+
+*SimpleToolkit.SimpleShell.Controls* is a collection of ready-to-use, navigation-related controls (not only) for `SimpleShell`.
+
+## Getting Started
+
+In order to use *SimpleToolkit.SimpleShell.Controls*, you need to call the `UseSimpleToolkit()` extension method in your `MauiProgram.cs` file:
+
+```csharp
+builder.UseSimpleToolkit();
+```
+
+<p align="center">
+    <a href="https://giphy.com/gifs/wiesemann1893-transparent-logo-wiesemann-dWa2rUaiahx1FB3jor">
+        <img width="250" src="https://media1.giphy.com/media/dWa2rUaiahx1FB3jor/giphy.gif?cid=790b7611041afeb62e8c51c2423440574e3473ff3a4cdd49&rid=giphy.gif&ct=g">
+    </a>
+</p>