# MarketAlly.Mopups

[![NuGet Version](https://img.shields.io/nuget/v/MarketAlly.Mopups.svg?style=flat)](https://www.nuget.org/packages/MarketAlly.Mopups/)
[![NuGet Downloads](https://img.shields.io/nuget/dt/MarketAlly.Mopups.svg)](https://www.nuget.org/packages/MarketAlly.Mopups/)
[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![.NET](https://img.shields.io/badge/.NET-9.0-512BD4)](https://dotnet.microsoft.com/download)
[![Platform](https://img.shields.io/badge/Platform-iOS%20%7C%20Android%20%7C%20Windows%20%7C%20macOS-lightgray)](https://dotnet.microsoft.com/apps/maui)

Customizable popups for .NET MAUI with multi-window support. A fork of [Mopups](https://github.com/LuckyDucko/Mopups) by Tyson Hooker (LuckyDucko) with enhanced multi-window capabilities for all platforms.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Multi-Window Support](#multi-window-support)
- [Usage](#usage)
- [Platform Support](#platform-support)
- [Requirements](#requirements)
- [License](#license)
- [Acknowledgments](#acknowledgments)

## Features

### Core Capabilities (from Mopups)

- **Customizable Popups**: Full control over popup appearance and behavior
- **Async/Await Pattern**: Modern asynchronous popup handling
- **Animation Support**: Built-in appearing and disappearing animations
- **System Padding**: Automatic safe area handling
- **Back Button Handling**: Customizable back button behavior
- **Cross-Platform**: iOS, Android, Windows, and macOS (Mac Catalyst)

### New in MarketAlly.Mopups v2.0.0

- **Multi-Window Support**: Display popups on specific windows instead of always on the main window
  - Windows: Uses target window's `XamlRoot`
  - iOS/iPadOS: Uses target window's `UIWindowScene`
  - macOS Catalyst: Uses target window's `UIWindowScene`
  - Android: Uses target window's Activity `DecorView`

## Installation

Install via NuGet Package Manager:

```bash
dotnet add package MarketAlly.Mopups
```

Or via Package Manager Console:

```powershell
Install-Package MarketAlly.Mopups
```

## Quick Start

### 1. Configure in MauiProgram.cs

```csharp
using Mopups.Hosting;

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .ConfigureMopups();  // Add this line

    return builder.Build();
}
```

### 2. Create a Popup Page

```csharp
using Mopups.Pages;

public class MyPopupPage : PopupPage
{
    public MyPopupPage()
    {
        Content = new StackLayout
        {
            Children =
            {
                new Label { Text = "Hello from popup!" },
                new Button { Text = "Close", Command = new Command(async () =>
                    await MopupService.Instance.PopAsync()) }
            }
        };
    }
}
```

### 3. Show the Popup

```csharp
using Mopups.Services;

// Show on main window (default behavior)
await MopupService.Instance.PushAsync(new MyPopupPage());

// Show on specific window (NEW in v2.0.0)
await MopupService.Instance.PushAsync(new MyPopupPage(), targetWindow);
```

## Multi-Window Support

The key enhancement in MarketAlly.Mopups is the ability to display popups on specific windows. This is essential for applications with multiple windows, such as:

- Helper/tool windows
- Document windows
- Settings panels
- Floating utility windows

### API

```csharp
// Standard push (uses main window)
Task PushAsync(PopupPage page, bool animate = true);

// Window-aware push (NEW)
Task PushAsync(PopupPage page, Window? window, bool animate = true);
```

### Example: Showing Dialog on Helper Window

```csharp
public class HelperWindow : Window
{
    public async Task ShowConfirmation()
    {
        var popup = new ConfirmationPopup();

        // Pass 'this' to show popup on this window, not the main window
        await MopupService.Instance.PushAsync(popup, this);
    }
}
```

### Platform Implementation Details

| Platform | How Window is Used |
|----------|-------------------|
| Windows | Gets `XamlRoot` from the target window's native `Microsoft.UI.Xaml.Window` |
| iOS/iPadOS | Gets `UIWindowScene` from the target window's native `UIWindow` |
| macOS Catalyst | Gets `UIWindowScene` from the target window's native `UIWindow` |
| Android | Gets `DecorView` from the target window's `Activity` |

## Usage

### Basic Popup Operations

```csharp
// Push a popup
await MopupService.Instance.PushAsync(new MyPopupPage());

// Push with animation control
await MopupService.Instance.PushAsync(new MyPopupPage(), animate: false);

// Pop the topmost popup
await MopupService.Instance.PopAsync();

// Pop all popups
await MopupService.Instance.PopAllAsync();

// Remove specific popup
await MopupService.Instance.RemovePageAsync(specificPopup);

// Check popup stack
var popupStack = MopupService.Instance.PopupStack;
```

### Events

```csharp
MopupService.Instance.Pushing += (sender, args) =>
    Console.WriteLine($"Pushing: {args.Page}");

MopupService.Instance.Pushed += (sender, args) =>
    Console.WriteLine($"Pushed: {args.Page}");

MopupService.Instance.Popping += (sender, args) =>
    Console.WriteLine($"Popping: {args.Page}");

MopupService.Instance.Popped += (sender, args) =>
    Console.WriteLine($"Popped: {args.Page}");
```

### PopupPage Properties

```csharp
public class MyPopupPage : PopupPage
{
    public MyPopupPage()
    {
        // Background click dismisses popup
        CloseWhenBackgroundIsClicked = true;

        // Handle safe areas
        HasSystemPadding = true;

        // Background color
        BackgroundColor = Color.FromRgba("#80000000");
    }

    // Override for custom back button behavior
    protected override bool OnBackButtonPressed()
    {
        // Return true to prevent dismissal
        return false;
    }
}
```

## Platform Support

| Platform | Minimum Version | Multi-Window Support |
|----------|-----------------|---------------------|
| iOS | 11.0 | Yes (iOS 13+ with UIScene) |
| Android | API 21 (5.0) | Yes (Android 7.0+ multi-window) |
| Windows | 10.0.17763.0 | Yes |
| macOS | 13.1 (Catalyst) | Yes |

## Requirements

- .NET 9.0
- Microsoft.Maui.Controls 9.0+
- Microsoft.Maui.Essentials 9.0+

## License

This project is licensed under the **BSD 3-Clause License**.

```
BSD 3-Clause License

Copyright (c) 2022, Tyson Elliot Hooker
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
```

## Acknowledgments

This project is a fork of [Mopups](https://github.com/LuckyDucko/Mopups), originally created by **Tyson Hooker (LuckyDucko)**. We extend our gratitude to:

- **Tyson Hooker** - Original author and maintainer of Mopups
- **Maksym Koshovyi** - Contributor
- **Aswin P G** - Contributor
- **Kirill Lyubimov** - Contributor
- **Martijn Van Dijk** - Contributor
- **Shane Neuville** - Contributor

Mopups itself was created as a replacement for the "Rg.Plugins.Popups" plugin for Xamarin, providing a modern popup solution for .NET MAUI.

### Additional Resources

- [Original Mopups Repository](https://github.com/LuckyDucko/Mopups)
- [Mopups Introduction Video by Gerald Versluis](https://youtu.be/OGWhgASmSto)

---

**Built with precision by [MarketAlly](https://marketally.com)**

*Multi-window popup support for .NET MAUI applications.*