Light, camera and action

Overview

In this chapter we take a look to the new action system of the framework. We learn how to create and use action, so let's get started.

What are actions?

Actions are not a part of the Discord API, but an event system of the framework. These actions are an advanced version of the event callbacks of the controller interface. With the help of actions you can triggered by a given event on a specific channel, which can also be filtered, but later more.

Your first action

MyAction.hpp

#ifndef MYACTION_HPP
#define MYACTION_HPP

#include <models/Action.hpp>
#include <iostream>

using namespace std;

class CMyAction : public DiscordBot::CAction<GuildMember>
{
    public:
        CMyAction() : CAction(ActionType::USER_JOIN | ActionType::USER_LEAVE) {}

        // Important this must be the same type as given as template parameter. 
        //                                                          |
        //                                                          V
        void FireAction(DiscordBot::ActionType Type, Channel c, GuildMember val) override
        {
            // Prints the nick or username of the user, who has triggered the event.
            if(Type == ActionType::USER_JOIN)
                cout << val->Nick.load() << " is no in " << c->Name << endl;
            else
            {
                cout << val->Nick.load() << " has leaved " << c->Name << endl;
            }
            
        }

        ~CMyAction() {}
};

#endif

This short class will listening on two different actions which can occurred. These actions are given to the base constructor as seen here CMyAction() : CAction(ActionType::USER_JOIN | ActionType::USER_LEAVE) {}. You can find all available ActionTypes here. Maybe you have already seen that the base class is a template class. This is necessary to pass the right type of class to the FireAction method. The needed type is documented as comment to the enum value of ActionType.

The void FireAction(DiscordBot::ActionType Type, Channel c, T val) method, where T is type given to the base class, will be always called if the given action occurred on a given channel. In the above example it's the user join and leave action. So always if an user joins or leaves a channel, the name is printed to the console with the action which triggered these.

Filter

So this is nothing new you might think, because the controller interface has a similar event, the OnVoiceStateUpdate event. But there is one different between these two methods, you can filter which for example User should trigger the FireAction method. With the following method you can control these behavior:

    public:
        ...
        // Important this must be the same type as given as template parameter. 
        //                                           |
        //                                           V
        bool Filter(ActionType Type, Channel c, GuildMember val) override
        {
                return val->Nick == "Josh";
        }
        ...

With the above snippet the FireAction is only triggered if a member with the nickname Josh joins or leaves the channel. That's all.

Registering an action

After we have written our action we need to register this for a channel. First we need to obtain the admin interface for a guild

...
auto Admin = Client->GetAdminInterface(guild);
...

Now we can register an action for a channel

...
Admin->AddChannelAction(channel, Action(new CMyAction()));
...

A few words about the above call. The first parameter is the channel where this event should applied to, this can either a channel object or null, which register this action globally. The second one is our action object. If an action is already registered for a channel an exception is thrown.

Congratulations

Now you know all about actions.