52 lines
1.8 KiB
Markdown
52 lines
1.8 KiB
Markdown
# custom_cursor
|
|
|
|
Custom cursor decoding, registration, and display for Flutter apps.
|
|
|
|
`custom_cursor` decodes Windows `.cur` and `.ani` resources, Linux Xcursor themes, native raster images (PNG/GIF/APNG/WebP/JPEG/BMP), and static SVG into [Cursor] / [AnimatedCursor] models. A [CursorRegion] widget switches the platform cursor when the mouse hovers its subtree, honoring the OS pointer-size multiplier and mirroring cursors for right-to-left layouts.
|
|
|
|
## Platforms
|
|
|
|
| Platform | Support | Implementation |
|
|
| -------- | ------- | ---------------------- |
|
|
| macOS | ✅ | Swift Package Manager |
|
|
| Windows | ✅ | C++ (GDI+) |
|
|
| Linux | ✅ | C++ (GTK3) |
|
|
| Web | ✅ | CSS `cursor: url(...)` |
|
|
| Android | ✅ | Kotlin (API 24+) |
|
|
|
|
### Linux prerequisites
|
|
|
|
Building on Linux requires GTK3 development headers:
|
|
|
|
```sh
|
|
sudo apt-get install -y libgtk-3-dev
|
|
```
|
|
|
|
## Cursor size limit
|
|
|
|
Cursors are capped at **128 px** per dimension, matching browser and native system limits. Custom sizes larger than 128 are clamped automatically ([CursorScaler]). 128 is available as a preset alongside the standard sizes.
|
|
|
|
## Android
|
|
|
|
Android support requires a minimum SDK of **24** (the pointer-icon API is gated behind `Build.VERSION.SDK_INT >= N`; on older devices the system arrow is kept).
|
|
|
|
## Usage
|
|
|
|
```dart
|
|
import "package:custom_cursor/custom_cursor.dart";
|
|
|
|
final cursors = cursorAssets({
|
|
"normal": await decodeCursorAsset(curBytes, ...),
|
|
...
|
|
});
|
|
|
|
// Register and display the "normal" cursor while hovering [child].
|
|
CursorRegion(
|
|
cursors: cursors,
|
|
child: child,
|
|
)
|
|
```
|
|
|
|
Registered cursors use the `"custom_cursor"` method channel and follow the OS pointer-size multiplier through `systemCursorScale` / `registerScaleObserver`,
|
|
and the OS layout direction through `systemDirection` / `registerDirectionObserver`.
|