feat: components v2 (#1381)

Author: braindigitalis

docpages/example_code/components_v2.cpp

@@ -0,0 +1,71 @@
+#include <dpp/dpp.h>
+
+int main() {
+	dpp::cluster bot("token");
+
+	bot.on_log(dpp::utility::cout_logger());
+
+	bot.on_ready([&bot](const auto& event) {
+		if (dpp::run_once<struct boot_t>()) {
+			bot.global_bulk_command_create({ dpp::slashcommand("cats", "I love cats", bot.me.id) });
+		}
+	});
+
+	bot.on_button_click([](const dpp::button_click_t& event) {
+		event.reply("You declared your love for cats by clicking button id: " + event.custom_id);
+	});
+
+	/* This is a detailed example of using many different types of component. For a complete
+	 * list of supported components, see the Discord developer documentation and the definition
+	 * of dpp::component_type.
+	 */
+	bot.register_command("cats", [](const dpp::slashcommand_t& e) {
+		e.reply(dpp::message()
+			/* Remember to set the message flag for components v2 */
+			.set_flags(dpp::m_using_components_v2).add_component_v2(
+			/* Reply with a container... */
+			dpp::component()
+				.set_type(dpp::cot_container)
+				.set_accent(dpp::utility::rgb(255, 0, 0))
+				.set_spoiler(true)
+				.add_component_v2(
+					/* ...which contains a section... */
+					dpp::component()
+						.set_type(dpp::cot_section)
+						.add_component_v2(
+							/* ...with text... */
+							dpp::component()
+								.set_type(dpp::cot_text_display)
+								.set_content("Click if you love cats")
+						)
+						.set_accessory(
+							/* ...and an accessory button to the right */
+							dpp::component()
+								.set_type(dpp::cot_button)
+								.set_label("Click me")
+								.set_style(dpp::cos_danger)
+								.set_id("button")
+						)
+				)
+		).add_component_v2(
+			/* ... with a large visible divider between... */
+			dpp::component()
+				.set_type(dpp::cot_separator)
+				.set_spacing(dpp::sep_large)
+				.set_divider(true)
+		).add_component_v2(
+			/* ... followed by a media gallery... */
+			dpp::component()
+				.set_type(dpp::cot_media_gallery)
+				.add_media_gallery_item(
+					/* ...containing one cat pic (obviously) */
+					dpp::component()
+						.set_type(dpp::cot_thumbnail)
+						.set_description("A cat")
+						.set_thumbnail("https://www.catster.com/wp-content/uploads/2023/11/Beluga-Cat-e1714190563227.webp")
+				)
+		));
+	});
+
+	bot.start(dpp::st_wait);
+}

docpages/example_programs/interactions_and_components/components-menu.md

@@ -7,3 +7,4 @@ Components are anything that can be attached to a message or a \ref modal-dialog
 * \subpage components3
 * \subpage default_select_value
 * \subpage editing_message_after_click
+* \subpage components_v2

docpages/example_programs/interactions_and_components/components/components_v2.md

@@ -0,0 +1,28 @@
+\page components_v2 Components V2
+
+From March 2025 onwards Discord have released a **new way to handle components** in a Discord application/bot. The previous methods of working with components remain, and are accessible without
+any changes in D++. If you want to use the new style of components you may do so, which gives far greater control over how message containing images, buttons, sections etc are formatted.
+
+Components are attached to any message or interaction reply, via the dpp::message::add_component() or dpp::message::add_component_v2() function. You must also be sure to set the flag
+dpp::m_using_components_v2 on the message to allow the new features.
+
+When using components v2, the following limits apply which do not apply with components v1 or traditional embeds:
+
+* Setting the message `content` or `embeds` will not be allowed (components v2 replaces the functionality)
+* You can have a maximum of 10 top level components per message. The maximum number of nested components is 30.
+* Audio files are not supported at present
+* Text preview for text/plain files is not supported
+* URLs will not have embeds generated for them
+* The total length of the entire message, including all components within and the content of those components, is 4000 UTF-8 characters.
+
+Here is a detailed example of how to create components v2 replies.
+
+\warning Please note that where you would use add_component() previously, you **should** use add_component_v2() (on component or message objects). This is because the v2 version will not automatically add action rows, which is a limitation which has been removed in version 2 but is still required for version 1.
+
+\include{cpp} components_v2.cpp
+
+There are many new component types, for a complete list see the definition of dpp::component_type
+
+If you run the example program above, you will be shown a message containing your components:
+
+\image html components.gif