Navigation:  Examples >

Example 6: Using Custom Event

Previous pageReturn to chapter overviewNext page

Example 6: Using Custom Event

Run This Example in New Window

If you want to define the same behavior for different events, you may consider copying/pasting the content between event handlers.  That works but it is not the best solution, the best practice is to define the behavior in a handler of "Custom Event", and trigger this custom event when you want the behavior be executed.

If you have programming experience, you will realize the way to use custom event is very similar with function call: you define a function, and call it at some places.

Now lets create a simple example to demonstrate how to use custom event: input password "1234", and press ENTER key or click button to login.

First we need to place a TextBox, a TextEditBox and a Button element into the page to construct a login UI.  The TextEditBox should have the "Encrypt" option selected since it is used to accept password.


Since clicking the login button and pressing ENTER key in TextEditBox have the same behavior, we can define a custom event for that.  Have the TextEditBox selected and press Ctrl+D to define behavior for it, then click "Add Event" button in toolbar and choose "Custom Event...", you will see this window:


Here we need to input the name of the custom event, only letters and underline can be accepted.  Let's use "Do_Login" as the event name.  Here the "Serve as Global Event" option is selected by default, which means the event can be triggered anywhere and the event handler will be invoke whenever the event is triggered.  In most cases we can let it work in this way, but it may bring some problems when we have duplicated custom event names in the same plot.  We will talk about this at the end of this example.

The defined custom event looks like this:


Lets finish the event handler for this custom event by adding conditional branch and show message actions, as shown below:


Now we want to trigger this custom event when user press ENTER key in the TextEditBox.  We need to add a "Key Down" event for the TextEditBox, and invoke the "Trigger Global Event" action to trigger the "Do_Login" custom event when the TextEditBox has focus and the pressed key is ENTER.  Please check out the figure below for details:


You may notice there is a "Delay" before actually triggering the custom event, it is related to the keyboard event.  When you press the ENTER key on keyboard, the "Key Down", "Key Up" and "Key Clicked" events are triggered in the browser.  When the "Key Down" event handler invoke the custom event handler, the login result will be popped up as a message box.  If the "Key Clicked" event comes after showing the message box, it will automatically close that message box and you will never see the login result.  So, we put a Delay here, to delay the invoking of custom event handler, and avoid the pop up window to be closed automatically.

Also we need to trigger the same custom event when user click the "Login" button.  This is quite easy:


So the final behavior looks like this:


If you run the simulation, you will see it works as we expected: you input "1234" and press ENTER or click "Login", it says "Login Ok!", otherwise it says "Login Failed!".

What happen if you have multiple handlers for the same (global) custom event?

Good question.  In this case all handlers will be invoked.  If it is not the behavior you want, you may consider using non-global custom event.  Do you still remember the "Serve as Global Event" option when creating the custom event?  You can double click the custom event to change it after creation.  If you unselect that option, the custom event become "non-global", which means it belongs to the element that you add the custom event.  As shown below:


You will notice the "(global)" text disappear now, indicating that custom event is not global now, it belongs to the TextEditBox_1 element only.

After doing this, you could not trigger this custom event by using the "Trigger Global Event" action, instead you have to trigger this custom event via the "Trigger Event on Element" action, which is under the "Operate on Element..." category:


By doing so, you can define multiple custom events with the same name.  They will not affect each other as long as you add them to different element.  The final behavior with non global custom event is shown below:


Now you can run the simulation and see how it works.  You can view this online example to see the result, or download the plot file.