[00:00] In this lesson, we'll take a look at the event object and how we can put it to use doing component event scripting in the designer. As we probably already know, there are many, many different kinds of components available to us in the designer. We can see a partial list of them here in the component palette on the right. When some action happens to one of them. For example, a button is pressed, mouse clicked, or a key typed, that triggers an event. And we can write an event handler script to respond to that event. Whenever you are doing component event scripting and writing an event handler script to respond to a specific event, there is a special variable available to your script called the event object. Every different kind of event has an event object associated with it, but the event objects for different events contain different kinds of information. How do we know what information is available to our event scripts? Let's take a look at this button component, which is labeled as button text.

[01:03] And down here in the property editor has a name of, not unsurprisingly, button name. So we can right click on this button, select the scripting option, select the script editor tab on the right, and take a closer look at its component scripting window. Let's also select the action performed event here in the event handlers pane. The panel here on the lower right, the event object properties will always tell us what variables any event object will have on it. What we can always count on, however, is that any event object always has a variable on it called source, which is just the component itself. So for an action performed event on the button, we can do the following, print event.source, which grabs the source out of the event, the component that fired the event. And then once we have that, we can drill down a bit further and append any desired properties of the button using dot notation.

[02:04] So to get the name of the button, let's just depend the following, .name, and let's copy paste all of this to one and two, like so. And if we wanted to get the label text as well, we'll just replace name with .text as so. To see the results of the script, we can go down here and apply our changes, then go to the preview mode in the designer up here. And each time we click this button, we see both the button's name and its labeling text appear down here in the console. Of course, the types of information available in the event object will vary with each specific event type. Let's go back into the scripting window to see some examples of this. So let's go from preview mode back to design mode, then we'll right click on the button again to get back to the scripting window. Then let's take a look at the key events. For example, the key typed event.

[03:05] It will have properties such as a key code for the key that was typed, a key char for the key that was typed in case it was a character key, and the key location to differentiate between the left and right, Shift or Control keys, things like that. Similarly in the mouse events, any of the mouse events such as mouse clicked will have things like which button was pressed on the mouse, the x and y coordinates of the mouse when it was pushed. And whether other keys such as Alt or Control or Shift were also held down, things like that. Of particular interest is the property change event. So let's click on that event handler. It's especially important because it demonstrates two key things. The value that was changed, both the before and after values, and the actual property name that was changed. This event object often leads to a common mistake by those more inexperience with scripting.

[04:07] For example, let's hit okay to close this window, and let's say we wanna work with a numeric text field. So we'll drag one over onto our window like so, and we might wanna write a script that runs each time the value of the numeric text field changes. So if we go down here and scroll down to its data section, let's say we wanna run in integer mode. So the property value we're interested in is called int value, which we can obtain by hovering over the data label like we're doing right here. Then the typical thought process might be, I wanna write a property change script for when my value changes. So let's open up our script window by right clicking on the component, selecting the property change event, and going to the script editor tab on the right. And there we'll simply print the new value, print event.new value, like so.

[05:11] Seems reasonable, right? Well, the reality of this will be very different because when we run this in preview mode, so let's click okay, and go to preview mode. And we start interacting with this component, Backspace and put in another value, for example. We're gonna start seeing lots of strange and unnecessary things displayed in the console down here. There's some long initial object strings, couple of true false values, and multiple data type versions of the same data, apparently. Why does this happen? The reason for all this is that the property change event gets fired for lots of different properties, including things that really have nothing to do with user-facing workings in ignition. Instead it's important to first check if the change comes from a property we want to handle.

[06:03] So going back to design mode and going back to our scripting window, we'll do this with an if and our script. So we'll preface the line we had before with the following. If events.property name, equal equal and then double quotes int value. And we'll space over a little bit like that. So now we're looking at the property name of the event. And if it's equal to int value, only then will we print the new value as we did before. So let's click apply to save these changes. Then when we go back to preview mode, and once again we interact with this numerical text box. Just to make it simpler, I'll clear out the console. So let's change this to something else, and change it to something else again.

[07:05] So now we see only the changed values with none of the extra earlier stuff. So if you're writing a property change script, without a first-line like this, you know you're probably doing something wrong. So in this lesson, we've seen how to add event scripting to components using an event object, and how to properly trigger them using only the property name of interest.