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.platform.swing.builder.event;
17
18 import net.sf.jguiraffe.gui.builder.event.FormEvent;
19 import net.sf.jguiraffe.gui.builder.event.FormEventListener;
20 import net.sf.jguiraffe.gui.builder.event.FormEventManager;
21 import net.sf.jguiraffe.gui.builder.event.FormListenerType;
22 import net.sf.jguiraffe.gui.forms.ComponentHandler;
23
24 /**
25 * <p>
26 * The base class for Swing event adapters.
27 * </p>
28 * <p>
29 * An event adapter is responsible for transforming a Swing specific event
30 * notification into a platform independent form builder event. This base class
31 * provides a great deal of common functionality useful for different event
32 * types. Concrete sub classes will deal with specific event types.
33 * </p>
34 * <p>
35 * This base class already stores important information (e.g. about the
36 * component this event adapter is associated with) in member fields. It also
37 * supports two different ways to map Swing events to platform-independent
38 * events:
39 * <ul>
40 * <li>If a {@code FormEventManager} is specified, its {@code fireEvent()}
41 * method is invoked. This automatically calls all listeners registered for
42 * specific or all components.</li>
43 * <li>It is also possible to map the Swing-specific events to a specific event
44 * listener which has to be passed to the constructor. In this case only this
45 * listener is invoked.</li>
46 * </ul>
47 * </p>
48 *
49 * @author Oliver Heger
50 * @version $Id: SwingEventAdapter.java 205 2012-01-29 18:29:57Z oheger $
51 */
52 public abstract class SwingEventAdapter
53 {
54 /** Stores a reference to the event manager. */
55 private final FormEventManager eventManager;
56
57 /** Stores a reference to the associated event listener. */
58 private final FormEventListener listener;
59
60 /** Stores a reference to the associated component handler. */
61 private final ComponentHandler<?> handler;
62
63 /** The name of the component this adapter is registered at. */
64 private final String name;
65
66 /**
67 * Creates a new instance of {@code SwingEventAdapter} and sets all
68 * properties.
69 *
70 * @param evMan the {@code FormEventManager}
71 * @param l the event listener
72 * @param h the {@code ComponentHandler}
73 * @param n the name of the component
74 */
75 private SwingEventAdapter(FormEventManager evMan, FormEventListener l,
76 ComponentHandler<?> h, String n)
77 {
78 eventManager = evMan;
79 listener = l;
80 handler = h;
81 name = n;
82 }
83
84 /**
85 * Creates a new instance of {@code SwingEventAdapter} that uses the {@code
86 * FormEventManager} to broadcast events.
87 *
88 * @param eventManager the event manager (must not be <b>null</b>)
89 * @param handler the component handler
90 * @param name the component's name
91 * @throws IllegalArgumentException if the {@code FormEventManager} is
92 * <b>null</b>
93 */
94 protected SwingEventAdapter(FormEventManager eventManager,
95 ComponentHandler<?> handler, String name)
96 {
97 this(eventManager, null, handler, name);
98 if (eventManager == null)
99 {
100 throw new IllegalArgumentException(
101 "FormEventManager must not be null!");
102 }
103 }
104
105 /**
106 * Creates a new instance of {@code SwingEventAdapter} that serves a
107 * specific event listener.
108 *
109 * @param l the event listener (must not be <b>null</b>)
110 * @param handler the {@code ComponentHandler}
111 * @param name the name of the component
112 * @throws IllegalArgumentException if the event listener is <b>null</b>
113 */
114 protected SwingEventAdapter(FormEventListener l,
115 ComponentHandler<?> handler, String name)
116 {
117 this(null, l, handler, name);
118 if (l == null)
119 {
120 throw new IllegalArgumentException(
121 "Event listener must not be null!");
122 }
123 }
124
125 /**
126 * Returns a reference to the form event manager. This can be <b>null</b> if
127 * this adapter is not associated with the event manager.
128 *
129 * @return the event manager
130 */
131 public FormEventManager getEventManager()
132 {
133 return eventManager;
134 }
135
136 /**
137 * Returns the event listener this adapter is associated with. This can be
138 * <b>null</b> if this listener is not associated with an event listener.
139 *
140 * @return the event listener
141 */
142 public FormEventListener getEventListener()
143 {
144 return listener;
145 }
146
147 /**
148 * Returns a reference to the associated component handler.
149 *
150 * @return the component handler
151 */
152 public ComponentHandler<?> getHandler()
153 {
154 return handler;
155 }
156
157 /**
158 * Returns the name of the component this adapter is registered at.
159 *
160 * @return the component name
161 */
162 public String getName()
163 {
164 return name;
165 }
166
167 /**
168 * Notifies the event manager about a new event. With this method an event
169 * can be sent to all registered listeners.
170 *
171 * @param event the event to send
172 */
173 protected void fireEvent(FormEvent event)
174 {
175 if (getEventManager() != null)
176 {
177 getEventManager().fireEvent(event, getListenerType());
178 }
179 else
180 {
181 getListenerType().callListener(getEventListener(), event);
182 }
183 }
184
185 /**
186 * Returns the event listener type used by this adapter. This method must be
187 * defined in concrete sub classes.
188 *
189 * @return the event listener type
190 */
191 protected abstract FormListenerType getListenerType();
192 }