Scripting and Events
To create form documents that are able to do more than just reading and writing plain data, it is often necessary to enhance the form with scripting functionality. That is, for a given form component, you want to declare that a certain script should be called, when a certain event occurs.
For example, you may need a check box control, which calls a certain macro when its check state changes. Within this macro, you can, for instance, enable or disable other controls that depend on the check box being checked.
One possible solution is to use a completely programmatic approach: just bind a script to the OnLoad event of the whole document, create an XItemListener, and register it at the check box control in question, using the XCheckBox interface.
However, this method is inefficient, because the whole scripting engine starts when the document is loaded. The scripting engine should start at the latest possible point, which is the moment the user clicks the check box for the first time.
Form components feature a mechanism that is more efficient. For every form component part of a hierarchy of form components, you can specify a script to be called upon a certain event. You only specify this once, at the time the form component is created and placed in the document.,
Look at the com.sun.star.form.FormComponents service, which was encountered previously. The service includes the interface com.sun.star.script.XEventAttacherManager. This interface allows you to manage the events that are associated with the elements in the FormComponents container.
Note that an event together with an associated script is described by the ScriptEventDescriptor, with the following elements:
|Properties of com.sun.star.script.ScriptEventDescriptor|
|ListenerType||Specifies the completely qualified name of a listener interface. This implies that you can only register scripts for events that are notified using UNO.|
|EventMethod||Specifies a method of the |
Together with the
|AddListenerParam||Specifies a parameter that is to be used when adding listeners, as described by the |
|ScriptType||Specifies which type of script is to be associated with the event. com.sun.star.form.FormComponents currently only support |
|ScriptCode||Specifies which script code to call. In case of |
The following example registers a certain Basic procedure for the event which is triggered when the state of a radio button control changes, for example, when a radio button has been selected or deselected:
Dim oEvent as new com.sun.star.script.ScriptEventDescriptor oEvent.ListenerType = "com.sun.star.awt.XItemListener" oEvent.EventMethod = "itemStateChanged" oEvent.ScriptType = "StarBasic" oEvent.ScriptCode = "application:Standard.macro_assignment.onColorChange" oSampleForm.registerScriptEvent( i, oEvent )
For the ith sub component of
oSampleForm, this associates the macro
onColorChange, located in the module
macro_assignment of the application-wide library
Standard, with the itemStateChanged event. You can use this with every form component which supports notification of XItemListeners, in particular with radio buttons (XRadioButton) and check boxes (XCheckBox).
Note that simply registering script events at a FormComponents instance does not do anything. In particular, registering script events does not yet mean that the script will be called automatically. In fact, the XEventAttacherManager interface merely acts as a container to remember the associated events. In a living form document, there are controller instances involved, which take care of the scripts that are really being called, by adding themselves as XScriptListener to the event attacher manager.
|Content on this page is licensed under the Public Documentation License (PDL).|