repository·master·Indexed 20 days ago
https://github.com/vintage/scratcherA Flutter widget for creating scratch card effects that temporarily hide content under a color or image layer. It features progress tracking via onChange, a configurable reveal threshold via onThreshold, and programmatic control through ScratcherState methods like reset() and reveal() using a GlobalKey.
To customize the app's launch screen, replace the existing image files within the example/ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory with your own assets.
Alternatively, you can manage these assets using Xcode:
open ios/Runner.xcworkspace.Runner/Assets.xcassets.open ios/Runner.xcworkspaceAdd scratcher as a dependency in your pubspec.yaml file to use the scratch card widget in your Flutter project.
dependencies:
scratcher: "^2.5.0"To use the scratch card, import package:scratcher/scratcher.dart and wrap the widget you want to hide inside a Scratcher widget. You can cover the child with a solid color or a custom image.
Key features include tracking scratch progress via onChange and triggering an action when a specific percentage of the area is revealed via onThreshold.
import 'package:scratcher/scratcher.dart';
Scratcher(
brushSize: 30,
threshold: 50,
color: Colors.red,
onChange: (value) => print("Scratch progress: $value%"),
onThreshold: () => print("Threshold reached, you won!"),
child: Container(
height: 300,
width: 300,
color: Colors.blue,
),
)The accuracy property determines how precisely the progress is tracked. Higher accuracy provides a smoother progress value but requires more computational resources.
Use the ScratchAccuracy enum to set the level:
ScratchAccuracy.low: High performance, lower accuracy.ScratchAccuracy.medium: Balanced performance and accuracy.ScratchAccuracy.high: High accuracy, lower performance.Scratcher(
accuracy: ScratchAccuracy.medium,
child: MyWidget(),
)The Scratcher widget covers a given child with a scratchable overlay. You can use a solid color or an image to create the scratchable surface. The widget provides callbacks to track progress, detect when a threshold is reached, and monitor the lifecycle of the scratching interaction.
child: The widget that will be revealed underneath the scratch layer.threshold: A double (0.0 to 100.0) representing the percentage of the area that must be scratched to trigger onThreshold.brushSize: The size of the scratch brush.accuracy: Controls the trade-off between progress tracking precision and performance using ScratchAccuracy.color: The color used for the scratchable overlay (if no image is provided).image: An Image widget to use as the scratchable overlay.onChange: Called when the revealed area changes (minimum 0.1% difference).onThreshold: Called when the threshold percentage is reached.onScratchStart, onScratchUpdate, onScratchEnd: Lifecycle callbacks for the user's touch/drag interaction.Scratcher(
brushSize: 30,
threshold: 50, // Trigger onThreshold at 50%
onChange: (progress) => print('Progress: $progress%'),
onThreshold: () => print('Threshold reached!'),
child: Text('Hidden Content'),
)To trigger actions like resetting the scratch card or revealing the content entirely from your code, assign a GlobalKey<ScratcherState> to the Scratcher widget. This allows you to access the ScratcherState methods.
final scratchKey = GlobalKey<ScratcherState>();
// In your build method
Scratcher(
key: scratchKey,
// ... other properties
)
// To reset the scratcher
scratchKey.currentState?.reset(duration: Duration(milliseconds: 2000));
// To reveal the whole scratcher
scratchKey.currentState?.reveal();The Scratcher widget accepts the following properties to configure the scratch card behavior and appearance:
| Property | Type | Description |
|---|---|---|
child | Widget | Widget rendered under the scratch area. |
enabled | bool | Whether new scratches can be applied. |
threshold | double | Percentage level of scratch area which should be revealed to complete. |
brushSize | double | Size of the brush. The bigger it is the faster user can scratch the card. |
accuracy | ScratchAccuracy | Determines how accurate the progress should be reported. Lower accuracy means higher performance. |
color | Color | Color used to cover the child widget. |
image | Image | Image widget used to cover the child widget. |
rebuildOnResize | bool | Determines if the scratcher should rebuild itself when space constraints change (resize). |
onChange | Function | Callback called when new part of area is revealed (min 0.1% difference). |
onThreshold | Function | Callback called when threshold is reached (only when defined). |
onScratchStart | Function | Callback called when scratching starts. |
onScratchUpdate | Function | Callback called during scratching. |
onScratchEnd | Function | Callback called when scratching ends. |
Use ScratcherState to programmatically control the widget's state. You can obtain the state using a GlobalKey<ScratcherState>.
reset({Duration? duration}): Resets the scratcher to its initial state. If a duration is provided, scratching is disabled during the transition.reveal({Duration? duration}): Immediately reveals the entire child widget. If a duration is provided, the transition is animated.final GlobalKey<ScratcherState> _key = GlobalKey<ScratcherState>();
// In your build method
Scratcher(
key: _key,
child: MyWidget(),
)
// To reset programmatically
_key.currentState?.reset(duration: Duration(milliseconds: 500));
// To reveal programmatically
_key.currentState?.reveal(duration: Duration(milliseconds: 500));The following properties are available on the Scratcher widget:
| Property | Type | Description |
|---|---|---|
child | Widget | Required. The widget rendered under the scratch area. |
enabled | bool | Whether new scratches can be applied. Defaults to true. |
threshold | double? | Percentage level (0-100) to complete. |
brushSize | double | Size of the brush. Defaults to 25. |
accuracy | ScratchAccuracy | Determines progress tracking precision. Defaults to ScratchAccuracy.high. |
color | Color | Color used to cover the child. Defaults to Colors.black. |
image | Image? | Image widget used to cover the child. |
rebuildOnResize | bool | If true, rebuilds when space constraints change. Defaults to true. |
onChange | Function(double value)? | Called when new part of area is revealed. |
onThreshold | VoidCallback? | Called when threshold is reached. |
onScratchStart | VoidCallback? | Called when scratching starts. |
onScratchUpdate | VoidCallback? | Called during scratching. |
onScratchEnd | VoidCallback? | Called when scratching ends. |
When using a GlobalKey<ScratcherState>, you can call the following methods on the currentState:
reset({Duration? duration}): Resets the scratcher state to the initial values.reveal(): Reveals the whole scratcher, so that only the original child is displayed.