Skip to content

Commit 301a925

Browse files
Copilotmattleibow
Copilot
and
mattleibow
committed
Add gesture surface controls for MAUI (port of PR #79)
Co-authored-by: mattleibow <1096616+mattleibow@users.noreply.github.com>
1 parent e3343e8 commit 301a925

19 files changed

Lines changed: 1642 additions & 0 deletions

‎.github/copilot-instructions.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
# GitHub Copilot Instructions for SkiaSharp.Extended
2+
3+
This document provides instructions for GitHub Copilot when working with the SkiaSharp.Extended repository.
4+
5+
## Repository Overview
6+
7+
SkiaSharp.Extended is a collection of additional libraries and controls for SkiaSharp, a cross-platform 2D graphics API for .NET. The repository includes:
8+
9+
- **SkiaSharp.Extended** - Core extension library with utilities like PathBuilder, SKGeometry, etc.
10+
- **SkiaSharp.Extended.UI.Maui** - MAUI controls including Lottie animations, Confetti effects, and gesture surfaces
11+
12+
## Project Structure
13+
14+
```
15+
SkiaSharp.Extended/
16+
├── source/
17+
│ ├── SkiaSharp.Extended/ # Core library (netstandard2.0, net9.0)
18+
│ └── SkiaSharp.Extended.UI.Maui/ # MAUI controls
19+
│ ├── Controls/
20+
│ │ ├── Confetti/ # Confetti particle system
21+
│ │ ├── Lottie/ # Lottie animation support
22+
│ │ └── Gestures/ # Gesture and dynamic surface views
23+
│ └── Utils/ # Utility classes
24+
├── samples/
25+
│ └── SkiaSharpDemo/ # MAUI demo app
26+
├── tests/ # Test projects
27+
└── docs/ # Documentation
28+
```
29+
30+
## Coding Conventions
31+
32+
### Naming Conventions
33+
- All control classes start with `SK` prefix (e.g., `SKConfettiView`, `SKGestureSurfaceView`)
34+
- Event args classes end with `EventArgs` suffix
35+
- Shared source files use `.shared.cs` extension
36+
- Platform-specific files use `.android.cs`, `.ios.cs`, `.windows.cs`, etc.
37+
38+
### File Naming
39+
- `*.shared.cs` - Cross-platform code
40+
- `*.shared.xaml` - Shared XAML resources
41+
- `*.android.cs` - Android-specific code
42+
- `*.ios.cs` - iOS-specific code
43+
- `*.windows.cs` - Windows-specific code
44+
45+
### Code Style
46+
- File-scoped namespaces
47+
- Nullable reference types enabled
48+
- LangVersion 10.0
49+
- Implicit usings enabled for MAUI projects
50+
51+
### Control Patterns
52+
53+
Controls follow a consistent pattern using `TemplatedView`:
54+
55+
```csharp
56+
namespace SkiaSharp.Extended.UI.Controls;
57+
58+
public class SKMyControl : SKSurfaceView // or TemplatedView
59+
{
60+
public static readonly BindableProperty MyProperty = BindableProperty.Create(
61+
nameof(MyPropertyName),
62+
typeof(PropertyType),
63+
typeof(SKMyControl),
64+
defaultValue,
65+
propertyChanged: OnMyPropertyChanged);
66+
67+
public SKMyControl()
68+
{
69+
// Register resources for styling
70+
ResourceLoader<Themes.SKMyControlResources>.EnsureRegistered(this);
71+
}
72+
73+
public PropertyType MyPropertyName
74+
{
75+
get => (PropertyType)GetValue(MyProperty);
76+
set => SetValue(MyProperty, value);
77+
}
78+
79+
protected override void OnPaintSurface(SKCanvas canvas, SKSize size)
80+
{
81+
// Drawing logic
82+
}
83+
84+
private static void OnMyPropertyChanged(BindableObject bindable, object? oldValue, object? newValue)
85+
{
86+
// Property change handler
87+
}
88+
}
89+
```
90+
91+
### XAML Resource Pattern
92+
93+
Each control has a corresponding resources file:
94+
95+
```xaml
96+
<ResourceDictionary xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
97+
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
98+
xmlns:local="clr-namespace:SkiaSharp.Extended.UI.Controls"
99+
xmlns:skia="clr-namespace:SkiaSharp.Views.Maui.Controls;assembly=SkiaSharp.Views.Maui.Controls"
100+
x:Class="SkiaSharp.Extended.UI.Controls.Themes.SKMyControlResources">
101+
102+
<ControlTemplate x:Key="SKMyControlControlTemplate">
103+
<skia:SKCanvasView x:Name="PART_DrawingSurface" />
104+
</ControlTemplate>
105+
106+
<Style x:Key="SKMyControlStyle" TargetType="local:SKMyControl">
107+
<Setter Property="ControlTemplate"
108+
Value="{StaticResource SKMyControlControlTemplate}" />
109+
</Style>
110+
111+
<Style TargetType="local:SKMyControl"
112+
ApplyToDerivedTypes="True"
113+
BasedOn="{StaticResource SKMyControlStyle}" />
114+
</ResourceDictionary>
115+
```
116+
117+
## Build Instructions
118+
119+
### Prerequisites
120+
- .NET 9 SDK or later
121+
- MAUI workload installed: `dotnet workload install maui`
122+
- On Linux, only Android builds are supported: `dotnet workload install maui-android`
123+
124+
### Build Commands
125+
```bash
126+
# Restore packages (use nuget.org source if internal feeds are unavailable)
127+
dotnet restore source/SkiaSharp.Extended.UI.Maui/SkiaSharp.Extended.UI.Maui.csproj --source https://api.nuget.org/v3/index.json
128+
129+
# Build for Android
130+
dotnet build source/SkiaSharp.Extended.UI.Maui/SkiaSharp.Extended.UI.Maui.csproj -f net9.0-android35.0
131+
132+
# Build for all platforms (Windows only)
133+
dotnet build source/SkiaSharp.Extended.UI.Maui/SkiaSharp.Extended.UI.Maui.csproj
134+
```
135+
136+
### Target Frameworks
137+
- `net9.0` - Reference assembly
138+
- `net9.0-android35.0` - Android
139+
- `net9.0-ios18.0` - iOS (macOS/Windows only)
140+
- `net9.0-maccatalyst18.0` - Mac Catalyst (macOS only)
141+
- `net9.0-windows10.0.19041.0` - Windows (Windows only)
142+
143+
## Common Patterns
144+
145+
### ResourceLoader Pattern
146+
Used to ensure XAML resources are loaded:
147+
```csharp
148+
public SKMyControl()
149+
{
150+
ResourceLoader<Themes.SKMyControlResources>.EnsureRegistered(this);
151+
}
152+
```
153+
154+
### Animation Pattern
155+
For animated controls, inherit from `SKAnimatedSurfaceView`:
156+
```csharp
157+
public class SKMyAnimatedControl : SKAnimatedSurfaceView
158+
{
159+
protected override void Update(TimeSpan deltaTime)
160+
{
161+
// Update animation state
162+
}
163+
164+
protected override void OnPaintSurface(SKCanvas canvas, SKSize size)
165+
{
166+
// Draw current frame
167+
}
168+
}
169+
```
170+
171+
### Touch/Gesture Pattern
172+
Enable touch events and handle them:
173+
```csharp
174+
// In constructor or initialization
175+
canvasView.EnableTouchEvents = true;
176+
canvasView.Touch += OnTouch;
177+
178+
private void OnTouch(object? sender, SKTouchEventArgs e)
179+
{
180+
switch (e.ActionType)
181+
{
182+
case SKTouchAction.Pressed:
183+
// Handle press
184+
break;
185+
case SKTouchAction.Moved:
186+
// Handle move
187+
break;
188+
case SKTouchAction.Released:
189+
// Handle release
190+
break;
191+
}
192+
e.Handled = true;
193+
}
194+
```
195+
196+
## Dependencies
197+
198+
### NuGet Packages
199+
- `SkiaSharp` (3.119.1+)
200+
- `SkiaSharp.Skottie` (3.119.1+) - For Lottie animations
201+
- `SkiaSharp.Views.Maui.Controls` (3.119.1+)
202+
- `Microsoft.Maui.Controls` (9.x)
203+
204+
### Project References
205+
- `SkiaSharp.Extended.UI.Maui` → `SkiaSharp.Extended`
206+
207+
## Testing
208+
209+
### Test Structure
210+
Tests are located in the `tests/` directory and use xUnit framework.
211+
212+
### Running Tests
213+
```bash
214+
dotnet test tests/SkiaSharp.Extended.Tests/SkiaSharp.Extended.Tests.csproj
215+
```
216+
217+
## Common Issues
218+
219+
### 1. NuGet Restore Failures
220+
If restore fails with Azure DevOps feed errors, use:
221+
```bash
222+
dotnet restore --source https://api.nuget.org/v3/index.json
223+
```
224+
225+
### 2. MAUI Workload Not Found
226+
Install the appropriate workload:
227+
```bash
228+
# Windows/macOS - full MAUI
229+
dotnet workload install maui
230+
231+
# Linux - Android only
232+
dotnet workload install maui-android
233+
```
234+
235+
### 3. Deprecated SkiaSharp APIs
236+
Use modern APIs:
237+
- `SKMatrix.CreateIdentity()` instead of `SKMatrix.MakeIdentity()`
238+
- `SKMatrix.CreateTranslation()` instead of `SKMatrix.MakeTranslation()`
239+
- `SKFont` for text measurement instead of `SKPaint.TextSize`
240+
241+
## Resources
242+
243+
- [SkiaSharp Documentation](https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/graphics/skiasharp/)
244+
- [.NET MAUI Documentation](https://docs.microsoft.com/en-us/dotnet/maui/)
245+
- [SkiaSharp.Views.Maui](https://learn.microsoft.com/en-us/dotnet/api/skiasharp.views.maui)

‎.github/workflows/copilot-setup.yml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
name: Copilot Setup
2+
3+
on:
4+
workflow_dispatch:
5+
# This workflow can be triggered manually to set up the development environment
6+
7+
jobs:
8+
setup-dotnet-maui:
9+
runs-on: ${{ matrix.os }}
10+
11+
strategy:
12+
matrix:
13+
os: [ubuntu-latest, windows-latest, macos-latest]
14+
include:
15+
- os: ubuntu-latest
16+
workload: maui-android
17+
- os: windows-latest
18+
workload: maui
19+
- os: macos-latest
20+
workload: maui
21+
22+
steps:
23+
- name: Checkout repository
24+
uses: actions/checkout@v4
25+
26+
- name: Setup .NET
27+
uses: actions/setup-dotnet@v4
28+
with:
29+
dotnet-version: |
30+
9.0.x
31+
dotnet-quality: 'ga'
32+
33+
- name: Display .NET version
34+
run: dotnet --version
35+
36+
- name: Install MAUI workload
37+
run: dotnet workload install ${{ matrix.workload }} --source https://api.nuget.org/v3/index.json
38+
39+
- name: List installed workloads
40+
run: dotnet workload list
41+
42+
- name: Restore dependencies
43+
run: dotnet restore source/SkiaSharp.Extended.UI.Maui/SkiaSharp.Extended.UI.Maui.csproj --source https://api.nuget.org/v3/index.json
44+
45+
- name: Build library (Android)
46+
if: matrix.os == 'ubuntu-latest'
47+
run: dotnet build source/SkiaSharp.Extended.UI.Maui/SkiaSharp.Extended.UI.Maui.csproj -f net9.0-android35.0 --no-restore
48+
49+
- name: Build library (all platforms)
50+
if: matrix.os != 'ubuntu-latest'
51+
run: dotnet build source/SkiaSharp.Extended.UI.Maui/SkiaSharp.Extended.UI.Maui.csproj --no-restore
52+
53+
verify-environment:
54+
runs-on: ubuntu-latest
55+
needs: setup-dotnet-maui
56+
57+
steps:
58+
- name: Checkout repository
59+
uses: actions/checkout@v4
60+
61+
- name: Setup .NET
62+
uses: actions/setup-dotnet@v4
63+
with:
64+
dotnet-version: '9.0.x'
65+
66+
- name: Install Android workload
67+
run: dotnet workload install maui-android --source https://api.nuget.org/v3/index.json
68+
69+
- name: Verify build
70+
run: |
71+
dotnet restore --source https://api.nuget.org/v3/index.json
72+
dotnet build source/SkiaSharp.Extended/SkiaSharp.Extended.csproj -c Release
73+
74+
- name: Run tests
75+
run: dotnet test tests/SkiaSharp.Extended.Tests/SkiaSharp.Extended.Tests.csproj --no-restore
76+
continue-on-error: true

0 commit comments

Comments
 (0)