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. WhileEventListenerTag
and 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.model
package that do not extend theFormEventListener
interface or even 3rd party or custom event listener interfaces.This tag handler class extends
UseBeanBaseTag
and 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 mandatorytype
attribute 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 theTreeHandler
interface 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
component
attribute. 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 thetargetBean
attribute 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
multiple
attribute must be set to true, and no component name or bean name must be specified. (The additionalmultiple
attribute was introduced to provide a better error diagnosis: If thecomponent
attribute 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
UseBeanBaseTag
class 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 BeanContext
can be selected to which the event listener is added. This is a more generic form than using thecomponent
attribute. The bean specified here does not need to implement theComponentHandler
interface; 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 component
attribute 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 ignoreFail
attribute 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 boolean
passResults(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:
passResults
in 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
-
-