diff --git a/docpages/example_code/timers_example1.cpp b/docpages/example_code/timers_example1.cpp new file mode 100644 index 0000000000..b3777f11cc --- /dev/null +++ b/docpages/example_code/timers_example1.cpp @@ -0,0 +1,21 @@ +#include + +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); +} diff --git a/docpages/example_code/timers_example2.cpp b/docpages/example_code/timers_example2.cpp new file mode 100644 index 0000000000..07b02ed267 --- /dev/null +++ b/docpages/example_code/timers_example2.cpp @@ -0,0 +1,23 @@ +#include + +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); +} diff --git a/docpages/example_code/timers_example3.cpp b/docpages/example_code/timers_example3.cpp new file mode 100644 index 0000000000..697e243457 --- /dev/null +++ b/docpages/example_code/timers_example3.cpp @@ -0,0 +1,69 @@ +#include + +std::map 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()) { + /* 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); +} diff --git a/docpages/example_programs/misc.md b/docpages/example_programs/misc.md index 9e1151fd46..448203285a 100644 --- a/docpages/example_programs/misc.md +++ b/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 making_timers diff --git a/docpages/example_programs/misc/making_timers.md b/docpages/example_programs/misc/making_timers.md new file mode 100644 index 0000000000..f561347a97 --- /dev/null +++ b/docpages/example_programs/misc/making_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! \ No newline at end of file diff --git a/docpages/example_programs/misc/setting_status.md b/docpages/example_programs/misc/setting_status.md index 088d7a1dfc..16796887b5 100644 --- a/docpages/example_programs/misc/setting_status.md +++ b/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! diff --git a/docpages/images/timers_example1.png b/docpages/images/timers_example1.png new file mode 100644 index 0000000000..644303ceab Binary files /dev/null and b/docpages/images/timers_example1.png differ diff --git a/docpages/images/timers_example3.png b/docpages/images/timers_example3.png new file mode 100644 index 0000000000..0d7089dce3 Binary files /dev/null and b/docpages/images/timers_example3.png differ