github/Discord.Net
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update events.rst

Browse Source
This commit is contained in:
RogueException
2016-01-24 00:04:32 -04:00
parent f7150c289f
commit 76c8833539
1 changed files with 28 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/features/events.rst
View File

@@ -3,14 +3,26 @@ Events
Usage Usage
----- -----
Events in Discord.NET are raised using the Event system in c#. Most events are raised on the ``DiscordClient`` class. Messages from the Discord server are exposed via events on the DiscordClient class and follow the standard EventHandler<EventArgs> C# pattern.
Most events in Discord.NET explain theirselves by their name. .. warning::
Note that all synchronous code in an event handler will run on the gateway socket's thread and should be handled as quickly as possible.
Using the async-await pattern to let the thread continue immediately is recommended and is demonstrated in the examples below.
Connection State
----------------
Connection Events will be raised when the Connection State of your client changes.
.. warning::
You should not use DiscordClient.Connected to run code when your client first connects to Discord.
If you lose connection and automatically reconnect, this code will be ran again, which may lead to unexpected behavior.
Messages Messages
-------- --------
The Four Message Events (MessageReceived, Updated, Deleted, and Acknowledged) are raised when a message has been modified/created. MessageReceived, MessageUpdated and MessageDeleted are raised when a new message arrives, an existing one has been updated (by the user, or by Discord itself), or deleted.
MessageAcknowledged is only triggered in client mode, and occurs when a message is read on another device logged-in with your account.
Example of MessageReceived: Example of MessageReceived:
@@ -19,24 +31,24 @@ Example of MessageReceived:
// (Preface: Echo Bots are discouraged, make sure your bot is not running in a public server if you use them) // (Preface: Echo Bots are discouraged, make sure your bot is not running in a public server if you use them)
// Hook into the MessageReceived event using a Lambda // Hook into the MessageReceived event using a Lambda
_client.MessageReceived += (s, e) => { _client.MessageReceived += async (s, e) => {
// Check to make sure that the bot is not the author // Check to make sure that the bot is not the author
if (!e.Message.IsAuthor) if (!e.Message.IsAuthor)
// Echo the message back to the channel // Echo the message back to the channel
e.Channel.SendMessage(e.Message); await e.Channel.SendMessage(e.Message);
}; };
Users Users
----- -----
There are Six User Events: There are several user events:
UserBanned: A user has been banned from a Server UserBanned: A user has been banned from a server.
UserUnbanned: A user was unbanned UserUnbanned: A user was unbanned.
UserJoined: A user joins a server UserJoined: A user joins a server.
UserLeft: A user left (or was kicked) from a Server UserLeft: A user left (or was kicked from) a server.
UserIsTyping: A user in a channel starts typing UserIsTyping: A user in a channel starts typing.
UserUpdated: A user object was updated. (caused by a presence update, role/permission change, or a voice state update) UserUpdated: A user object was updated (presence update, role/permission change, or a voice state update).
.. note:: .. note::
UserUpdated Events include a ``User`` object for Before and After the change. UserUpdated Events include a ``User`` object for Before and After the change.
@@ -47,29 +59,20 @@ Examples:
.. code-block:: c# .. code-block:: c#
// Register a Hook into the UserBanned event using a Lambda // Register a Hook into the UserBanned event using a Lambda
_client.UserBanned += (s, e) => { _client.UserBanned += async (s, e) => {
// Create a Channel object by searching for a channel named '#logs' on the server the ban occurred in. // Create a Channel object by searching for a channel named '#logs' on the server the ban occurred in.
var logChannel = e.Server.FindChannels("logs").FirstOrDefault(); var logChannel = e.Server.FindChannels("logs").FirstOrDefault();
// Send a message to the server's log channel, stating that a user was banned. // Send a message to the server's log channel, stating that a user was banned.
logChannel.SendMessage($"User Banned: {e.User.Name}") await logChannel.SendMessage($"User Banned: {e.User.Name}");
}; };
// Register a Hook into the UserUpdated event using a Lambda // Register a Hook into the UserUpdated event using a Lambda
_client.UserUpdated += (s, e) => { _client.UserUpdated += async (s, e) => {
// Check that the user is in a Voice channel // Check that the user is in a Voice channel
if (e.After.VoiceChannel == null) return; if (e.After.VoiceChannel == null) return;
// See if they changed Voice channels // See if they changed Voice channels
if (e.Before.VoiceChannel == e.After.VoiceChannel) return; if (e.Before.VoiceChannel == e.After.VoiceChannel) return;
// do something... await logChannel.SendMessage($"User {e.After.Name} changed voice channels!");
}; };
Connection States
-----------------
Connection Events will be raised when the Connection State of your client changes.
.. warning::
You should not use DiscordClient.Connected to run code when your client first connects to Discord.
If you lose connection and automatically reconnect, this code will be ran again, which may lead to unexpected behavior.