Merge pull request #47 from RadekVyM/dev

Core 5.0.0

.gitignore

@@ -29,6 +29,7 @@ bld/
 
 # Visual Studio 2015/2017 cache/options directory
 .vs/
+.vscode/
 # Uncomment if you have tasks that create the project's static files in wwwroot
 #wwwroot/
 

docs/SimpleToolkit.Core/ContentButton.md

@@ -1,6 +1,6 @@
 # ContentButton
 
-In order to use this control, you need to call the `UseSimpleToolkit()` extension method in your `MauiProgram.cs` file:
+`ContentButton` is just a button that can hold whatever content you want. In order to use this control, you need to call the `UseSimpleToolkit()` extension method in your `MauiProgram.cs` file:
 
 ```csharp
 builder.UseSimpleToolkit();
@@ -12,29 +12,30 @@ builder.UseSimpleToolkit();
 xmlns:simpleCore="clr-namespace:SimpleToolkit.Core;assembly=SimpleToolkit.Core"
 ```
 
-`ContentButton` is just a button that can hold whatever content you want:
+## Example
+
+Let's define a `ContentButton` with an `Icon` and `Label`:
 
 ```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
+    Clicked="StarButtonClicked"
+    Background="Orange"
+    HorizontalOptions="Center"
+    StrokeShape="{RoundRectangle CornerRadius=6}">
+    <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>
 </simpleCore:ContentButton>
 ```
 
-Output:
+The button border can be modified the same way as the `Border` control. Output:
 
 <p align="center">
     <img src="../images/star_button.png" data-canonical-src="../images/star_button.png" />
@@ -45,45 +46,42 @@ Output:
 `ContentButton` provides the same visual states as .NET MAUI `Button` does:
 
 ```xml
-<simpleCore:ContentButton Clicked="StarButtonClicked">
+<simpleCore:ContentButton
+    Clicked="StarButtonClicked"
+    Background="Orange"
+    HorizontalOptions="Center"
+    StrokeShape="{RoundRectangle CornerRadius=6}">
     <VisualStateManager.VisualStateGroups>
         <VisualStateGroupList>
             <VisualStateGroup>
                 <VisualState x:Name="Normal"/>
                 <VisualState x:Name="Pressed">
                     <VisualState.Setters>
                         <Setter
-                            TargetName="border" 
                             Property="Background" 
                             Value="OrangeRed"/>
                     </VisualState.Setters>
                 </VisualState>
                 <VisualState x:Name="PointerOver">
                     <VisualState.Setters>
                         <Setter
-                            TargetName="border" 
                             Property="Background" 
                             Value="DarkOrange"/>
                     </VisualState.Setters>
                 </VisualState>
             </VisualStateGroup>
         </VisualStateGroupList>
     </VisualStateManager.VisualStateGroups>
-    <Border x:Name="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>
+    <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>
 </simpleCore:ContentButton>
 ```
 
@@ -95,7 +93,7 @@ Output:
 
 ## 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:
+Since version 5.0.0, the `ContentButton` class is inherited from the .NET MAUI `Border` control. `ContentButton` has these events and properties in addition to `Border`s events and properties:
 
 - `Clicked` - an event that fires when the button is clicked
 - `Pressed` - an event that fires when the button is pressed

docs/SimpleToolkit.Core/Icon.md

@@ -1,6 +1,6 @@
 # Icon
 
-In order to use this control, you need to call the `UseSimpleToolkit()` extension method in your `MauiProgram.cs` file:
+Thanks to the `Icon` control, you are able to display a tinted image. In order to use this control, you need to call the `UseSimpleToolkit()` extension method in your `MauiProgram.cs` file:
 
 ```csharp
 builder.UseSimpleToolkit();
@@ -12,7 +12,9 @@ builder.UseSimpleToolkit();
 xmlns:simpleCore="clr-namespace:SimpleToolkit.Core;assembly=SimpleToolkit.Core"
 ```
 
-Thanks to the `Icon` control, you are able to display a tinted image:
+## Example
+
+If no tint color is defined, black color is used:
 
 ```xml
 <simpleCore:Icon Source="star.png"/>
@@ -28,7 +30,7 @@ Output:
 
 ## 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:
+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 `IconSourceElement`. Because of that, the control supports only these image sources on Windows:
 
 - `FileImageSource`
 - `UriImageSource`

docs/SimpleToolkit.Core/Popover.md

@@ -1,18 +1,26 @@
 # Popover
 
-In order to use this control, you need to call the `UseSimpleToolkit()` extension method in your `MauiProgram.cs` file:
+`Popover` allows you to display custom popovers (flyouts) anchored to any control. In order to use this control, you need to call the `UseSimpleToolkit()` extension method in your `MauiProgram.cs` file:
 
 ```csharp
 builder.UseSimpleToolkit();
 ```
 
-`Popover` can be found in the following XAML namespace:
+`Popover` and all related classes and methods can be found in the following namespace:
+
+```csharp
+using SimpleToolkit.Core;
+```
+
+Or in the following XAML namespace:
 
 ```xml
 xmlns:simpleCore="clr-namespace:SimpleToolkit.Core;assembly=SimpleToolkit.Core"
 ```
 
-`Popover` allows you to display custom popovers (flyouts) anchored to any control:
+## Example
+
+Simple popover anchored to a button can be defined as follows:
 
 ```xml
 <Button
@@ -30,11 +38,13 @@ xmlns:simpleCore="clr-namespace:SimpleToolkit.Core;assembly=SimpleToolkit.Core"
 
                 <VerticalStackLayout Padding="12,10" Spacing="10">
                     <simpleCore:Icon
