001    package org.LiveGraph.gui;
002    
003    import javax.swing.JPanel;
004    
005    import org.LiveGraph.LiveGraph;
006    import org.LiveGraph.events.Event;
007    import org.LiveGraph.events.EventListener;
008    import org.LiveGraph.events.EventManager;
009    import org.LiveGraph.events.EventType;
010    import org.LiveGraph.settings.SettingsEvent;
011    
012    
013    /**
014     * This is the superclass for LiveGraph main settings panels that may be inserted directly into
015     * a window (or some other kind of GUI frame).This class executes event handling commonly shared
016     * between settings panels. Each panel may ovverride any of this behaviour if desired. 
017     * 
018     * <p>
019     *   <strong>LiveGraph</strong>
020     *   (<a href="http://www.live-graph.org" target="_blank">http://www.live-graph.org</a>).
021     * </p> 
022     * <p>Copyright (c) 2007-2008 by G. Paperin.</p>
023     * <p>File: LiveGraphSettingsPanel.java</p>
024     * <p style="font-size:smaller;">Redistribution and use in source and binary forms, with or
025     *    without modification, are permitted provided that the following terms and conditions are met:
026     * </p>
027     * <p style="font-size:smaller;">1. Redistributions of source code must retain the above
028     *    acknowledgement of the LiveGraph project and its web-site, the above copyright notice,
029     *    this list of conditions and the following disclaimer.<br />
030     *    2. Redistributions in binary form must reproduce the above acknowledgement of the
031     *    LiveGraph project and its web-site, the above copyright notice, this list of conditions
032     *    and the following disclaimer in the documentation and/or other materials provided with
033     *    the distribution.<br />
034     *    3. All advertising materials mentioning features or use of this software or any derived
035     *    software must display the following acknowledgement:<br />
036     *    <em>This product includes software developed by the LiveGraph project and its
037     *    contributors.<br />(http://www.live-graph.org)</em><br />
038     *    4. All advertising materials distributed in form of HTML pages or any other technology
039     *    permitting active hyper-links that mention features or use of this software or any
040     *    derived software must display the acknowledgment specified in condition 3 of this
041     *    agreement, and in addition, include a visible and working hyper-link to the LiveGraph
042     *    homepage (http://www.live-graph.org).
043     * </p>
044     * <p style="font-size:smaller;">THIS SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY
045     *    OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
046     *    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND  NONINFRINGEMENT. IN NO EVENT SHALL
047     *    THE AUTHORS, CONTRIBUTORS OR COPYRIGHT  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
048     *    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING  FROM, OUT OF OR
049     *    IN CONNECTION WITH THE SOFTWARE OR THE USE OR  OTHER DEALINGS IN THE SOFTWARE.
050     * </p>
051     * 
052     * @author Greg Paperin (<a href="http://www.paperin.org" target="_blank">http://www.paperin.org</a>)
053     * @version {@value org.LiveGraph.LiveGraph#version}
054     *
055     */
056    public abstract class LiveGraphSettingsPanel extends JPanel implements EventListener {
057    
058    /**
059     * Permits to register as listener with the main LiveGraph event manager and
060     * only with the main LiveGraph event manager.
061     * 
062     * @param manager The {@code EventManager} for the registering attempt.
063     * @return {@code (LiveGraph.application().eventManager() == manager)}.
064     * @see EventListener#permissionRegisterWithEventManager(EventManager)
065     */
066    public boolean permissionRegisterWithEventManager(EventManager manager) {
067            return LiveGraph.application().eventManager() == manager;
068    }
069    
070    /**
071     * Does not permit any unregistering.
072     * 
073     * @param manager The {@code EventManager} for the registering attempt.
074     * @return {@code false}.
075     * @see EventListener#permissionUnregisterWithEventManager(EventManager)
076     */
077    public boolean permissionUnregisterWithEventManager(EventManager manager) {
078            return false;
079    }
080    
081    /**
082     * Does nothing.
083     * 
084     * @param manager The {@code EventManager} with which this {@code EventListener} is now registered.
085     * @see EventListener#completedRegisterWithEventManager(EventManager)
086     */
087    public void completedRegisterWithEventManager(EventManager manager) { }
088    
089    /**
090     * Does nothing.
091     * 
092     * @param manager The {@code EventManager} with which this {@code EventListener} is now unregistered.
093     * @see EventListener#completedUnregisterWithEventManager(EventManager)
094     */
095    public void completedUnregisterWithEventManager(EventManager manager) { }
096    
097    /**
098     * Does nothing.
099     * 
100     * @param event An event in which this {@code EventListener} may be interested.
101     * @return {@code false}.
102     * @see EventListener#checkEventInterest(Event)
103     */
104    public boolean checkEventInterest(Event<? extends EventType> event) {
105            return false;
106    }
107    
108    /**
109     * Does nothing.
110     * 
111     * @param event The event to be validated.
112     * @param soFar Whether {@code event} has been successfuly validated by whichever {@code EventListener}s
113     * (if any) were invoked to validate {@code event} before this {@code EventListener}.
114     * @return {@code true}.
115     * @see EventListener#checkEventValid(Event, boolean)
116     */
117    public boolean checkEventValid(Event<? extends EventType> event, boolean soFar) {
118            return true;
119    }
120    
121    /**
122     * Calls {@link #processSettingsEvent(Event)} to process LiveGraph settings events.
123     * Subclasses can override this method to process events of other types, however,
124     * they <em>must</em> make sure to call this superclass method to ensure that
125     * the settings events handled here are processed correctly. 
126     * 
127     * @param event Event to process.
128     */
129    public void eventRaised(Event<? extends EventType> event) {
130            
131            if (event.getDomain() == SettingsEvent.class) {
132                    processSettingsEvent(event.cast(SettingsEvent.class));
133                    return;
134            }
135    }
136    
137    /**
138     * This method must be overridden by subclasses in order to process settings events.
139     * 
140     * @param event A settings event.
141     */
142    protected abstract void processSettingsEvent(Event<SettingsEvent> event);
143    
144    } // public class LiveGraphSettingsPanel