Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/the49ltd/The49.Maui.ContextMenu
.NET MAUI library for Android and iOS used to open a native context menu on long press
https://github.com/the49ltd/The49.Maui.ContextMenu
Last synced: about 2 months ago
JSON representation
.NET MAUI library for Android and iOS used to open a native context menu on long press
- Host: GitHub
- URL: https://github.com/the49ltd/The49.Maui.ContextMenu
- Owner: the49ltd
- License: mit
- Created: 2023-04-27T10:45:41.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-04-27T10:46:18.000Z (over 1 year ago)
- Last Synced: 2024-07-28T13:19:53.019Z (about 2 months ago)
- Language: C#
- Homepage:
- Size: 771 KB
- Stars: 56
- Watchers: 3
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-dotnet-maui - The49.Maui.ContextMenu - square)](https://github.com/the49code/The49.Maui.ContextMenu/stargazers)|[](https://github.com/the49code/The49.Maui.ContextMenu/commits) (UI)
README
## What is Maui.ContextMenu?
Maui.ContextMenu is a .NET MAUI library for Android and iOS used to open a native context menu on long press.
Android | iOS
:-------------------------:|:-------------------------:
|
## Getting Started
Enable this plugin by calling `UseContextMenu()` in your `MauiProgram.cs`
```csharp
using The49.Maui.ContextMenu;
public static class MauiProgram
{
public static MauiApp CreateMauiApp()
{
var builder = MauiApp.CreateBuilder();
// Initialise the plugin
builder.UseMauiApp().UseContextMenu();
// the rest of your logic...
}
}
```
### 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"
```
Then you can add a context menu to any control:
```xml
```
### Defining the menu
The available elements for the menu are:
- ``: The top level menu, can be nested for submenus
- ``: An action users can select from the menu
- ``: A group of `Action`s or `Menu`s. `Group`s cannot be nested
The `` element supports the following parameters:
| Property | Type | Description | iOS | Android |
|-----------|---------|:--------------------------------------------------------------|---|-------|
| `Title` | `string` | A string title to be displayed at the top of the context menu | ✅ | ❌ |
The `` element supports the following parameters:
| Property | Type | Description | iOS | Android |
|-----------|---------|:--------------------------------------------------------------|---|-------|
| `Title` | `string` | A string title to be displayed at the top of the group | ✅ | ❌ |
The `` element supports the following parameters:
| Property | Type | Description | iOS | Android |
|-----------|---------|:--------------------------------------------------------------|---|-------|
| `Title` | `string`| The text for the action | ✅ | ✅ |
| `Command` | `ICommand` | A command to execute when the user selects this action | ✅ | ✅ |
| `CommandParameter` | `object` | A parameter that will be passed to the `Command` | ✅ | ✅ |
| `Icon` | `ImageSource` | An icon to be displayed next to the action text | ✅ | ✅ |
| `SystemIcon` | `string` | A string reference to a system icon to use instead of the `Icon` | ✅* | ❌** |
| `IsEnabled` | `bool` | Enables/Disables the action in the menu | ✅ | ✅ |
| `IsVisible` | `bool` | Hides/Displays the action in the menu | ✅ | ✅ |
| `IsDestructive` | `bool` | Displays the action as destructive | ✅ | ✅ |
- \* SystemIcons on iOS use the SFSymbols collection of icons: https://developer.apple.com/sf-symbols/
- \*\* Android does not recommend using system icons in your apps
Here is what a more complex menu would look like using most properties available:
```xml
```
### Customising the preview
When an item is selected for its context menu to open, a highlighted preview can be displayed. This preview by default is a snapshot of the view itself. This can be customised using the `Preview` property.
| Property | Type | Description | iOS | Android |
|-----------|---------|:--------------------------------------------------------------|---|-------|
| `PreviewTemplate` | `DataTemplate` | Provide a different view to render the preview | ✅ | ✅ |
| `VisiblePath` | `IShape`| Customise the path used to clip the preview | ✅* | ✅ |
| `BackgroundColor` | `Color` | The background color for the hightlight preview | ✅ | ✅ |
| `Padding` | `Thickness` | The padding of the VisiblePath within the highlight preview | ✅ | ✅ |
- \* By default the Visible path on iOS has a corner radius set
Example:
```xml
```
### Standard click
Because of how context menus ar attached to view on each different platforms, the `TapGestureRecognizer` might not work in combination with the context menu. This is why this plugin also offers a `ClickCommand` property to ensure your command is called on every platform.
```xml
```
### Show menu on click
Sometimes you want to show the context menu on a click instead of the default long press/right click. Setting `ShowMenuOnClick` to true will simply do that. The highlight preview will however not be shown in this mode.
On iOS it is not possible to open a context menu on click. This plugin uses the UIKit `showsMenuAsPrimaryAction` property to support this feature. This is however only supported on UIKit.UIbutton, meaning `ShowMenuOnClick` will only work on `Button` on iOS
### TableView, ListView, CollectionView
To add a contextmenu to all items of a CollectionView for example:
```xml
```
This will add a contextmenu to each item of a CollectionView. However all the menus will be identical. If you need to have the menu change based on the item of the CollectionView selected, you can do so by using bindings. By default, the BindingContext of the `` is the item the user opened the context menu from.
This can also be useful to pass the item to the command of an action.
For example, if the Items of the CollectionView are:
```cs
public class UserDocuments {
public string Name { get; set; }
public bool CanUpload { get; set; }
}
```
You can configure the context menu for these items like so:
```xml
```
## Implementation details
This plugins aims to use the underlying platform's features as much as possible, however when needed the platform was extended to offer the best user experience.
### iOS
iOS provides a native and comprehensive context menu feature. This was used to support this plugin.
The [UIContextMenuInteraction](https://developer.apple.com/documentation/uikit/uicontextmenuinteraction) was used to support standalone controls. For items views, [contextMenuConfigurationForItemsAt](https://developer.apple.com/documentation/uikit/uicollectionviewdelegate/4002186-collectionview) or an equivalent method was used
### Android
Android offers a native context menu API. However this API basically just opens a [PopupMenu](https://developer.android.com/reference/android/widget/PopupMenu) anchored to the target view.
This plugin implements a more complete context menu experience by adding a highlighted preview and multiple other features to match the featureset provided by iOS.
A [MenuBuilder](https://developer.android.com/reference/android/view/Menu) is still used to conform the custom implementation to all other Android menus.
## TODO:
- Allows for the specification of the icon color. This would let developer choose whether their icons will match the text color or use the icon's colors.
---
Made within The49