1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.gui.builder.event;
17
18 import net.sf.jguiraffe.gui.forms.ComponentHandler;
19
20 /**
21 * <p>
22 * Definition of an interface for dealing with platform (i.e. a specific GUI
23 * library) specific events.
24 * </p>
25 * <p>
26 * This interface defines the link between the generic event handling mechanism
27 * provided by the form framework and the library specific event handling
28 * support. A concrete implementation has to intercept native component events
29 * and transform them into the generic event types. Then the transformed events
30 * are passed to the {@link FormEventManager}.
31 * </p>
32 * <p>
33 * This interface defines only methods for registering and deregistering event
34 * listeners of a certain type at a component defined by a
35 * <code>ComponentHandler</code> object. These methods will be called by the
36 * {@link FormEventManager} class, which will already perform some
37 * synchronization and pre-processing. So it is guaranteed that synchronization
38 * is performed on the form listener type, i.e. no listeners of the same type
39 * will be added or removed concurrently. <code>FormEventManager</code> will
40 * further invoke the <code>registerListener</code> method only once for a
41 * combination of component handler and event listener type. This means that the
42 * <code>FormEventManager</code> instance is the only event listener for the
43 * available components; is is itself responsible for multiplexing of event
44 * notifications. These facts can be used by a concrete implementation for doing
45 * some optimization.
46 * </p>
47 * <p>
48 * Note: It cannot be guaranteed that all {@link ComponentHandler} objects
49 * passed to the methods defined by this interface have been created by the
50 * current {@code ComponentManager}. For instance, there can be other custom
51 * handler implementations created by special tag handler classes. This may be
52 * an issue for platform-specific implementations that expect the {@code
53 * ComponentHandler} objects to be derived from a specific base class.
54 * </p>
55 *
56 * @author Oliver Heger
57 * @version $Id: PlatformEventManager.java 205 2012-01-29 18:29:57Z oheger $
58 */
59 public interface PlatformEventManager
60 {
61 /**
62 * Registers an event listener of the given type at the specified component.
63 * This method is called when the first event listener of the affected type
64 * is registered at this component. The <code>FormEventManager</code> then
65 * registers itself as event listener so that it can multiplex incoming
66 * events to all registered listeners.
67 *
68 * @param name the component's name (must be contained in the
69 * {@link FormEvent} objects generated by this implementation)
70 * @param handler the component handler of the affected component
71 * @param eventManager the event manager that must be invoked when an event
72 * occurs
73 * @param type the event listener type
74 */
75 void registerListener(String name, ComponentHandler<?> handler,
76 FormEventManager eventManager, FormListenerType type);
77
78 /**
79 * Removes an event listener of the given type from the specified component.
80 * This method is called by the <code>FormEventManager</code> when the last
81 * event listener of the affected type deregisters from this component.
82 *
83 * @param name the name of the affected component
84 * @param handler the component handler of this component
85 * @param eventManager the event manager
86 * @param type the event listener type
87 */
88 void unregisterListener(String name, ComponentHandler<?> handler,
89 FormEventManager eventManager, FormListenerType type);
90 }