vegUI Tutorial 05 - Node Events (mouse, keyboard and more)

A live example of this tutorial can be found here. This tutorial is a follow-up to tutorial 4.

The vegUI node, and hence every vegUI element can handle all the common mouse and keyboard events. By default event handling is disabled for a vegui element (with certain exception depending on the widget). In order to enable event handling for a certain event we need to set the flag in the flags property of the element.

The flags property is a bitmask, you can enable a flag with the | operator, toggle a flag with the ^ operator and check for a flag with the & operator. I know those familiar with bitmasks are probably scowling at me for that description, however i dont want to explain bitmasks in this tutorial, and how they work, if youre interested in reading how exactly bitmasks work i am sure there are a ton of good tutorials on google.



So lets say we want our node cloneNode1 to handle the mouse-down event that is fired when a mouse button is clicked while the mouse is hovering above the element. In order to enable the event in vegUI we would need to set the VUI_HMOUSE_DOWN flag.



It is important that event enabling flags are set before the node is built by the way.

The vegUI node handles events over its States property. If a mouse or keyboard event fires and handling of it is enabled on the note then the VegUIMouseState object for the event does the rest.

Every vegUINode has a vegUIMouseState object for every event that vegUI supports. Those object are stored in the node's State property by their type


Definition: Mouse and Keyboard event types

The VegUIMouseState object has a Scripts property which is a VegUIDynFunc object. The vegUIDynFunc is a dynamic function object that is basically a collection of functions that can all be executed at the same time with a single command. This is handy because it allows us to add a big "dynamic" function that we can add snippets to as we see fit.

Definition:VegUIDynFunc

Lets have cloneNode1 change its child's background color when it is clicked, shall we? In order to do so we need to add a script to the VUI_MOUSE_DOWN State of the node.



The argument of the add method of the VegUIDynFunc object is the function that you wish to add to the function stack. In the case of the VegUIMouseState object the function you add has an optional argument as well called argArr, which is an array that holds certain properties, the first property at index 0 is always a reference to the element that the event was fired on.

You could also use the power of closures too, in which case you wouldnt need argArr to reference to the object. Like this:



Closures are tricky though, and can lead to some unintended behavior if you do not understand them, but thats not part of this tutorial ;).

Back to our color changing node.. If you load the page now and click the node, the background color of the child should change to white. Lets add a mouse-up event as well to change it back to #000.



Okay ,ready to go! Hold up whats that? Oh we did not set the VUI_HMOUSE_UP flag on the node. Well we dont need to , mouse up events are handled by the manager and are always directed to the element that the manager currently sees as focused. To give a node focus you need to call the set_focus_node() or set_focus() method on it. So lets change the function that we add to the VUI_MOUSE_DOWN state a bit to give the node focus.



We dont want to hog the focus either so lets lose it on VUI_MOUSE_UP, we do this by calling the method lose_focus_node() or lose_focus() on the element.



There.. now we're done! If you load the page now, and press the button on the node, it will turn white. It will stay white as long as you dont release the mouse button, once you do the node changes its color back to blue.

Event Properties

When an event is handled by the VegUINode certain properties may be set on the element that may help you deal with the event.

In all cases of event handling the mEvent property is set which holds the javascript event object that was created when the event was fired.

You can find a list of event specific properties here:

Definition: Event Specific Object Properties

Handling a keyboard event

In order to have our node handle keyboard events we need to do two things

1. Flag the node accordingly


2. Give the node focus

We will use our second clone cloneNode2 for this example, so we can leave cloneNode1 in peace with its color changing abilities ;)

So lets set the flag that allows us to handle key down events cloneNode2, we also enable VUI_HMOUSE_DOWN, because we will need that as well.



Lets do something fun and have the child node of cloneNode2 display the key that was pressed. In order to do that we need to figure out which key was pressed and then fill the child node with a text node.


Definition: VegUINode.clear()

The aKeyChar property is one of the event specific properties that i mentioned earlier, it holds the character of the key that was pressed.

The key-down and key-up events are triggered on the manager node and not on the node directly. The event is then routed to the element that the manager currently sees as having focus. That means in order for our example to work we need a way to give focus to cloneNode2

Lets do this like we did for cloneNode1 by enabling the mouse-down event catching and having a click on cloneNode2 giving it focus, thats why we set the VUI_HMOUSE_DOWN flag as well.



Okay, a small difference, this time we also submit an argument to the set_focus() method. The focus type. It just means were giving the node active focus , which allows the manager to reroute the key event to it.

Load the page, then click on cloneNode2 to give it focus then type something, if everything worked out every time you hit a key it should get displayed.

Toggling events after the node is built

You can toggle event catching on or off even after the node is build by calling the tgl_event() method directly.


Definition: VegUINode.tgl_event()

This would turn the event handling for VUI_KEY_DOWN off after the node was build. Additionally if you want to disable all event handling on the node temporarily you can call the element's disable_node() or disable() method.


Definition: VegUINode.disable_node()

Update: 2.0.6

Form Events

There are two form events that are supported by vegUI the VUI_FORM_BLUR and VUI_FORM_FOCUS events. VUI_FORM_FOCUS is fired when a form element that can take input (such as a text box or a select list) gains focus. VUI_FORM_BLUR triggers when said focus is lost again.

You access them in the States property of the node just as the other events.



This concludes the fifth tutorial of the vegUI tutorial series, in the next tutorial we will take a look at the vegUI bounding box.

Related Posts

• vegUI Tutorial 04 - Cloning
• vegUI Tutorial 06 - The Bounding Box

---

Your Comment

name:*
email-address:
Are you human?

Comments to this post: (2)

RSS Feed for comments

---

lavnish
on 06 Jun, 2007 - 12:24:32

hi
possibly you can think of changing the color of the cloneNode2 ... as black alphabets are not visible on black background ...
only if the color is changed then we can see typed alphabets

regards
lavnish


Report this comment

---

vegu
on 06 Jun, 2007 - 13:09:58

Oh, lol, that kinda slipped past me, i will fix it when i get a sec, thanks , but for now you can simply set its T.Css.color to '#fff' when it's background color is set to be black and vice versa :)

Report this comment

---

---