EventPerk

Inherits:Perk Section:event Priority:210

EventPerk grants event-related functions such as adding event handlers and triggering events.

Unit-specific settings are written in the “event” section.

{
    "event": {
        "events": {
            <elementName>: {
                "handlers": {
                    <eventName>: { or [{
                        "handler": Function|String,
                        "listerOptions": Object,
                        "options": Object,
                        "order": Number,
                    } or }, ...]
                    ...
                },
                "rootNode": String,
            },
            ...
        }
    }
}

There is a shortened format for event handlers. If you do not need event handler options, you can use this format.

{
    "event": {
        "events": {
            <elementName>: {
                "handlers": {
                    <eventName>: Function|String or [Function|String, ...],
                    ...
                },
                "rootNode": String,
            },
            ...
        }
    }
}

Type:String

The target element name to set event handlers. If the rootNode option is not specified, this value is taken as the ID of the element. If this value is “this”, it represents the unit itself. If the rootNode option is specified, this value has no particular meaning, but should be unique.

Type:String

The name of the event for which you want to register an event handler. Valid event names are BitsmistJS events or standard Javascript events.

Type:String|Function

The event handler for this event. The event handler can be a string or a Function object. If a string is specified, it is assumed to be the method name of the unit. If a Function object is specified, it is considered to be the event handler itself (Function object). In either case, the handler will be bound to the unit, and “this” will point to the unit itself, unless specified in the add skill argument.

Type:Object

The options which passed to the Javascript native addEventListener() function.

Type:Object

The options which passed to the event handler. It can be accessed via the “ex” argument of the event handler.

Type:Number Default:0

The order priority. It controls the order of execution when there are multiple event handlers for the same event on the same element. The higher the number, the earlier the event is executed. If not specified, it is 0.

Type:String

The selector string represents the node to which the event handler is set. Only elements under the unit's own node are selected. If multiple elements are returned, the same event handler is set for all elements.

Here are some examples of settings. The shortened formats are used whenever possible.

Here is an example of specifying the target element. There are two main types of elements: the unit itself or elements inside the unit.

"event": {
    "events": {
        "this": {
            "handlers": {
                "doRefresh": this.onDoRefresh
            }
        }
    }
}

Since <elementName> is “this”, the event handler is set to the unit itself.

You can specify it in “rootNode”, also. In this case, the <elementName> “myself” is just a meaningless string (to the library), but should be a unique one.

"event": {
    "events": {
        "myself": {
            "rootNode": "this"
            "handlers": {
                "doRefresh": this.onDoRefresh
            }
        }
    }
}

If an element has an ID, you can specify it in <elementName>.

"event": {
    "events": {
        "btn-menu": {
            "handlers": {
                "click": this.onBtnMenu_Click
            }
        }
    }
}

In the above example, the event handler is set to an element that has an ID “btn-menu”.

You can use a selector string that is valid to querySelectorAll() in “rootNode”.

"event": {
    "events": {
        "btn-menu": {
            "rootNode": ".buttons"
            "handlers": {
                "click": this.onBtnMenu_Click
            }
        }
    }
}

This could result in more than one element. The event handler is set to all the elements matched.

We will show you how to specify event handlers.

You can use a Function object or a string as an event handler.

"event": {
    "events": {
        "this": {
            "handlers": {
                "doRefresh": this.onDoRefresh
            }
        }
    }
}

In the above example, a Function object is specified as the event handler for the “doRefresh” event.

"event": {
    "events": {
        "this": {
            "handlers": {
                "doRefresh": "onDoRefresh"
            }
        }
    }
}

In this example, a string is set as the event handler. The method that has the name “onDoRefresh” is searched from the unit's method, that is this.onDoRefresh(), and used as the event handler.

You can set multiple event handlers to one element.

"event": {
    "events": {
        "this": {
            "handlers": {
                "doRefresh": ["onDoRefresh1", this.onDoRefresh2]
            }
        }
    }
}

Two event handlers are specified using an array. You can mix function objects and strings in one array.

You can pass options to event handlers.

"event": {
    "events": {
        "this": {
            "handlers": {
                "doRefresh": {
                    "handler": this.onDoRefresh,
                    "options": {"value":"1"}
                 }
            }
        }
    }
}

In this example, both an event handler and options are set at the same time. The options can be accessed via the “ex” parameter of the event handler.

onDoRefresh(sender, e, ex)
{
    console.log("value =", ex.value); // console displays "value = 1"
}

In the next example, two handlers with each option are specified.

"event": {
    "events": {
        "this": {
            "handlers": {
                "doRefresh": [
                    {
                        "handler": this.onDoRefresh1,
                        "options": {"value":"1"}
                     },
                    {
                        "handler": "onDoRefresh2",
                        "options": {"value":"2"}
                     },
                 ]
            }
        }
    }
}

Loads the settings from the “event.events” section and adds event handlers.

• event.events

Loads the settings from the “event.events” section and adds event handlers only to the elements inside the units. The unit's own events are not installed at this time.

• event.events

Type:Undefined Target:Unit

Sets event handlers for an event to elements.

Undefined.

Type:Undefined Target:Unit

Sets event handlers for events to elements. Unlike add skill, init skill can set event handlers for multiple events at once. Uses add skill internally to set each event.

Undefined.

• event.events.<elementName>

Type:Undefined Target:Unit

Removes event handlers from elements.

Undefined.

Type:Undefined Target:Unit

Removes event handlers from elements. The reverse process of the init skill is performed.

Undefined.

• event.events.<elementName>

Type:Undefined Target:Unit

Fires an event, but unlike trigger, it calls the next handler without waiting for the previous one to finish.

Undefined.

Type:Undefined Target:Unit

Fires an event. If multiple event handlers are set for the same event of the same element, the event handlers wait until the previous event handler is complete.

Undefined.