Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add NuGet badge, make title not embedded in the text #95

Merged
merged 3 commits into from
Feb 12, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 25 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
# <img src="./The49.Maui.BottomSheet.icon.svg?raw=true" height="24" alt="The49.Maui.BottomSheet icon" /> The49.Maui.BottomSheet

[![NuGet Version](https://img.shields.io/nuget/v/The49.Maui.BottomSheet)](https://www.nuget.org/packages/The49.Maui.BottomSheet)

> **NOTE**: Coming from Gerald Versluis' video? Make sure to check the section on [what changed since the video was made](#changes-since-gerald-versluis-video)


<img src="./The49.Maui.BottomSheet.TitleLogo.svg?raw=true" height="64" />

# What is Maui.BottomSheet?

## What is Maui.BottomSheet?

Maui.BottomSheet is a .NET MAUI library used to display pages as Bottom Sheets.

Expand All @@ -12,7 +16,7 @@ Android | iOS
<img src="screenshots/android.png?raw=true" height="480" />|<img src="screenshots/ios.png?raw=true" height="480" />


# Setup
## Setup

Enable this plugin by calling `UseBottomSheet()` in your `MauiProgram.cs`

Expand All @@ -36,15 +40,15 @@ public static class MauiProgram
}
```

## XAML usage
### XAML usage

In order to make use of the plugin within XAML you can use this namespace:

```xml
xmlns:the49="https://schemas.the49.com/dotnet/2023/maui"
```

## Quick usage
### Quick usage

Simply create a `ContentView`. Replace the extended class with `BottomSheet` in code-behind and in XAML:

Expand Down Expand Up @@ -101,11 +105,11 @@ On Android, make sure your application's theme extends the Material3 theme. This

If you already have this file, just make sure the `Maui.MainTheme` style inherits the `Theme.Material3.DayNight` parent.

# API
## API

This library offers a `BottomSheet`, an extension of the `ContentView` with extra functionality

## Properties
### Properties

The following properties are available to use:

Expand All @@ -126,15 +130,15 @@ Only when the `FullscreenDetent` and/or `MediumDetent` are used those properties

\*\*\* On Android, setting a custom corner radius will prevent the radius animation when the sheet hits the top of the screen

## Detents:
### Detents:

Detents are snap point at which the sheet will stop when a drag gesture is released [See iOS definition](https://developer.apple.com/documentation/uikit/uisheetpresentationcontroller/detent).

On Android only 3 detents are supported (See implemenation section for more info).

On iOS, detents are only fully supported for iOS 16 and up. On iOS 15, medium and large detents are used instead [See iOS documentation](https://developer.apple.com/documentation/uikit/uisheetpresentationcontroller/detent).

## Available detents
### Available detents

Name | Parameter | Description |
:-------------------------|:-------------------------|:----|
Expand Down Expand Up @@ -177,11 +181,11 @@ Example:
</the49:BottomSheetPage>
```

## Custom detent
### Custom detent

You can create a custom detent by extending the default `Detent` class and implementing its `GetHeight` abstract method

## Events
### Events

The following events are available to use:

Expand All @@ -192,15 +196,15 @@ Name | EventArg | Description | Android | iOS |
`Shown` | `EventArg.Emtpy` | Called when the sheet finished animating in. | ✅ | ✅ |


# Platform specifics
## Platform specifics

On Android, the `Google.Android.Material.BottomSheet.BottomSheetBehavior` is made available under `sheet.Controller.Behavior`, to ensure the property is set, access it when the `Showing` event is fired. Learn more about it here: [BottomSheetBehavior  |  Android Developers](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetBehavior)

On iOS, the `UIKit.UISheetPresentationController` is made available under `sheet.Controller.SheetPresentationController`, to ensure the property is set, access it when the `Showing` event is fired. Learn more about it here: [UISheetPresentationController | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/uisheetpresentationcontroller)

# Common questions
## Common questions

## How can I remove the backdrop on iOS
### How can I remove the backdrop on iOS

A sheet without backdrop works on iOS only if using `MediumDetent` and `FullscreenDetent`. Using the `OnPlatform` tool replace the detent on iOS to only use those and it will work.

Expand Down Expand Up @@ -241,7 +245,7 @@ A `IsDefault` property can be used to select the detent that will be shown when
</the49:BottomSheetPage>
```

## How do I prevent the rounded corner to animate on Android?
### How do I prevent the rounded corner to animate on Android?

```cs
var sheet = new MySheet();
Expand All @@ -251,24 +255,24 @@ sheet.Showing += (s, e) =>
};
sheet.ShowAsync(Window);
```
## How can I change the detent used when showing the sheet
### How can I change the detent used when showing the sheet

You can either add `IsDefault="True"` to the detent or set `SelectedDetent` to one of your detents before calling `ShowAsync`.

## How do I change the corner radius?
### How do I change the corner radius?

Use the `CornerRadius` property.

# Implementation details
## Implementation details

## iOS
### iOS

The bottom sheet on iOS is presented using the `UIViewController`'s `PresentViewController` and configuring the sheet with [UISheetPresentationController](https://developer.apple.com/documentation/uikit/uisheetpresentationcontroller/detent).

Detents are created using the [custom](https://developer.apple.com/documentation/uikit/uisheetpresentationcontroller/detent/3976719-custom) method


## Android
### Android

The Material library's bottom sheet is used.

Expand All @@ -279,7 +283,7 @@ A backdrop is added and animated when requested
Detents are created using a combination of [expandedOffset](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetBehavior#setExpandedOffset(int)), [halfExpandedRatio](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetBehavior#setHalfExpandedRatio(float)) and [peekHeight](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetBehavior#setPeekHeight(int,%20boolean)). These are the only configurable stop points for the bottom sheets, and that is why this library only supports up to 3 detents on Android.


# Changes since Gerald Versluis' video
## Changes since Gerald Versluis' video

If you're coming from [Gerald Versluis' video](https://www.youtube.com/watch?v=JJUm58avADo), a few things have changed. Here is what you need to know:

Expand Down
25 changes: 25 additions & 0 deletions The49.Maui.BottomSheet.icon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading