Event Actions

action.perform(action: any): any

Performs the given action. This function can be used to perform actions that you have stored as data without having to find out which function to call. You can find a list of action types here.

The first parameter is a any and is the action that should be performed.

Examples

Perform a toast action

action.perform({
    type: 'show_toast',
    message: 'Hello, world!',
    duration: 2000
});

Perform an add bot action

action.perform({
    type: 'add_bot',
    id: 'bot_id',
    bot: {
        id: 'bot_id',
        tags: {
            home: true,
            label: 'Hello, World!'
        }
    }
});

action.reject(action: any): RejectAction

Prevents a previous action from being performed.

This is especially useful when used in a @onAnyAction listener since it lets you reject actions before they are performed.

The first parameter is a any and is the action that should be prevented/rejected.

Examples

Prevent a toast message from being performed.

const toastAction = os.toast("my message");
action.reject(toastAction);

priorityShout(eventNames: string[], arg?: any): any

Shouts to all bots that are #listening and have a listen tag for the specified events until one of the bots returns a value. Optionally includes a custom that argument. Also triggers @onListen and @onAnyListen for the bots that the shout was sent to.

This function is useful when you want to shout but only want one bot to process the shout.

The first parameter is a string[] and is the array of event names that should be shouted. e.g. Using onClick for the name will trigger the @onClick listener until a bot returns a value.

The second parameter is optional and is a any and is the that argument to send with the shout. You do not need to specify this parameter if you do not want to.

Examples

Shout to the first bot that handles @onClick

priorityShout(['onClick']);

Shout to the first bot that handles @myTest or @mySecondTest

priorityShout(['myTest', 'mySecondTest']);

Priority shout with a color

priorityShout(['myTest', 'mySecondTest'], "blue");

shout(name: string, arg?: any): any

Sends a shout to all bots that are #listening and have a listen tag for the specified name. Optionally includes a custom that argument. Also triggers @onListen and @onAnyListen.

The first parameter is a string and is the name of the shout. e.g. Using onClick for the name will trigger all @onClick listeners.

The second parameter is optional and is a any and is the that argument to send with the shout. You do not need to specify this parameter if you do not want to.

Examples

Send a @reset event to all bots

shout("reset");

Send a @hello event with your name

shout("hello", "Bob");

superShout(eventName: string, arg?: any): SuperShoutAction

Sends a shout to all of the other instances that are loaded.

The first parameter is a string and is the name of the shout. e.g. Using onClick for the name will trigger all the @onClick listeners.

The second parameter is optional and is a any and is the optional that argument to include with the shout.

Examples

Send a hello super shout to all the loaded instances.

superShout("hello");

whisper(bot: (string | Bot | (string | Bot)[]), eventName: string, arg?: any): any

Sends a whisper to all bots that are #listening and have a listen tag for the specified name. Optionally includes a custom that argument. Also triggers @onListen and @onAnyListen.

The first parameter is a (string | Bot | (string | Bot)[]) and is the bot, array of bots, bot #id , or array of bot #id that the whisper should be sent to.

The second parameter is a string and is the name of the whisper. e.g. Using onClick for the name will trigger the @onClick listener for the specified bots.

The third parameter is optional and is a any and is the that argument to send with the shout. You do not need to specify this parameter if you do not want to.

Examples

Send a @reset event to all bots named "Bob"

let bots = getBots("#name", "Bob");
whisper(bots, "reset");

Send a @setColor event to ourself

whisper(this, "setColor", "red");