|
|
 |
|
|
| NOTE: This Design document is subject to change at any time. |
Event Handling
zApp provides a very powerful mechanism for handling events that might be generated by various controls. For example, when you click the mouse on a control, the "OnClick" event is generated.
zApp handles events in a way very similar to how events are handled on a web page. The <SCRIPT> tag allows you to define a new script in zApp, and the EVENT attribute can be used to assign an event name to the script.
For example, to execute a script when a button is clicked, you might use the following code:
| Code: |
<BUTTON Name='MyButton' Caption='Click Me'>
<SCRIPT Event='OnClick'>
msgbox "The button was clicked!"
</SCRIPT>
</BUTTON> |
Or, the second way to assign an event handle is to assign a script directly to the OnEventName property of the control. For example, to change the OnClick event handler show above, you could use the code:
| Code: |
| MyButton.OnClick = "msgbox ""New handler was clicked""" |
The difference between these two methods is that the first method is more useful within your ZML application file, while the second method allows for event handlers to be redefined at runtime.
There is another important distinction between these two methods. When using the ZML code to define an event, you can add additional code to the event at a later time, or within a plugin. For example, if the main ZML file had the BUTTON as defined in the previous example, then a plugin could add the following code:
| Code: |
<BUTTON Name='MyButton'>
<SCRIPT Event='OnClick'>
msgbox "In the plugin"
</SCRIPT>
</BUTTON> |
Now, when the button is clicked you get two message boxes. The first one says "The button was clicked!" and the second one says "In the plugin", showing that both event handlers are being executed in succession.
If you assign a script to the OnClick property of the button, that replaces ALL scripts assigned to that event for the button (the main script AND the plugin script). So, assigning a script directly to the OnClick event should be done with care.
Default Scripts
Many controls have a default event handler script. When using the default script, you don't need to specify the EVENT attribute. If the default event handler is also the default property of the control (such as with Buttons and Items), then you don't even need the <SCRIPT> tag. For example, the above button could have more easily been defined with the simple code:
| Code: |
<BUTTON Name='MyButton'>
msgbox "The button was clicked!"
</BUTTON> |
or the event handler could have been set using the generic SCRIPT property of the control:
MyButton.Script = "msgbox ""The button was clicked!"""
When using the ZML SCRIPT tag, the script is normally assigned to the object that the SCRIPT tag is defined within. In the above examples, the SCRIPT tag is used within the BUTTON tag, so the script is assigned to the button (MyButton in this case). You can override this using the FOR attribute within the script tag. For example, to add a script to the MyButton object from anywhere in your ZML file, you could use this code:
| Code: |
<SCRIPT For='MyButton' Event='OnClick'>
msgbox "Yet another event handler"
</SCRIPT> |
Note that this is the same syntax as that used to define events within an HTML web page.
Script languages
One of the advantages of using the <SCRIPT> tag to define an event handler is that you can use the Language attribute to set the scripting language of the script. The default scripting language for a particular control is set via the Language property of that control. But using the <SCRIPT> tag, you can have different languages for different event handlers within the same control, or different languages for event handlers added by plugin modules. Thus, the plugin developer doesn't need to know what language the main application is using and can use whatever scripting language the developer wants for the plugin scripts.
Script Access Protection
zApp also implements some protection mechanisms to prevent unauthorized tampering with your event code. First, if your object is defined with an encrypted ZXL file, you cannot assign directly to the event handler properties outside of that ZXL file. For example, a plugin could not replace your script, nor can the plugin even view the contents of the script.
You can achieve this same kind of protection within your code by setting the Locked property of the control to True. When a control is Locked, then none of its event handlers can be viewed or overwritten. A control defined within an encrypted ZXL file is locked by default and the locked property can only be reset to false within that same ZXL file. |
|
Plugins