CubixD, a 3d cube
Installation
Add cubixd to your pubspec.yaml dependencies
dependencies:
cubixd: ^0.1.1
And then import it:
import 'package:cubixd/cubixd.dart';
Features
- Add this to your flutter app to get a 3d cube!
Getting started
This package includes 2 widgets:
- AnimatedCubixD
- CubixD
AnimatedCubixD is the 3d cube animated, this widget uses 3 controllers (AnimationController
) for 3 different animations.
Includes the shadow, the colorful stars, all animations and the functionality to select a field
CubixD is the static 3d cube, this widget includes the functionality to select a field (without the animation)
The example you saw at the beginning you can do it with the following code:
import 'package:cubixd/cubixd.dart';
Center(
child: AnimatedCubixD(
onSelected: ((SelectedSide opt) => opt == SelectedSide.bottom ? false : true),
size: 200.0,
left: Container(
decoration: const BoxDecoration(
image: DecorationImage(
image: AssetImage("assets/images/graphql.png"),
fit: BoxFit.cover,
),
),
),
front: Container(
decoration: const BoxDecoration(
image: DecorationImage(
image: AssetImage("assets/images/nestjs.png"),
fit: BoxFit.cover,
),
),
),
back: Container(
decoration: const BoxDecoration(
image: DecorationImage(
image: AssetImage("assets/images/mongodb.png"),
fit: BoxFit.cover,
),
),
),
top: ...,
bottom: ...,
right: ...,
),
),
AnimatedCubixD
Parameters
Parameter | Type | Default value | Description |
---|---|---|---|
advancedXYposAnim | AnimRequirements | – | Advanced XY Position Animation. If you want more control over the AnimationController and the 2 animations that requires, you could set this parameter. Keep in mind that the AnimationController won’t forward and dispose automatically when you set this option. You can read more information and examples down below |
afterRestDel | Duration | Duration(miliseconds: 50) |
After Restore Delay. This parameter represents the delay after the cubixd restore animation executes to make way to the main animation again |
afterSelDel | Duration | Duration(seconds: 4) |
After Selection Delay. This parameter represents the duration that cubixd waits after a face is selected, and right after that time restores the cubixd to the main animation |
back * | Widget | – | The widget that should be displayed on the back face side |
bottom * | Widget | – | The widget that should be displayed on the bottom face side |
buildOnSelect | Widget Function(double, AnimationController) | null | If you don’t like the default starts animation that triggers when the user selects a face. With a great freedom, you could set a different one with this parameter. This one is quite complex, so you can read more about this down below |
debounceTime | Duration | Duration(miliseconds: 500) |
Debonce Time. The cubixd works with a debouncer, this means that when you constantly move the cubixd to select a face it won’t execute the selection until you leave it static with a valid face and wait the duration specified here it will trigger the selection, otherwise if you move it just before time runs, it will “bounce” the selection and count back from 0 this time specified here |
front * | Widget | – | The widget that should be displayed on the front face side |
left * | Widget | – | The widget that should be displayed on the left face side |
onPanUpdate | void Function() | null | On Pan Update. This is a callback that executes whatever the user moves the cubixd to select a face |
onRestCurve | Curve | Curves.fastOutSlowIn |
On Restore Curve. This parameter sets the curve that should have the restore animation. Understand the restore animation as the animation that executes after the selection of a face occurs to restore the cubixd to its starting position |
onSelecCurve | Curve | Curves.fastOutSlowIn |
On Selection Curve. This parameter sets the curve that have the selection animation. Understand the selection animation as the animation that triggers just right when the debounce timer ends and triggers the selection |
onSelect | bool Function(SelectedSide) | null | On Select. The callback that should trigger when a user selects a face |
restDuration | Duration | Duration(miliseconds: 800) |
Restore Duration. The duration that the restore animation should take |
right * | Widget | – | The widget that should be displayed on the right face side |
selDuration | Duration | Duration(miliseconds: 400) |
Select Duration. The duration that the selection animation should take. Understand the selection animation as the animation that occurs just right after the debouncer triggers |
sensitivityFac | double | 1.0 | Sensitivity Factor. Just like a mouse has a sensitivity when you move it. The cubixd has a sensitivity too. It’s ideal that this value should be near 1 and not 0 or less. The greater its value, the sensitivity will be too |
shadow | bool | true | Shadow. Defines if the cubixd should have shadow. Take in mind that if there is no shadow, the cubixd it won’t nicely move up and down at all (and the final height that this widget take up will be reduced) |
simplePosAnim | SimpleAnimRequirements | SimpleAnimRequirements(duration: const Duration(seconds: 10), xBegin: -pi / 4, xEnd: (7*pi)/4, yBegin: pi / 4, yEnd: pi / 4, reverseWhenDone: false, infinite: true) |
If you don’t want to set advanced options with an AnimationController you could use this parameter to set a few parameters to get your cubixd moving c: You can read more information about this parameter down below |
size * | double | – | The width and height that each face should have |
stars | bool | true | If the colorful stars should appear right after a face is selected |
top * | Widget | – | The widget that should be displayed on the top face side |
onSelect
A 3d cube should always have 6 faces, but maybe you only want 5 faces. You could have 5 faces ready to be selected and 1 out of service. that’s what was thought when considering this parameter: A callback that sends the face that was selected, and if this callback returns false that face can’t be selected, otherwise it cans
AnimatedCubixD(
...
onSelected: (SelectedSide opt) {
switch (opt) {
case SelectedSide.back:
return true;
case SelectedSide.top:
return true;
case SelectedSide.front:
return true;
case SelectedSide.bottom:
return false; // out of service
case SelectedSide.right:
return true;
case SelectedSide.left:
return true;
case SelectedSide.none:
// You can do something else
return false; // Nothing will happend if you return true at this point
default:
throw Exception("Unimplemented option");
}
}
...
),
If this parameter isn’t set (null). The user won’t be able to move the cubixd
As a result we obtain
advancedXYposAnim
AnimRequirements
Parameter | Type | Default value | Description |
---|---|---|---|
controller * | AnimationController | – | The AnimationController that should be used on the main animation. Here you can set the duration of the main animation |
xAnimation * | Animation | – | The Animation that should be used on the horizontal axis. Here you set the x start angle and the x end angle (in radians) |
yAnimation * | Animation | – | The Animation that should be used on the vertical axis. Here you set the y start angle and the y end angle (in radians) |
Example
...
late final AnimationController _mainCtrl;
late final Animation<double> _xAnimation;
late final Animation<double> _yAnimation;
...
@override
void initState(){
_mainCtrl = AnimationController(vsync: this, duration: const Duration(seconds: 10));
_xAnimation = Tween<double>(begin: -pi / 4, end: pi * 2 - pi / 4).animate(_mainCtrl);
_yAnimation = Tween<double>(begin: pi / 4, end: pi / 4).animate(_mainCtrl);
_mainCtrl.addStatusListener((status) {
if (status == AnimationStatus.completed) {
_mainCtrl.reverse();
} else if (status == AnimationStatus.dismissed) {
_mainCtrl.forward();
}
print(status);
});
_mainCtrl.forward();
super.initState();
}
...
AnimatedCubixD(
...
advancedXYposAnim: AnimRequirements(
controller: _mainCtrl,
xAnimation: _xAnimation,
yAnimation: _yAnimation,
),
...
),
...
@override
void dispose(){
_mainCtrl.dispose();
super.dispose();
}
...
buildOnSelect
This is probably the most complex parameter of all this package, so I recommend you to read this section the times you need it
What if you would like to have another splash animation when you select a face? With this parameter, you could do so. When the user selects a face, another animation is running to place the de cubixd to the selected face, I call this “select animation” and this animation is completely different from the main animation, for that reason it has another AnimationController.
AnimatedCubixD use 3 different controllers for 3 different animations:
-
Main animation. It uses the controller you may or not passed to AnimatedCubixD from
advancedXYposAnim
parameter, if you didn’t passed him any controller at all, it will create it himself and execute forward and dispose methods automatically -
Select animation. It creates its controller only if
onSelect
parameter isn’t null. This is used to execute the animation that plays to adjust the exact angles of the selected face -
Restore animation. It creates its controller only if
onSelect
parameter isn’t null. This is used to execute the animation that plays to adjust the cubixd to its initial position after a face was selected by the user
With this in mind, the callback of this parameter sends 2 arguments: size (double) and the select animation controller (AnimationController
),
this callback expects you to return a widget that will display right after user selects a face
import 'dart:math';
import 'package:cubixd/cubixd.dart';
...
AnimatedCubixD(
...
buildOnSelect: (double size, AnimationController ctrl) => CircleStar(ctrl: ctrl, size: size),
stars: false,
...
),
...
class _Animations {
final Animation<double> xAnim;
final Animation<double> yAnim;
final double size;
_Animations(this.xAnim, this.yAnim, this.size);
}
class CircleStar extends StatelessWidget {
final CurvedAnimation _curvedA;
final double overflowQ = 0.4;
final List<_Animations> _starsA = [];
final List<int> _minMax = [20, 35];
CircleStar({
Key? key,
required AnimationController ctrl,
required double size,
}) : _curvedA = CurvedAnimation(parent: ctrl, curve: Curves.easeOutCubic),
super(key: key) {
_initParams(size);
ctrl.addStatusListener((status) {
if (status == AnimationStatus.completed) {
_initParams(size);
}
});
}
void _initParams(double size) {
_starsA.clear();
final int length = Random().nextInt(_minMax[1] - _minMax[0]) + _minMax[0];
final double overflow = overflowQ * size;
for (int i = 0; i < length; i++) {
final double shapeSize = Random().nextDouble() * size * 0.8;
final double lPos = Random().nextDouble() * size;
final double tPos = Random().nextDouble() * size;
final double xEnd;
final double yEnd;
if (-lPos.abs() % size < -tPos.abs() % size) {
xEnd = lPos > size / 2 ? size + overflow : -overflow;
yEnd = xEnd * (tPos / xEnd);
} else {
yEnd = tPos > size / 2 ? size + overflow : -overflow;
xEnd = yEnd / (tPos / lPos);
}
_starsA.add(_Animations(
Tween<double>(begin: lPos, end: xEnd).animate(_curvedA),
Tween<double>(begin: tPos, end: yEnd).animate(_curvedA),
shapeSize,
));
}
}
List<Widget> get _buildList {
final List<Widget> list = [];
final Color color = Color((Random().nextDouble() * 0xFFFFFF).toInt());
for (int i = 0; i < _starsA.length; i++) {
list.add(Positioned(
left: 0,
top: 0,
child: Transform.translate(
offset: Offset(_starsA[i].xAnim.value, _starsA[i].yAnim.value),
child: Transform.rotate(
angle: -4 * pi * _curvedA.value,
child: ClipPath(
clipper: _CircleStarClip(),
child: Container(
color: color.withOpacity(1 - _curvedA.value),
height: _starsA[i].size,
width: _starsA[i].size,
),
),
),
),
));
}
return list;
}
@override
Widget build(BuildContext context) {
return AnimatedBuilder(
animation: _curvedA,
builder: (_, __) {
return Stack(children: _buildList);
},
);
}
}
class _CircleStarClip extends CustomClipper<Path> {
static const _starShrink = 2;
static const _starSides = 5;
static const _deg90 = pi / 2;
@override
Path getClip(Size size) {
final double bigRad = size.width / 2;
final double centerX = size.width / 2;
final double centerY = size.height / 2;
final double smallRad = bigRad / _starShrink;
const double sides = 2 * pi / _starSides;
final Path path = Path()..moveTo(size.width / 2, 0);
for (int i = 0; i < _starSides + 1; i++) {
path.lineTo(cos(sides * i + _deg90) * bigRad + centerX,
sin(sides * i + _deg90) * bigRad + centerY);
path.lineTo(cos(sides * i + _deg90) * smallRad + centerX,
sin(sides * i + _deg90) * smallRad + centerY);
}
return path..close();
}
@override
bool shouldReclip(covariant CustomClipper<Path> oldClipper) => false;
}
...
Hints:
- You could have your custom animation and the default one (the starts) running together
- You could code your custom animation with a
StatefulWidget
instead of aStatelessWidget
and use a more orthodox method
Here’s a slow motion of the result:
simplePosAnim
Previously, we stated that the default value that this parameter takes is:
import 'package:cubixd/cubixd.dart';
...
simplePosAnim: SimpleAnimRequirements(
duration: const Duration(seconds: 10),
infinite: true,
reverseWhenDone: false,
xBegin: -pi / 4,
xEnd: (7*pi)/4,
yBegin: pi / 4,
yEnd: pi / 4,
),
...
cubixd takes that values as the default animation only if this parameter (simplePosAnim) and advancedXYposAnim are’nt set
Another example
import 'package:cubixd/cubixd.dart';
...
simplePosAnim: SimpleAnimRequirements(
duration: const Duration(seconds: 11),
infinite: true,
reverseWhenDone: true,
xBegin: pi / 4,
xCurve: Curves.ease,
xEnd: 2 * pi,
yBegin: -pi / 4,
yCurve: Curves.ease,
yEnd: 4 * pi,
),
...
SimpleAnimRequirements
Parameter | Type | Default value | Description |
---|---|---|---|
duration * | Duration | – | The duration that the main animation should have |
infinite | bool | true | If the main animation should play infinitely |
reverseWhenDone | bool | false | If the cubixd should play backwards when it finishes |
xBegin * | double | – | The horizontal angle (in radians) that should be set at the start of the animation |
xCurve | Curve | Curves.linear |
The curve that should have the main animation on its horizontal axis |
xEnd * | double | – | The horizontal angle (in radians) that should be set at the end of the animation |
yBegin * | double | – | The vertical angle (in radians) that should be set at the start of the animation |
yCurve | Curve | Curves.linear |
The curve that should have the main animation on its vertical axis |
yEnd * | double | – | The vertical angle (in radians) that should be set at the end of the animation |
CubixD
CubixD is the widget that displays the 3d cube. The shadow and the rotating animation are’nt part of this widget, but the selection of a face it is part of this widget (almost), by the exception that the animation that plays to place the cubixd to its exact correct position of the face it’sn’t part of this widget
Parameters
Parameter | Type | Default value | Description |
---|---|---|---|
back * | Widget | – | The widget that should be displayed on the back face side |
bottom * | Widget | – | The widget that should be displayed on the bottom face side |
debounceTime | Duration | Duration(milliseconds: 500) |
Debonce Time. The cubixd works with a debouncer, this means that when you constantly move the cubixd to select a face it won’t execute the selection until you leave it static with a valid face and wait the duration specified here it will trigger the selection, otherwise if you move it just before time runs, it will “bounce” the selection and count back from 0 this time specified here |
delta * | Vector2 | – | The horizontal and vertical angle (in radians) of the cubixd. You can read more about this down below |
front * | Widget | – | The widget that should be displayed on the front face side |
left * | Widget | – | The widget that should be displayed on the left face side |
onPanUpdate | VoidCallback | null | On Pan Update. This is a callback that executes whatever the user moves the cubixd to select a face |
onSelected | void Function(SelectedSide opt, Vector2 delta) | null | On Selected. The callback that should trigger when a user selects a face |
right * | Widget | – | The widget that should be displayed on the right face side |
sensitivityFac | double | 1.0 | Sensitivity Factor. Just like a mouse has a sensitivity when you move it. The cubixd has a sensitivity too. It’s ideal that this value should be near 1 and not 0 or less. The greater its value, the sensitivity will be too |
size * | double | – | The width and height that each face should have |
top * | Widget | – | The widget that should be displayed on the top face side |
delta
This parameter represents the horizontal and vertical angle of the cubixd (in radians) AnimatedCubixD uses this parameter with an AnimatedBuilder to get the animation running by updating every time its respective controller indicates it
import 'package:vector_math/vector_math_64.dart' show Vector2;
import 'package:cubixd/cubixd.dart';
...
CubixD(
...
delta: Vector2(verticalAngle, horizontalAngle)
...
),
...
Here’s an example
import 'package:cubixd/cubixd.dart';
...
CubixD(
size: 200.0,
delta: Vector2(pi / 4, pi / 4),
onSelected: (SelectedSide opt, Vector2 delta) {
print('On selected callback:\n\topt = ${opt}\n\tdelta = ${delta}');
},
front: ...,
back: ...,
right: ...,
left: ...,
top: ...,
bottom: ...,
),
...
As a result we obtain:
Extras
SelectedSide
SelectedSide it’s an enum that helps to know which side has been selected:
enum SelectedSide { front, back, right, left, top, bottom, none }
Calculations are’nt exact
Be aware that when you want to get a specific angle. The horizontal angle “changes” the direction based on the vertical angle, here’s an example of this:
If the vertical angle is between -90° and 90°. A horizontal angle grater than 0 (positive) has a direction from right to left.
Otherwise, if the vertical angle is grater than 90°. A horizontal angle grater than 0 (positive) has a direction from left to right.
TODO
-
Maybe attach the front, back, right, left, top and bottom widgets would be better to do with a widget list
List<Widget>
-
Offer the possibility to control the up and down animation