Add get_loops_left() function to Tween

Implements godotengine/godot-proposals#5141.

Adds a new get_loops_left() function to Tween, allowing developers to
reason about how many times a tweening sequence will repeat and whether
to expect finished or loop_finished as the next signal.

Co-authored-by: Tomek <[email protected]>

doc/classes/Tween.xml

@@ -131,6 +131,12 @@
 				Returns [code]true[/code] if the [Tween] still has [Tweener]s that haven't finished.
 			</description>
 		</method>
+		<method name="get_loops_left" qualifiers="const">
+			<return type="int" />
+			<description>
+				Returns the number of remaining loops for this [Tween] (see [method set_loops]). A return value of [code]-1[/code] indicates an infinitely looping [Tween], and a return value of [code]0[/code] indicates that the [Tween] has already finished.
+			</description>
+		</method>
 		<method name="get_total_elapsed_time" qualifiers="const">
 			<return type="float" />
 			<description>

scene/animation/tween.cpp

@@ -228,6 +228,14 @@ Ref<Tween> Tween::set_loops(int p_loops) {
 	return this;
 }
 
+int Tween::get_loops_left() const {
+	if (loops <= 0) {
+		return -1; // Infinite loop.
+	} else {
+		return loops - loops_done;
+	}
+}
+
 Ref<Tween> Tween::set_speed_scale(float p_speed) {
 	speed_scale = p_speed;
 	return this;
@@ -442,6 +450,7 @@ void Tween::_bind_methods() {
 
 	ClassDB::bind_method(D_METHOD("set_parallel", "parallel"), &Tween::set_parallel, DEFVAL(true));
 	ClassDB::bind_method(D_METHOD("set_loops", "loops"), &Tween::set_loops, DEFVAL(0));
+	ClassDB::bind_method(D_METHOD("get_loops_left"), &Tween::get_loops_left);
 	ClassDB::bind_method(D_METHOD("set_speed_scale", "speed"), &Tween::set_speed_scale);
 	ClassDB::bind_method(D_METHOD("set_trans", "trans"), &Tween::set_trans);
 	ClassDB::bind_method(D_METHOD("set_ease", "ease"), &Tween::set_ease);

scene/animation/tween.h

@@ -160,6 +160,7 @@ public:
 
 	Ref<Tween> set_parallel(bool p_parallel);
 	Ref<Tween> set_loops(int p_loops);
+	int get_loops_left() const;
 	Ref<Tween> set_speed_scale(float p_speed);
 	Ref<Tween> set_trans(TransitionType p_trans);
 	TransitionType get_trans();