Scripting and Events

From Apache OpenOffice Wiki
Jump to: navigation, search



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 ListenerType interface.

Together with the ListenerType member, this completely describes the event for which a script is to be registered.

AddListenerParam Specifies a parameter that is to be used when adding listeners, as described by the ListenerType element) For most listener types, this is not necessary.
ScriptType Specifies which type of script is to be associated with the event. com.sun.star.form.FormComponents currently only support StarBasic here.
ScriptCode Specifies which script code to call. In case of ScriptType being StarBasic, this must specify a Basic procedure or function, either within the application-wide code repository, or within the document which the form component belongs to. In the first case, the script code starts with "application:", else with "document:".

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 attach manager.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages