docs: added a timers page, added a note in setting_status for timers (#1120)

Author: Jaskowicz1

docpages/example_code/timers_example1.cpp

@@ -0,0 +1,21 @@
+#include <dpp/dpp.h>
+
+int main() {
+	/* Create the bot */
+	dpp::cluster bot("token");
+
+	bot.on_log(dpp::utility::cout_logger());
+
+	bot.on_ready([&bot](const dpp::ready_t& event) {
+		/* Create a timer when the bot starts. */
+		bot.start_timer([&bot](const dpp::timer& timer){
+			/* Create a timer when the bot starts. */
+			bot.request("https://dpp.dev/DPP-Logo.png", dpp::m_get, [&bot](const dpp::http_request_completion_t& callback) {
+				/* Create a message to our desired channel, with the D++ logo. */
+				bot.message_create(dpp::message(1140010849432522843, "").add_file("image.png", callback.body));
+			});
+		}, 10); /* Do it every 10 seconds. Timers also start with this delay. */
+	});
+
+	bot.start(dpp::st_wait);
+}

docpages/example_code/timers_example2.cpp

@@ -0,0 +1,23 @@
+#include <dpp/dpp.h>
+
+int main() {
+	/* Create the bot */
+	dpp::cluster bot("token");
+
+	bot.on_log(dpp::utility::cout_logger());
+
+	bot.on_ready([&bot](const dpp::ready_t& event) {
+		/* Create a timer when the bot starts. */
+		bot.start_timer([&bot](const dpp::timer& timer) {
+			/* Create a timer when the bot starts. */
+			bot.request("https://dpp.dev/DPP-Logo.png", dpp::m_get, [&bot, timer](const dpp::http_request_completion_t& callback) {
+				/* Create a message to our desired channel, with the D++ logo. */
+				bot.message_create(dpp::message(1140010849432522843, "").add_file("image.png", callback.body));
+				/* Stop the timer by passing the timer handle in. */
+				bot.stop_timer(timer);
+			});
+		}, 10); /* Do it every 10 seconds. Timers also start with this delay. */
+	});
+
+	bot.start(dpp::st_wait);
+}

docpages/example_code/timers_example3.cpp

@@ -0,0 +1,69 @@
+#include <dpp/dpp.h>
+
+std::map<dpp::snowflake, dpp::timer> user_timers{};
+
+int main() {
+	/* Create the bot */
+	dpp::cluster bot("token");
+
+	bot.on_log(dpp::utility::cout_logger());
+
+	/* The event is fired when someone issues your commands */
+	bot.on_slashcommand([&bot](const dpp::slashcommand_t& event) {
+		/* Check which command they ran */
+		if (event.command.get_command_name() == "start_timer") {
+			/* Does user_timers contain the user id? */
+			if (user_timers.find(event.command.usr.id) != user_timers.end()) {
+				event.reply("You've already got an in-progress timer!");
+				return;
+			}
+
+			/* Create a copy of the channel_id to copy in to the timer lambda. */
+			dpp::snowflake channel_id = event.command.channel_id;
+
+			/* Start the timer and save it to a local variable. */
+			dpp::timer timer = bot.start_timer([&bot, channel_id](const dpp::timer& timer) {
+				bot.message_create(dpp::message(channel_id, "This is a timed message! Use /stop_timer to stop this!"));
+			}, 10);
+
+			/*
+			 * Add the timer to user_timers.
+			 * As dpp::timer is just size_t (essentially the timer's ID), it's perfectly safe to copy it in.
+			 */
+			user_timers.emplace(event.command.usr.id, timer);
+
+			event.reply("Started a timer every 10 seconds!");
+		}
+
+		if(event.command.get_command_name() == "stop_timer") {
+			/* Is user_timers empty? */
+			if (user_timers.empty()) {
+				event.reply("There are no timers currently in-progress!");
+				return;
+			} else if (user_timers.find(event.command.usr.id) == user_timers.end()) { /* Does user_timers not contain the user id? */
+				event.reply("You've don't currently have a timer in-progress!");
+				return;
+			}
+
+			/* Stop the timer. */
+			bot.stop_timer(user_timers[event.command.usr.id]);
+			/* Remove the timer from user_timers. */
+			user_timers.erase(event.command.usr.id);
+
+			event.reply("Stopped your timer!");
+		}
+	});
+
+	bot.on_ready([&bot](const dpp::ready_t& event) {
+		if (dpp::run_once<struct register_bot_commands>()) {
+			/* Create a new global command on ready event. */
+			dpp::slashcommand start_timer("start_timer", "Start a 10 second timer!", bot.me.id);
+			dpp::slashcommand stop_timer("stop_timer", "Stop your 10 second timer!", bot.me.id);
+
+			/* Register the commands. */
+			bot.global_bulk_command_create({ start_timer, stop_timer });
+		}
+	});
+
+	bot.start(dpp::st_wait);
+}

docpages/example_programs/misc.md

@@ -12,3 +12,4 @@ This section lists examples that do not fit neatly into any of the categories ab
 * \subpage checking-member-permissions
 * \subpage setting_status
 * \subpage using-emojis
+* \subpage using_timers

docpages/example_programs/misc/setting_status.md

@@ -17,6 +17,8 @@ You can also play around with dpp::at_game, changing it to something like dpp::a
 
 Now, let's cover setting the bot status to say `Playing with x guilds!` every two minutes.
 
+\note This example uses timers to update the status every 2 minutes. If you aren't familiar with D++'s own timers, please read \ref using_timers "this page on timers" before you continue.
+
 \include{cpp} setting_status2.cpp
 
 If you followed that well, your bot should now say this on members list!

docpages/example_programs/misc/using_timers.md

@@ -0,0 +1,27 @@
+\page using_timers Using Timers
+
+Timers are a great way to run something every x seconds, from setting the bot's status, to maybe even doing a http request! Luckily, D++ makes this incredibly easy by providing an easy-to-use timer system! This tutorial will show you a couple examples on how to use timers!
+
+First, we'll cover sending the D++ logo every 10 seconds!
+
+\include{cpp} timers_example1.cpp
+
+If all went well, you should get the D++ logo sent every 10 seconds to your desired channel!
+
+\image html timers_example1.png
+
+Now, let's make the same timer a one-shot timer, meaning it will only run once!
+
+\include{cpp} timers_example2.cpp
+
+Great! Now we've learnt the basics of timers and how to stop them!
+
+To finish off, let's make a timer that you can start and stop with commands. This example will store the timer in a map where the user is the owner of the timer!
+
+\include{cpp} timers_example3.cpp
+
+If that went well, it should work something like below!
+
+\image html timers_example3.png
+
+Great, now you've learnt how to store timers to manage at a later point!