Class EventRegistrationTag
- java.lang.Object
-
- org.apache.commons.jelly.TagSupport
-
- org.apache.commons.jelly.DynaTagSupport
-
- org.apache.commons.jelly.MapTagSupport
-
- org.apache.commons.jelly.tags.core.UseBeanTag
-
- net.sf.jguiraffe.gui.builder.components.tags.UseBeanBaseTag
-
- net.sf.jguiraffe.gui.builder.action.tags.EventRegistrationTag
-
- All Implemented Interfaces:
ConditionalTag,PropertySupport,org.apache.commons.jelly.DynaTag,org.apache.commons.jelly.impl.BeanSource,org.apache.commons.jelly.Tag
public class EventRegistrationTag extends UseBeanBaseTag
A tag handler class for registering an event listener at a single or multiple components.
This tag handler class has a similar purpose as
EventListenerTag. However, it uses a different approach for connecting an event listener with a component. WhileEventListenerTagand its sub classes allow connecting actions to standard component events (e.g. action or change events), this class operates on plain event listener implementations. It can also be used for working with non-standard event listeners, i.e. event listener interfaces defined in thenet.sf.jguiraffe.gui.builder.components.modelpackage that do not extend theFormEventListenerinterface or even 3rd party or custom event listener interfaces.This tag handler class extends
UseBeanBaseTagand thus allows the definition of a bean class in multiple ways. The bean specified using the tag's attributes must implement the appropriate event listener interface. With the mandatorytypeattribute the event listener type must be specified. This can be either one of the standard types (ACTION,CHANGE, orFOCUS) or a non-standard event listener type. In the latter case the type name is derived from the name of the method for adding event listeners. As an example take theTreeHandlerinterface that defines theaddExpansionListener()method for registering an event listener to be notified when a node of the tree is expanded or collapsed. The corresponding event type is Expansion, i.e. the string between add and Listener.The component(s) the event listener should be registered at can be specified in multiple ways:
- This tag can be placed in the body of a tag defining a component. Then it registers the listener at the component handler of this component.
- The name of a single component can be specified in the
componentattribute. The listener will be registered at this component'sComponentHandler. - Event handlers may also be registered at arbitrary beans accessible
through the current
BeanContext. To do this thetargetBeanattribute must be specified. The tag obtains this bean from the context and calls the appropriateadd()method for adding the handler. Note that if the tag is used in this way really all beans of the current bean context can be accessed, e.g. the platform-specific components or the current window. - It is also possible to register a listener at all components that support
the specified event type. In this case the
multipleattribute must be set to true, and no component name or bean name must be specified. (The additionalmultipleattribute was introduced to provide a better error diagnosis: If thecomponentattribute is omitted accidently, an exception is thrown rather than silently registering the listener at all components.)
The following table lists the attributes supported by this tag handler class. Of course, all attributes defined by the
UseBeanBaseTagclass for specifying the bean are also supported.Attribute Meaning Optional component The name of the component the event listener is to be registered at. Yes targetBean With this attribute an arbitrary object available in the current BeanContextcan be selected to which the event listener is added. This is a more generic form than using thecomponentattribute. The bean specified here does not need to implement theComponentHandlerinterface; as the event listener is added through reflection, it can be an arbitrary object defining an appropriateaddXXXListener()method. Note: This attribute should not be used for registering standard event handlers (ACTION, FOCUS, and CHANGE ).Yes multiple If this attribute is specified (with an arbitrary value), the event listener will be registered at all compatible components. In this case the componentattribute must be empty.Yes eventType Determines the type of the event listener. The bean specified by this tag must implement a compatible event listener interface. No ignoreFail With this attribute error handling can be controlled. Per default, the tag causes an error if no event listener can be registered. This can have various reasons, e.g. the name of the component is wrong, there is a typo in the event listener type, or there is no compatible component supporting the listener type. In most cases it is preferable to throw an exception in such a situation instead of ignoring the problem silently. There may be use cases though, where it is considered normal behavior that no fitting component for registering an event listener can be found. In this cases the ignoreFailattribute should be set - it can have an arbitrary value. If it is present, the tag will not throw an exception if the registration of the event listener is not possible.Yes The following fragment shows an example how this tag can be used for registering a listener for tree expansion events:
<f:tree name="myTree" model="treeModel"> </f:tree> <!-- The event listener bean --> <di:bean name="treeListener" beanClass="com.mypackage.MyTreeListenerClass"> </di:bean> <!-- Register the event listener --> <a:eventListener component="myTree" eventType="Expansion" beanName="treeListener"/>
Note that it does not matter where in the builder script the event registration tags are placed as the actual registration is performed after all components have been created.
- Version:
- $Id: EventRegistrationTag.java 205 2012-01-29 18:29:57Z oheger $
- Author:
- Oliver Heger
-
-
Field Summary
-
Fields inherited from class net.sf.jguiraffe.gui.builder.components.tags.UseBeanBaseTag
ATTR_BEAN_CLASS, ATTR_BEAN_NAME, ATTR_CLASS, ATTR_IF_NAME, ATTR_REF, ATTR_UNLESS_NAME, ATTR_VAR
-
-
Constructor Summary
Constructors Constructor Description EventRegistrationTag()Creates a new instance ofEventRegistrationTag.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected booleanpassResults(Object bean)Performs the registration of the event listener.-
Methods inherited from class net.sf.jguiraffe.gui.builder.components.tags.UseBeanBaseTag
addIgnoreProperties, doTag, fetchBean, getAdditionalProperties, getAttributeStr, getBaseClass, getIfName, getUnlessName, isOptional, processBean, setBaseClass, setProperty, useExistingBean
-
Methods inherited from class org.apache.commons.jelly.tags.core.UseBeanTag
addIgnoreProperty, convertToClass, getBean, getDefaultClass, getIgnorePropertySet, isIgnoreUnknownProperties, loadClass, newInstance, setBean, setBeanProperties, setIgnoreUnknownProperties, validateBeanProperties
-
Methods inherited from class org.apache.commons.jelly.MapTagSupport
createAttributes, getAttributes, setAttribute
-
Methods inherited from class org.apache.commons.jelly.TagSupport
findAncestorWithClass, findAncestorWithClass, findAncestorWithClass, findAncestorWithClass, findAncestorWithClass, findAncestorWithClass, getBody, getBodyText, getBodyText, getContext, getParent, invokeBody, isEscapeText, isTrim, setBody, setContext, setEscapeText, setParent, setTrim, trimBody
-
-
-
-
Method Detail
-
passResults
protected boolean passResults(Object bean) throws org.apache.commons.jelly.JellyTagException
Performs the registration of the event listener. The actual registration is done by a callback object at the very end of the builder script. This ensures that all components have already been created.- Overrides:
passResultsin classUseBeanBaseTag- Parameters:
bean- the bean object- Returns:
- a flag whether the event listener could be registered
- Throws:
org.apache.commons.jelly.JellyTagException- if an error occurs
-
-