KotBehamot.RadialSegmentControl 1.0.0

RadialSegmentControl

<div align="center">

</div>

<div align="center"> <img src="assets/icon.png" alt="RadialSegmentControl Icon" width="128" height="128" /> </div>

A high-quality, customizable radial/circular segment button control library for .NET MAUI applications. This library provides an interactive circular button interface with customizable segments, following SOLID principles and best practices for library development.

✨ Features

• 🎯 Radial Segment Layout: Display buttons in a circular/radial pattern
• 🎨 Customizable Appearance: Configure colors, text, and styling for each segment
• 📱 Touch Interaction: Full support for tap/click interactions
• 🔌 Extensible Design: Implement custom drawables through the IRadialSegmentDrawable interface
• 📦 MVVM Support: Bindable properties and command support
• 🎭 Event-Driven: Events and commands for segment selection

📦 Installation

Install via NuGet Package Manager:

dotnet add package KotBehamot.RadialSegmentControl

Or via Package Manager Console:

Install-Package KotBehamot.RadialSegmentControl

🚀 Quick Start

Basic Usage

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:controls="clr-namespace:RadialSegmentControl.Controls;assembly=RadialSegmentControl"
             x:Class="YourApp.MainPage">
    
    <controls:RadialSegmentControl x:Name="radialControl"
                                   WidthRequest="300"
                                   HeightRequest="300"
                                   CenterRadius="30"
                                   SegmentSelected="OnSegmentSelected" />
</ContentPage>

Code-Behind

using RadialSegmentControl.Models;

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
        
        // Add segments programmatically
        radialControl.Segments.Add(new RadialSegment
        {
            Text = "Option 1",
            BackgroundColor = Colors.Blue,
            TextColor = Colors.White,
            Value = "value1"
        });
        
        radialControl.Segments.Add(new RadialSegment
        {
            Text = "Option 2",
            BackgroundColor = Colors.Green,
            TextColor = Colors.White,
            Value = "value2"
        });
        
        radialControl.Segments.Add(new RadialSegment
        {
            Text = "Option 3",
            BackgroundColor = Colors.Red,
            TextColor = Colors.White,
            Value = "value3"
        });
    }
    
    private void OnSegmentSelected(object sender, SegmentSelectedEventArgs e)
    {
        DisplayAlert("Selected", $"You selected: {e.Segment.Text}", "OK");
    }
}

MVVM Usage

using System.Collections.ObjectModel;
using System.Windows.Input;
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
using RadialSegmentControl.Models;

public partial class MainViewModel : ObservableObject
{
    [ObservableProperty]
    private ObservableCollection<RadialSegment> segments;
    
    [ObservableProperty]
    private RadialSegment? selectedSegment;
    
    public ICommand SegmentSelectedCommand { get; }
    
    public MainViewModel()
    {
        Segments = new ObservableCollection<RadialSegment>
        {
            new RadialSegment { Text = "A", BackgroundColor = Colors.Blue, TextColor = Colors.White },
            new RadialSegment { Text = "B", BackgroundColor = Colors.Green, TextColor = Colors.White },
            new RadialSegment { Text = "C", BackgroundColor = Colors.Red, TextColor = Colors.White }
        };
        
        SegmentSelectedCommand = new RelayCommand<RadialSegment>(OnSegmentSelected);
    }
    
    private void OnSegmentSelected(RadialSegment? segment)
    {
        if (segment != null)
        {
            // Handle selection
        }
    }
}

<controls:RadialSegmentControl Segments="{Binding Segments}"
                               SelectedSegment="{Binding SelectedSegment}"
                               SegmentSelectedCommand="{Binding SegmentSelectedCommand}"
                               WidthRequest="300"
                               HeightRequest="300" />

🔧 Advanced Usage

Custom Drawable

Create a custom rendering implementation by implementing IRadialSegmentDrawable:

using RadialSegmentControl.Interfaces;
using RadialSegmentControl.Models;

public class CustomRadialDrawable : IRadialSegmentDrawable
{
    public void DrawSegment(ICanvas canvas, RadialSegment segment, 
                           float centerX, float centerY, float radius, bool isSelected)
    {
        // Custom drawing logic
    }
    
    public void DrawCenter(ICanvas canvas, float centerX, float centerY, float radius)
    {
        // Custom center circle drawing
    }
}

// Use custom drawable
var control = new RadialSegmentControl(new CustomRadialDrawable());

📜 API Reference

RadialSegmentControl

Properties:

• Segments (ObservableCollection<RadialSegment>): Collection of segments to display
• SelectedSegment (RadialSegment?): Currently selected segment (bindable, two-way)
• CenterRadius (float): Radius of the center circle (default: 30)
• SegmentSelectedCommand (ICommand?): Command executed when a segment is selected

Events:

• SegmentSelected: Raised when a segment is selected

RadialSegment

Properties:

• Id (string): Unique identifier
• Text (string): Display text
• BackgroundColor (Color): Segment background color
• TextColor (Color): Text color
• Value (object?): Associated value/data
• IsEnabled (bool): Whether segment is enabled
• StartAngle (float): Start angle in degrees (auto-calculated)
• SweepAngle (float): Segment size in degrees (auto-calculated)
• Metadata (IDictionary<string, object>): Additional custom data

🏛️ Architecture & SOLID Principles

This library is built with clean architecture and SOLID principles:

Single Responsibility Principle (SRP)

• RadialSegment: Pure data model - only stores segment information
• RadialSegmentControl: Manages control lifecycle, events, and bindings
• IRadialSegmentDrawable: Defines rendering contract
• BasicRadialSegmentDrawable: Implements default rendering logic
• RadialSegmentBuilder: Handles fluent object construction
• RadialSegmentExtensions: Provides utility operations

Open/Closed Principle (OCP)

• Extensible: Create custom rendering by implementing IRadialSegmentDrawable
• Closed for modification: Core control logic doesn't change when adding new visual styles
• Example: Swap rendering implementations without touching control code

Liskov Substitution Principle (LSP)

• Properly inherits from GraphicsView
• All IRadialSegmentDrawable implementations are interchangeable
• Maintains expected behavior across substitutions

Interface Segregation Principle (ISP)

• IRadialSegmentDrawable: Contains only drawing methods
• No forced implementation of unused functionality
• Clean, focused contracts

Dependency Inversion Principle (DIP)

• RadialSegmentControl depends on IRadialSegmentDrawable abstraction
• Concrete implementations injected via constructor
• Easily testable through mocking

🎨 Use Cases

Radial Menus

Perfect for creating circular context menus and radial selection interfaces.

Music Applications

Ideal for key signature selection, chord progression wheels, or music theory tools.

Navigation Controls

Create unique circular navigation interfaces for mobile apps.

Data Visualization

Interactive pie charts with selectable segments.

Game Interfaces

Circular skill trees, radial weapon selectors, or ability wheels.

📊 Platform Support

⚡ Performance

• Optimized rendering using ICanvas for hardware acceleration
• Efficient hit-testing with mathematical calculations (no pixel iteration)
• Minimal allocations - reuses objects where possible
• Smooth animations - 60 FPS on modern devices

🔒 Requirements

• .NET: 8.0 or later
• MAUI: 8.0 or later
• C#: 12.0 or later

🐛 Known Limitations

• Segment count: Recommended 2-12 segments for optimal usability
• Text length: Best with short labels (1-10 characters)
• Center radius: Should be proportional to control size (10-30% of radius)

📚 Documentation

• Changelog: Detailed version history
• Contributing Guidelines: How to contribute
• API Documentation: Full API reference
• Sample Project: Working examples

🏷️ Versioning

This project adheres to Semantic Versioning:

• MAJOR: Incompatible API changes
• MINOR: Backwards-compatible functionality additions
• PATCH: Backwards-compatible bug fixes

Current version: 1.0.0

🛡️ Security

For security concerns, please see our Security Policy.

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: Create an issue for support

🌟 Star History

If you find this library useful, please consider giving it a ⭐ on GitHub!

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting PRs.

Ways to Contribute

• 🐛 Report bugs
• 💡 Suggest features
• 📝 Improve documentation
• 🔧 Submit pull requests
• ⭐ Star the repository
• 📢 Spread the word

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright 2025 KotBehamot

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

🙏 Acknowledgments

• Extracted from the MusicKeyChanger project
• Built with .NET MAUI
• Inspired by radial menu patterns in modern UIs

👨‍💻 Authors

• KotBehamot - GitHub Profile

📂 Project Structure

RadialSegmentControl/
├── src/
│   └── RadialSegmentControl/        # Main library
│   ├── Controls/         # UI Controls
│       ├── Models/        # Data models
│       ├── Interfaces/            # Abstractions
│       ├── Drawing/           # Rendering implementations
│       ├── Builders/     # Builder patterns
│ ├── Adapters/         # Adapter patterns
│  ├── Extensions/  # Extension methods
│       └── Events/           # Event arguments
├── tests/
│   └── RadialSegmentControl.Tests/ # Unit tests
├── samples/
│   └── RadialSegmentControl.Sample/ # Sample application
├── docs/# Documentation
└── assets/# Package assets (icon, etc.)

<div align="center">

Made with ❤️ by KotBehamot

Report Bug · Request Feature · Documentation

</div>