-                        Source="star.png" TintColor="White"
+                        Source="star.png"
+                        TintColor="White"
                         VerticalOptions="Center"
                         HeightRequest="25" WidthRequest="25"/>
                     <Label
-                        Text="Star this repo" TextColor="White"
+                        Text="Do you like this repo?"
+                        TextColor="White"
                         FontAttributes="Bold"
                         VerticalOptions="Center"/>
                 </VerticalStackLayout>
@@ -44,7 +54,7 @@ xmlns:simpleCore="clr-namespace:SimpleToolkit.Core;assembly=SimpleToolkit.Core"
 </Button>
 ```
 
-Code behind:
+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
 private void ButtonClicked(object sender, EventArgs e)
@@ -66,27 +76,37 @@ Output:
             <th>
                 <p align="center">iOS</p>
             </th>
+        </tr>
+        <tr>
+            <td>
+                <img src="../images/android_popover.webp" width="480"/>
+            </td>
+            <td>
+                <img src="../images/ios_popover.webp" width="480"/>
+            </td>
+        </tr>
+         <tr>
+            <th>
+                <p align="center">macOS</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"/>
+                <img src="../images/macos_popover.webp" width="480"/>
             </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"/>
+                <img src="../images/windows_popover.webp" width="480"/>
             </td>
         </tr>
     </table>
 </p>
 
-## Implementation details
+## Properties and methods
 
-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:
+The `Popover` class is inherited from the .NET MAUI `Element` class. `Popover` offers these essential 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
@@ -104,4 +124,69 @@ Popover can be attached to a view using the `AttachedPopover` attached property.
 ```csharp
 button.ShowAttachedPopover();
 button.HideAttachedPopover();
+```
+
+### `UseDefaultStyling`
+Using the `UseDefaultStyling` boolean property, we can define whether the default platform-specific styling of the popover should be used. The default value is `false`. If we set the property to `true`, following results will be achieved:
+
+<p align="center">
+    <table>
+        <tr>
+            <th>
+                <p align="center">Android</p>
+            </th>
+            <th>
+                <p align="center">iOS</p>
+            </th>
+        </tr>
+        <tr>
+            <td>
+                <img src="../images/android_popover.webp" width="480"/>
+            </td>
+            <td>
+                <img src="../images/ios_popover_default.webp" width="480"/>
+            </td>
+        </tr>
+         <tr>
+            <th>
+                <p align="center">macOS</p>
+            </th>
+            <th>
+                <p align="center">Windows</p>
+            </th>
+        </tr>
+        <tr>
+            <td>
+                <img src="../images/macos_popover.webp" width="480"/>
+            </td>
+            <td>
+                <img src="../images/windows_popover_default.webp" width="480"/>
+            </td>
+        </tr>
+    </table>
+</p>
+
+### `Alignment`
+
+On Android and Windows, popover alignment can be defined using the `Alignment` property. This property accepts a value of the `PopoverAlignment` enumeration type:
+
+- `Center` - popover is centered to its anchor
+- `Start` - popover is aligned to the left edge of its anchor
+- `End` - popover is aligned to the right edge of its anchor
+
+### `PermittedArrowDirections`
+
+On iOS, permitted arrow directions can be defined using the `PermittedArrowDirections` property. This property accepts flags of the `PopoverArrowDirection` enumeration type:
+
+- `Unknown` - the status of the arrow is currently unknown
+- `Up` - an arrow points upward
+- `Down` - an arrow points downward
+- `Left` - an arrow points toward the left
+- `Right` - an arrow points toward the right
+- `Any` - an arrow points in any direction. This is the default value
+
+We can, for example, allow the arrow to point only upward or downward:
+
+```csharp
+popover.PermittedArrowDirections = PopoverArrowDirection.Up | PopoverArrowDirection.Down;
 ```

src/Playground/Playground.Original/Playground.Original.csproj

@@ -22,6 +22,8 @@
 		<ApplicationDisplayVersion>1.0</ApplicationDisplayVersion>
 		<ApplicationVersion>1</ApplicationVersion>
 
+		<WindowsAppSdkDeploymentManagerInitialize>false</WindowsAppSdkDeploymentManagerInitialize>
+
 		<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">14.2</SupportedOSPlatformVersion>
 		<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">14.0</SupportedOSPlatformVersion>
 		<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">21.0</SupportedOSPlatformVersion>
@@ -73,7 +75,7 @@
 	<ItemGroup Condition="'$(Configuration)'!='DEBUG'">
         <PackageReference Include="SimpleToolkit.Core" Version="4.0.0" />
         <PackageReference Include="SimpleToolkit.SimpleShell.Controls" Version="3.0.0-preview1" />
-        <PackageReference Include="SimpleToolkit.SimpleShell" Version="4.0.0" />
+        <PackageReference Include="SimpleToolkit.SimpleShell" Version="4.1.0" />
 	</ItemGroup>
 
 	<ItemGroup Condition="'$(Configuration)'=='DEBUG'">
@@ -90,6 +92,12 @@
 	<ItemGroup>
 		<ProjectReference Include="..\SimpleShell\Playground.Core\Playground.Core.csproj" />
 	</ItemGroup>
+
+	<ItemGroup>
+	  <MauiXaml Update="Views\Controls\PopoverTest.xaml">
+	    <Generator>MSBuild:Compile</Generator>
+	  </MauiXaml>
+	</ItemGroup>
 
 	<!-- Build Properties must be defined within these property groups to ensure successful publishing
        to the Mac App Store. See: https://aka.ms/maui-publish-app-store#define-build-properties-in-your-project-file -->