Formspecs: Add starting frame to `animated_image` (#9411)

doc/lua_api.txt

@@ -2120,27 +2120,29 @@ Elements
 ### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>;<fontcolor>]`
 
 * Adds tooltip for an element
-* `<bgcolor>` tooltip background color as `ColorString` (optional)
-* `<fontcolor>` tooltip font color as `ColorString` (optional)
+* `bgcolor` tooltip background color as `ColorString` (optional)
+* `fontcolor` tooltip font color as `ColorString` (optional)
 
 ### `tooltip[<X>,<Y>;<W>,<H>;<tooltip_text>;<bgcolor>;<fontcolor>]`
 
 * Adds tooltip for an area. Other tooltips will take priority when present.
-* `<bgcolor>` tooltip background color as `ColorString` (optional)
-* `<fontcolor>` tooltip font color as `ColorString` (optional)
+* `bgcolor` tooltip background color as `ColorString` (optional)
+* `fontcolor` tooltip font color as `ColorString` (optional)
 
 ### `image[<X>,<Y>;<W>,<H>;<texture name>]`
 
 * Show an image
 
-### `animated_image[<X>,<Y>;<W>,<H>;<texture name>:<frame count>,<frame duration>]`
+### `animated_image[<X>,<Y>;<W>,<H>;<name>;<texture name>;<frame count>;<frame duration>;<frame start>]`
 
 * Show an animated image. The image is drawn like a "vertical_frames" tile
-    animation (See Tile animation definition), but uses a frame count/duration
+    animation (See [Tile animation definition]), but uses a frame count/duration
     for simplicity
-* `<texture name>` is the image to use
-* `<frame count>` is the number of frames animating the image
-* `<frame duration>` is in milliseconds
+* `name`: Element name to send when an event occurs. The event value is the index of the current frame.
+* `texture name`: The image to use.
+* `frame count`: The number of frames animating the image.
+* `frame duration`: Milliseconds between each frame. `0` means the frames don't advance.
+* `frame start` (Optional): The index of the frame to start on. Default `1`.
 
 ### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
 
@@ -2575,6 +2577,7 @@ Setting a property to nothing will reset it to the default value. For example:
 
 Some types may inherit styles from parent types.
 
+* animated_image, inherits from image
 * button
 * button_exit, inherits from button
 * checkbox
@@ -4325,6 +4328,7 @@ Call these functions only at load time!
       is a table containing each formspecs element value (as string), with
       the `name` parameter as index for each. The value depends on the
       formspec element type:
+        * `animated_image`: Returns the index of the current frame.
         * `button` and variants: If pressed, contains the user-facing button
           text as value. If not pressed, is `nil`
         * `field`, `textarea` and variants: Text in the field

games/minimal/mods/test/formspec.lua

@@ -17,7 +17,7 @@ local clip_fs = [[
 	scrollbar[0,9;3,0.8;horizontal;x9;3]
 	tablecolumns[text;text]
 	table[0,10;3,1;x10;one,two,three,four;1]
-	animated_image[0,11;3,1;test_animation.png:4,100]
+	animated_image[-0.5,11;4.5,1;;test_animation.png;4;100]
 ]]
 
 
@@ -172,11 +172,19 @@ local pages = {
 		[[
 			formspec_version[3]
 			size[12,12]
-			animated_image[0.5,0.5;1,1;test_animation.png:4,100]
-			animated_image[1.75,0.5;1,1;test_animation.png:100,100]
-			animated_image[0.5,1.75;1,1;test_animation.jpg:4,100]
-			animated_image[3,0.5;5,2;test_animation.png:4,100]
-			animated_image[3,2.75;5,2;test_animation.jpg:4,100]
+			animated_image[0.5,0.5;1,1;;test_animation.png;4;100]
+			animated_image[0.5,1.75;1,1;;test_animation.jpg;4;100]
+			animated_image[1.75,0.5;1,1;;test_animation.png;100;100]
+			animated_image[3,0.5;1,1;ani_img_1;test_animation.png;4;1000]
+			button[4.25,0.5;1,1;ani_btn_1;Current
+Number]
+			animated_image[3,1.75;1,1;ani_img_2;test_animation.png;4;1000;2]
+			button[4.25,1.75;1,1;ani_btn_2;Current
+Number]
+			animated_image[3,3;1,1;;test_animation.png;4;0]
+			animated_image[3,4.25;1,1;;test_animation.png;4;0;3]
+			animated_image[5.5,0.5;5,2;;test_animation.png;4;100]
+			animated_image[5.5,2.75;5,2;;test_animation.jpg;4;100]
 		]]
 }
 
@@ -198,6 +206,11 @@ minetest.register_on_player_receive_fields(function(player, formname, fields)
 		return true
 	end
 
+	if fields.ani_img_1 and fields.ani_btn_1 then
+		minetest.chat_send_all(fields.ani_img_1)
+	elseif fields.ani_img_2 and fields.ani_btn_2 then
+		minetest.chat_send_all(fields.ani_img_2)
+	end
 end)
 
 minetest.register_node("test:node", {

src/gui/guiAnimatedImage.cpp

@@ -4,42 +4,24 @@
 #include "client/tile.h" // ITextureSource
 #include "log.h"
 #include "porting.h"
+#include "util/string.h"
 #include <string>
+#include <vector>
 
 GUIAnimatedImage::GUIAnimatedImage(gui::IGUIEnvironment *env, gui::IGUIElement *parent,
-		s32 id, const core::rect<s32> &rectangle, const std::string &name,
-		ISimpleTextureSource *tsrc) :
-		gui::IGUIElement(gui::EGUIET_ELEMENT, env, parent, id, rectangle),
-		m_name(name), m_tsrc(tsrc), m_texture(nullptr), m_global_time(0),
-		m_frame_idx(0), m_frame_count(1), m_frame_duration(1), m_frame_time(0)
+	s32 id, const core::rect<s32> &rectangle, const std::string &texture_name,
+	s32 frame_count, s32 frame_duration, ISimpleTextureSource *tsrc) :
+	gui::IGUIElement(gui::EGUIET_ELEMENT, env, parent, id, rectangle), m_tsrc(tsrc)
 {
-	// Expected format: "texture_name:frame_count,frame_duration"
-	// If this format is not met, the string will be loaded as a normal texture
+	m_texture = m_tsrc->getTexture(texture_name);
 
-	std::string::size_type colon_position = name.find(':', 0);
-	std::string::size_type comma_position = name.find(',', 0);
-
-	if (comma_position != std::string::npos &&
-			colon_position != std::string::npos &&
-			comma_position < name.size()) {
-		m_texture = m_tsrc->getTexture(name.substr(0, colon_position));
-
-		m_frame_count = std::max(stoi(name.substr(
-					colon_position + 1, comma_position - colon_position - 1)), 1);
-
-		m_frame_duration = std::max(stoi(name.substr(comma_position + 1)), 1);
-	} else {
-		// Leave the count/duration and display a static image
-		m_texture = m_tsrc->getTexture(name);
-		errorstream << "animated_image[]: Invalid texture format " << name <<
-			". Expected format: texture_name:frame_count,frame_duration" << std::endl;
-	}
+	m_frame_count    = std::max(frame_count,    1);
+	m_frame_duration = std::max(frame_duration, 0);
 
 	if (m_texture != nullptr) {
 		core::dimension2d<u32> size = m_texture->getOriginalSize();
-		if (size.Height < (u64)m_frame_count) {
+		if (size.Height < (u64)m_frame_count)
 			m_frame_count = size.Height;
-		}
 	} else {
 		// No need to step an animation if we have nothing to draw
 		m_frame_count = 1;
@@ -58,13 +40,13 @@ void GUIAnimatedImage::draw()
 		core::dimension2d<u32> size = m_texture->getOriginalSize();
 		size.Height /= m_frame_count;
 
-		draw2DImageFilterScaled( driver, m_texture, AbsoluteRect,
-				core::rect<s32>(core::position2d<s32>(0, size.Height * m_frame_idx), size),
-				NoClip ? nullptr : &AbsoluteClippingRect, colors, true);
+		draw2DImageFilterScaled(driver, m_texture, AbsoluteRect,
+			core::rect<s32>(core::position2d<s32>(0, size.Height * m_frame_idx), size),
+			NoClip ? nullptr : &AbsoluteClippingRect, colors, true);
 	}
 
 	// Step the animation
-	if (m_frame_count > 1) {
+	if (m_frame_count > 1 && m_frame_duration > 0) {
 		// Determine the delta time to step
 		u64 new_global_time = porting::getTimeMs();
 		if (m_global_time > 0)
@@ -81,3 +63,11 @@ void GUIAnimatedImage::draw()
 		m_frame_time %= m_frame_duration;
 	}
 }
+
+
+void GUIAnimatedImage::setFrameIndex(s32 frame)
+{
+	s32 idx = std::max(frame, 0);
+	if (idx > 0 && idx < m_frame_count)
+		m_frame_idx = idx;
+}

src/gui/guiAnimatedImage.h

@@ -1,26 +1,28 @@
 #pragma once
 
 #include "irrlichttypes_extrabloated.h"
-#include "util/string.h"
+#include <string>
 
 class ISimpleTextureSource;
 
 class GUIAnimatedImage : public gui::IGUIElement {
 public:
-	GUIAnimatedImage(gui::IGUIEnvironment *env, gui::IGUIElement *parent, s32 id,
-			const core::rect<s32> &rectangle, const std::string &name,
-			ISimpleTextureSource *tsrc);
+	GUIAnimatedImage(gui::IGUIEnvironment *env, gui::IGUIElement *parent,
+		s32 id, const core::rect<s32> &rectangle, const std::string &texture_name,
+		s32 frame_count, s32 frame_duration, ISimpleTextureSource *tsrc);
 
 	virtual void draw() override;
 
+	void setFrameIndex(s32 frame);
+	s32 getFrameIndex() const { return m_frame_idx; };
+
 private:
-	std::string m_name;
 	ISimpleTextureSource *m_tsrc;
 
-	video::ITexture *m_texture;
-	u64 m_global_time;
-	s32 m_frame_idx;
-	s32 m_frame_count;
-	u64 m_frame_duration;
-	u64 m_frame_time;
+	video::ITexture *m_texture = nullptr;
+	u64 m_global_time = 0;
+	s32 m_frame_idx = 0;
+	s32 m_frame_count = 1;
+	u64 m_frame_duration = 1;
+	u64 m_frame_time = 0;
 };

src/gui/guiFormSpecMenu.cpp

@@ -784,16 +784,19 @@ void GUIFormSpecMenu::parseAnimatedImage(parserData *data, const std::string &el
 {
 	std::vector<std::string> parts = split(element, ';');
 
-	if (parts.size() != 3 &&
-			!(parts.size() > 3 && m_formspec_version > FORMSPEC_API_VERSION)) {
-		errorstream << "Invalid animated image element(" << parts.size()
-				<< "): '" << element << "'"  << std::endl;
+	if (parts.size() != 6 && parts.size() != 7 &&
+			!(parts.size() > 7 && m_formspec_version > FORMSPEC_API_VERSION)) {
+		errorstream << "Invalid animated_image element(" << parts.size()
+			<< "): '" << element << "'" << std::endl;
 		return;
 	}
 
-	std::vector<std::string> v_pos   = split(parts[0], ',');
-	std::vector<std::string> v_geom  = split(parts[1], ',');
-	std::string name = unescape_string(parts[2]);
+	std::vector<std::string> v_pos  = split(parts[0], ',');
+	std::vector<std::string> v_geom = split(parts[1], ',');
+	std::string name = parts[2];
+	std::string texture_name = unescape_string(parts[3]);
+	s32 frame_count = stoi(parts[4]);
+	s32 frame_duration = stoi(parts[5]);
 
 	MY_CHECKPOS("animated_image", 0);
 	MY_CHECKGEOM("animated_image", 1);
@@ -811,21 +814,26 @@ void GUIFormSpecMenu::parseAnimatedImage(parserData *data, const std::string &el
 	}
 
 	if (!data->explicit_size)
-		warningstream << "invalid use of animated_image without a size[] element" << std::endl;
+		warningstream << "Invalid use of animated_image without a size[] element" << std::endl;
 
 	FieldSpec spec(
-			"",
-			L"",
-			L"",
-			258 + m_fields.size()
+		name,
+		L"",
+		L"",
+		258 + m_fields.size()
 	);
+	spec.ftype = f_AnimatedImage;
+	spec.send = true;
 
 	core::rect<s32> rect = core::rect<s32>(pos, pos + geom);
 
-	gui::IGUIElement *e = new GUIAnimatedImage(Environment, this, spec.fid,
-			rect, name, m_tsrc);
+	GUIAnimatedImage *e = new GUIAnimatedImage(Environment, this, spec.fid,
+		rect, texture_name, frame_count, frame_duration, m_tsrc);
+
+	if (parts.size() >= 7)
+		e->setFrameIndex(stoi(parts[6]) - 1);
 
-	auto style = getStyleForElement("animated_image", spec.fname);
+	auto style = getStyleForElement("animated_image", spec.fname, "image");
 	e->setNotClipped(style.getBool(StyleSpec::NOCLIP, false));
 	e->drop();
 
@@ -3499,7 +3507,7 @@ void GUIFormSpecMenu::acceptInput(FormspecQuitMode quitmode=quit_mode_no)
 		}
 
 		for (const GUIFormSpecMenu::FieldSpec &s : m_fields) {
-			if(s.send) {
+			if (s.send) {
 				std::string name = s.fname;
 				if (s.ftype == f_Button) {
 					fields[name] = wide_to_utf8(s.flabel);
@@ -3508,14 +3516,13 @@ void GUIFormSpecMenu::acceptInput(FormspecQuitMode quitmode=quit_mode_no)
 					if (table) {
 						fields[name] = table->checkEvent();
 					}
-				}
-				else if(s.ftype == f_DropDown) {
-					// no dynamic cast possible due to some distributions shipped
-					// without rtti support in irrlicht
+				} else if (s.ftype == f_DropDown) {
+					// No dynamic cast possible due to some distributions shipped
+					// without rtti support in Irrlicht
 					IGUIElement *element = getElementFromId(s.fid, true);
 					gui::IGUIComboBox *e = NULL;
 					if ((element) && (element->getType() == gui::EGUIET_COMBO_BOX)) {
-						e = static_cast<gui::IGUIComboBox*>(element);
+						e = static_cast<gui::IGUIComboBox *>(element);
 					} else {
 						warningstream << "GUIFormSpecMenu::acceptInput: dropdown "
 								<< "field without dropdown element" << std::endl;
@@ -3529,10 +3536,9 @@ void GUIFormSpecMenu::acceptInput(FormspecQuitMode quitmode=quit_mode_no)
 							fields[name] = (*dropdown_values)[selected];
 						}
 					}
-				}
-				else if (s.ftype == f_TabHeader) {
-					// no dynamic cast possible due to some distributions shipped
-					// without rttzi support in irrlicht
+				} else if (s.ftype == f_TabHeader) {
+					// No dynamic cast possible due to some distributions shipped
+					// without rtti support in Irrlicht
 					IGUIElement *element = getElementFromId(s.fid, true);
 					gui::IGUITabControl *e = nullptr;
 					if ((element) && (element->getType() == gui::EGUIET_TAB_CONTROL)) {
@@ -3544,10 +3550,9 @@ void GUIFormSpecMenu::acceptInput(FormspecQuitMode quitmode=quit_mode_no)
 						ss << (e->getActiveTab() +1);
 						fields[name] = ss.str();
 					}
-				}
-				else if (s.ftype == f_CheckBox) {
-					// no dynamic cast possible due to some distributions shipped
-					// without rtti support in irrlicht
+				} else if (s.ftype == f_CheckBox) {
+					// No dynamic cast possible due to some distributions shipped
+					// without rtti support in Irrlicht
 					IGUIElement *element = getElementFromId(s.fid, true);
 					gui::IGUICheckBox *e = nullptr;
 					if ((element) && (element->getType() == gui::EGUIET_CHECK_BOX)) {
@@ -3560,10 +3565,9 @@ void GUIFormSpecMenu::acceptInput(FormspecQuitMode quitmode=quit_mode_no)
 						else
 							fields[name] = "false";
 					}
-				}
-				else if (s.ftype == f_ScrollBar) {
-					// no dynamic cast possible due to some distributions shipped
-					// without rtti support in irrlicht
+				} else if (s.ftype == f_ScrollBar) {
+					// No dynamic cast possible due to some distributions shipped
+					// without rtti support in Irrlicht
 					IGUIElement *element = getElementFromId(s.fid, true);
 					GUIScrollBar *e = nullptr;
 					if (element && element->getType() == gui::EGUIET_ELEMENT)
@@ -3577,8 +3581,17 @@ void GUIFormSpecMenu::acceptInput(FormspecQuitMode quitmode=quit_mode_no)
 						else
 							fields[name] = "VAL:" + os.str();
  					}
-				}
-				else {
+				} else if (s.ftype == f_AnimatedImage) {
+					// No dynamic cast possible due to some distributions shipped
+					// without rtti support in Irrlicht
+					IGUIElement *element = getElementFromId(s.fid, true);
+					GUIAnimatedImage *e = nullptr;
+					if (element && element->getType() == gui::EGUIET_ELEMENT)
+						e = static_cast<GUIAnimatedImage *>(element);
+
+					if (e)
+						fields[name] = std::to_string(e->getFrameIndex() + 1);
+				} else {
 					IGUIElement *e = getElementFromId(s.fid, true);
 					if (e)
 						fields[name] = wide_to_utf8(e->getText());

src/gui/guiFormSpecMenu.h

@@ -50,6 +50,7 @@ typedef enum {
 	f_Box,
 	f_ItemImage,
 	f_HyperText,
+	f_AnimatedImage,
 	f_Unknown
 } FormspecFieldType;