jsampler/view/JSMainFrame.java

/*
 *   JSampler - a java front-end for LinuxSampler
 *
 *   Copyright (C) 2005-2007 Grigor Iliev <grigor@grigoriliev.com>
 *
 *   This file is part of JSampler.
 *
 *   JSampler is free software; you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License version 2
 *   as published by the Free Software Foundation.
 *
 *   JSampler is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with JSampler; if not, write to the Free Software
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 *   MA  02111-1307  USA
 */

package org.jsampler.view;

import java.awt.Dialog;
import java.awt.Dimension;
import java.awt.Frame;

import java.awt.event.ActionEvent;
import java.awt.event.KeyEvent;
import java.awt.event.WindowAdapter;
import java.awt.event.WindowEvent;

import java.util.Vector;
import java.util.logging.Level;

import javax.swing.AbstractAction;
import javax.swing.JComponent;
import javax.swing.JFrame;
import javax.swing.KeyStroke;

import org.jsampler.CC;
import org.jsampler.JSampler;
import org.jsampler.Prefs;
import org.jsampler.Server;

import org.jsampler.event.SamplerChannelListEvent;
import org.jsampler.event.SamplerChannelListListener;


/**
 * Defines the skeleton of a JSampler's main frame.
 * @author Grigor Iliev
 */
public abstract class JSMainFrame extends JFrame {
        private final Vector<JSChannelsPane> chnPaneList = new Vector<JSChannelsPane>();
        private boolean autoUpdateChannelListUI = true;
        
        /** Creates a new instance of <code>JSMainFrame</code>. */
        public
        JSMainFrame() {
                super(JSampler.NAME + ' ' + JSampler.VERSION);
                
                setDefaultCloseOperation(DO_NOTHING_ON_CLOSE);
                addWindowListener(new WindowAdapter() {
                        public void
                        windowClosing(WindowEvent we) { onWindowClose(); }
                });
                
                CC.getSamplerModel().addSamplerChannelListListener(new EventHandler());
                
                getRootPane().getInputMap(JComponent.WHEN_ANCESTOR_OF_FOCUSED_COMPONENT).put (
                        KeyStroke.getKeyStroke(KeyEvent.VK_G, KeyEvent.CTRL_MASK | KeyEvent.SHIFT_MASK),
                        "RunGarbageCollector"
                );
                
                getRootPane().getActionMap().put ("RunGarbageCollector", new AbstractAction() {
                        public void
                        actionPerformed(ActionEvent e) {
                                System.gc();
                        }
                });
        }
        
        /**
         * Invoked when this window is about to close.
         * Don't forget to call <code>super.onWindowClose()</code> at the end,
         * when override this method.
         */
        protected void
        onWindowClose() {
                CC.cleanExit();
        }
        
        /**
         * Invoked on startup when no JSampler home directory is specified
         * or the specified JSampler home directory doesn't exist.
         * This method should ask the user to specify a JSampler
         * home directory and then set the specified JSampler home directory using
         * {@link org.jsampler.CC#setJSamplerHome} method.
         * @see org.jsampler.CC#getJSamplerHome
         * @see org.jsampler.CC#setJSamplerHome
         */
        public abstract void installJSamplerHome();
        
        /**
         * Shows a detailed error information about the specified exception.
         */
        public abstract void showDetailedErrorMessage(Frame owner, String err, String details);
        
        /**
         * Shows a detailed error information about the specified exception.
         */
        public abstract void showDetailedErrorMessage(Dialog owner, String err, String details);
        
        /**
         * Returns a list containing all <code>JSChannelsPane</code>s added to the view.
         * @return A list containing all <code>JSChannelsPane</code>s added to the view.
         * @see #addChannelsPane
         * @see #removeChannelsPane
         */
        public Vector<JSChannelsPane>
        getChannelsPaneList() { return chnPaneList; }
        
        /**
         * Return the <code>JSChannelsPane</code> at the specified position.
         * @param idx The position of the <code>JSChannelsPane</code> to be returned.
         * @return The <code>JSChannelsPane</code> at the specified position.
         */
        public JSChannelsPane
        getChannelsPane(int idx) { return chnPaneList.get(idx); }
        
        /**
         * Adds the specified <code>JSChannelsPane</code> to the view.
         * @param chnPane The <code>JSChannelsPane</code> to be added.
         */
        public void
        addChannelsPane(JSChannelsPane chnPane) { chnPaneList.add(chnPane); }
        
        /**
         * Removes the specified <code>JSChannelsPane</code> from the view.
         * Override this method to remove <code>chnPane</code> from the view,
         * and don't forget to call <code>super.removeChannelsPane(chnPane);</code>.
         * @param chnPane The <code>JSChannelsPane</code> to be removed.
         * @return <code>true</code> if the specified code>JSChannelsPane</code>
         * is actually removed from the view, <code>false</code> otherwise.
         */
        public boolean
        removeChannelsPane(JSChannelsPane chnPane) { return chnPaneList.remove(chnPane); }
        
        /**
         * Gets the current number of <code>JSChannelsPane</code>s added to the view.
         * @return The current number of <code>JSChannelsPane</code>s added to the view.
         */
        public int
        getChannelsPaneCount() { return chnPaneList.size(); }
        
        /**
         * Inserts the specified <code>JSChannelsPane</code> at the specified position
         * in the view and in the code>JSChannelsPane</code> list.
         * Where and how this pane will be shown depends on the view/GUI implementation.
         * Note that some GUI implementation may have only one pane containing sampler channels.
         * @param pane The <code>JSChannelsPane</code> to be inserted.
         * @param idx Specifies the position of the <code>JSChannelsPane</code>.
         * @see #getChannelsPaneList
         */
        public abstract void insertChannelsPane(JSChannelsPane pane, int idx);
        
        /**
         * Gets the <code>JSChannelsPane</code> that is currently shown,
         * or has the focus if more than one channels' panes are shown.
         * If the GUI implementation has only one pane containing sampler channels,
         * than this method should always return that pane (the <code>JSChannelsPane</code>
         * with index 0).
         * @return The selected <code>JSChannelsPane</code>.
         */
        public abstract JSChannelsPane getSelectedChannelsPane();
        
        /**
         * Gets the server address to which to connect. If the server should be
         * manually selected, a dialog asking the user to choose a server is displayed.
         */
        public abstract Server getServer();
        
        /**
         * Gets the server address to which to connect. If the server should be
         * manually selected, a dialog asking the user to choose a server is displayed.
         * @param manualSelect Determines whether the server should be manually selected.
         */
        public abstract Server getServer(boolean manualSelect);
        
        /**
         * Sets the <code>JSChannelsPane</code> to be selected.
         * @param pane The <code>JSChannelsPane</code> to be shown.
         */
        public abstract void setSelectedChannelsPane(JSChannelsPane pane);
        
        private class EventHandler implements SamplerChannelListListener {
                /**
                 * Invoked when a new sampler channel is created.
                 * @param e A <code>SamplerChannelListEvent</code>
                 * instance providing the event information.
                 */
                public void
                channelAdded(SamplerChannelListEvent e) {
                        Integer id = e.getChannelModel().getChannelId();
                        if(findChannel(id) != null) {
                                CC.getLogger().log(Level.WARNING, "JSMainFrame.channelExist!", id);
                                return;
                        }
                        
                        getSelectedChannelsPane().addChannel(e.getChannelModel());
                }
        
                /**
                 * Invoked when a sampler channel is removed.
                 * @param e A <code>SamplerChannelListEvent</code>
                 * instance providing the event information.
                 */
                public void
                channelRemoved(SamplerChannelListEvent e) {
                        removeChannel(e.getChannelModel().getChannelId());
                }
        }
        
        /**
         * Searches for the first occurence of a channel with numerical ID <code>id</code>.
         * @return The first occurence of a channel with numerical ID <code>id</code> or
         * <code>null</code> if there is no channel with numerical ID <code>id</code>.
         */
        public JSChannel
        findChannel(int id) {
                if(id < 0) return null;
                
                for(JSChannelsPane cp : getChannelsPaneList()) {
                        for(JSChannel c : cp.getChannels()) if(c.getChannelId() == id) return c;
                }
                
                return null;
        }
        
        /**
         * Removes the first occurence of a channel with numerical ID <code>id</code>.
         * This method is invoked when a sampler channel is removed in the back-end.
         * @return The removed channel or <code>null</code>
         * if there is no channel with numerical ID <code>id</code>.
         */
        public JSChannel
        removeChannel(int id) {
                if(id < 0) return null;
                
                for(JSChannelsPane cp : getChannelsPaneList()) {
                        for(JSChannel c : cp.getChannels()) {
                                if(c.getChannelId() == id) {
                                        cp.removeChannel(c);
                                        return c;
                                }
                        }
                }
                
                return null;
        }
        
        /**
         * Determines whether the channel list UI should be automatically updated
         * when channel is added/removed. The default value is <code>true</code>.
         */
        public boolean
        getAutoUpdateChannelListUI() { return autoUpdateChannelListUI; }
        
        /**
         * Determines whether the channel list UI should be automatically updated
         * when channel is added/removed.
         */
        public void
        setAutoUpdateChannelListUI(boolean b) {
                if(b == autoUpdateChannelListUI) return;
                
                autoUpdateChannelListUI = b;
                for(JSChannelsPane cp : getChannelsPaneList()) {
                        cp.setAutoUpdate(b);
                }
        }
        
        /**
         * Updates the channel list UI.
         */
        public void
        updateChannelListUI() {
                for(JSChannelsPane cp : getChannelsPaneList()) {
                        cp.updateChannelListUI();
                }
        }
}
1	iliev	787	/*
2			* JSampler - a java front-end for LinuxSampler
3			*
4	iliev	1285	* Copyright (C) 2005-2007 Grigor Iliev <grigor@grigoriliev.com>
5	iliev	787	*
6			* This file is part of JSampler.
7			*
8			* JSampler is free software; you can redistribute it and/or modify
9			* it under the terms of the GNU General Public License version 2
10			* as published by the Free Software Foundation.
11			*
12			* JSampler is distributed in the hope that it will be useful,
13			* but WITHOUT ANY WARRANTY; without even the implied warranty of
14			* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15			* GNU General Public License for more details.
16			*
17			* You should have received a copy of the GNU General Public License
18			* along with JSampler; if not, write to the Free Software
19			* Foundation, Inc., 59 Temple Place, Suite 330, Boston,
20			* MA 02111-1307 USA
21			*/
22
23			package org.jsampler.view;
24
25	iliev	1204	import java.awt.Dialog;
26	iliev	842	import java.awt.Dimension;
27	iliev	1204	import java.awt.Frame;
28	iliev	842
29	iliev	1734	import java.awt.event.ActionEvent;
30			import java.awt.event.KeyEvent;
31	iliev	787	import java.awt.event.WindowAdapter;
32			import java.awt.event.WindowEvent;
33
34			import java.util.Vector;
35			import java.util.logging.Level;
36
37	iliev	1734	import javax.swing.AbstractAction;
38			import javax.swing.JComponent;
39	iliev	787	import javax.swing.JFrame;
40	iliev	1734	import javax.swing.KeyStroke;
41	iliev	787
42			import org.jsampler.CC;
43			import org.jsampler.JSampler;
44	iliev	842	import org.jsampler.Prefs;
45	iliev	1688	import org.jsampler.Server;
46	iliev	787
47			import org.jsampler.event.SamplerChannelListEvent;
48			import org.jsampler.event.SamplerChannelListListener;
49
50	iliev	1204
51	iliev	787	/**
52	iliev	911	* Defines the skeleton of a JSampler's main frame.
53	iliev	787	* @author Grigor Iliev
54			*/
55			public abstract class JSMainFrame extends JFrame {
56			private final Vector<JSChannelsPane> chnPaneList = new Vector<JSChannelsPane>();
57	iliev	1734	private boolean autoUpdateChannelListUI = true;
58	iliev	787
59	iliev	911	/** Creates a new instance of <code>JSMainFrame</code>. */
60	iliev	787	public
61			JSMainFrame() {
62			super(JSampler.NAME + ' ' + JSampler.VERSION);
63
64			setDefaultCloseOperation(DO_NOTHING_ON_CLOSE);
65			addWindowListener(new WindowAdapter() {
66			public void
67	iliev	842	windowClosing(WindowEvent we) { onWindowClose(); }
68	iliev	787	});
69
70			CC.getSamplerModel().addSamplerChannelListListener(new EventHandler());
71	iliev	1734
72			getRootPane().getInputMap(JComponent.WHEN_ANCESTOR_OF_FOCUSED_COMPONENT).put (
73			KeyStroke.getKeyStroke(KeyEvent.VK_G, KeyEvent.CTRL_MASK \| KeyEvent.SHIFT_MASK),
74			"RunGarbageCollector"
75			);
76
77			getRootPane().getActionMap().put ("RunGarbageCollector", new AbstractAction() {
78			public void
79			actionPerformed(ActionEvent e) {
80			System.gc();
81			}
82			});
83	iliev	787	}
84
85	iliev	911	/**
86			* Invoked when this window is about to close.
87			* Don't forget to call <code>super.onWindowClose()</code> at the end,
88			* when override this method.
89			*/
90			protected void
91	iliev	842	onWindowClose() {
92			CC.cleanExit();
93			}
94
95	iliev	911	/**
96	iliev	1143	* Invoked on startup when no JSampler home directory is specified
97			* or the specified JSampler home directory doesn't exist.
98			* This method should ask the user to specify a JSampler
99			* home directory and then set the specified JSampler home directory using
100			* {@link org.jsampler.CC#setJSamplerHome} method.
101			* @see org.jsampler.CC#getJSamplerHome
102			* @see org.jsampler.CC#setJSamplerHome
103			*/
104			public abstract void installJSamplerHome();
105
106			/**
107	iliev	1204	* Shows a detailed error information about the specified exception.
108			*/
109			public abstract void showDetailedErrorMessage(Frame owner, String err, String details);
110
111			/**
112			* Shows a detailed error information about the specified exception.
113			*/
114			public abstract void showDetailedErrorMessage(Dialog owner, String err, String details);
115
116			/**
117	iliev	911	* Returns a list containing all <code>JSChannelsPane</code>s added to the view.
118			* @return A list containing all <code>JSChannelsPane</code>s added to the view.
119			* @see #addChannelsPane
120			* @see #removeChannelsPane
121			*/
122	iliev	787	public Vector<JSChannelsPane>
123			getChannelsPaneList() { return chnPaneList; }
124
125	iliev	911	/**
126			* Return the <code>JSChannelsPane</code> at the specified position.
127			* @param idx The position of the <code>JSChannelsPane</code> to be returned.
128			* @return The <code>JSChannelsPane</code> at the specified position.
129			*/
130	iliev	787	public JSChannelsPane
131			getChannelsPane(int idx) { return chnPaneList.get(idx); }
132
133	iliev	911	/**
134			* Adds the specified <code>JSChannelsPane</code> to the view.
135			* @param chnPane The <code>JSChannelsPane</code> to be added.
136			*/
137	iliev	787	public void
138			addChannelsPane(JSChannelsPane chnPane) { chnPaneList.add(chnPane); }
139
140	iliev	911	/**
141			* Removes the specified <code>JSChannelsPane</code> from the view.
142			* Override this method to remove <code>chnPane</code> from the view,
143			* and don't forget to call <code>super.removeChannelsPane(chnPane);</code>.
144			* @param chnPane The <code>JSChannelsPane</code> to be removed.
145			* @return <code>true</code> if the specified code>JSChannelsPane</code>
146			* is actually removed from the view, <code>false</code> otherwise.
147			*/
148	iliev	787	public boolean
149			removeChannelsPane(JSChannelsPane chnPane) { return chnPaneList.remove(chnPane); }
150
151	iliev	911	/**
152			* Gets the current number of <code>JSChannelsPane</code>s added to the view.
153			* @return The current number of <code>JSChannelsPane</code>s added to the view.
154			*/
155	iliev	787	public int
156			getChannelsPaneCount() { return chnPaneList.size(); }
157
158	iliev	911	/**
159			* Inserts the specified <code>JSChannelsPane</code> at the specified position
160			* in the view and in the code>JSChannelsPane</code> list.
161			* Where and how this pane will be shown depends on the view/GUI implementation.
162			* Note that some GUI implementation may have only one pane containing sampler channels.
163			* @param pane The <code>JSChannelsPane</code> to be inserted.
164			* @param idx Specifies the position of the <code>JSChannelsPane</code>.
165			* @see #getChannelsPaneList
166			*/
167	iliev	787	public abstract void insertChannelsPane(JSChannelsPane pane, int idx);
168	iliev	911
169			/**
170			* Gets the <code>JSChannelsPane</code> that is currently shown,
171			* or has the focus if more than one channels' panes are shown.
172			* If the GUI implementation has only one pane containing sampler channels,
173			* than this method should always return that pane (the <code>JSChannelsPane</code>
174			* with index 0).
175			* @return The selected <code>JSChannelsPane</code>.
176			*/
177	iliev	787	public abstract JSChannelsPane getSelectedChannelsPane();
178	iliev	911
179			/**
180	iliev	1688	* Gets the server address to which to connect. If the server should be
181			* manually selected, a dialog asking the user to choose a server is displayed.
182			*/
183			public abstract Server getServer();
184
185			/**
186			* Gets the server address to which to connect. If the server should be
187			* manually selected, a dialog asking the user to choose a server is displayed.
188			* @param manualSelect Determines whether the server should be manually selected.
189			*/
190			public abstract Server getServer(boolean manualSelect);
191
192			/**
193	iliev	911	* Sets the <code>JSChannelsPane</code> to be selected.
194			* @param pane The <code>JSChannelsPane</code> to be shown.
195			*/
196	iliev	787	public abstract void setSelectedChannelsPane(JSChannelsPane pane);
197
198			private class EventHandler implements SamplerChannelListListener {
199			/**
200			* Invoked when a new sampler channel is created.
201			* @param e A <code>SamplerChannelListEvent</code>
202			* instance providing the event information.
203			*/
204			public void
205			channelAdded(SamplerChannelListEvent e) {
206	iliev	1143	Integer id = e.getChannelModel().getChannelId();
207	iliev	787	if(findChannel(id) != null) {
208			CC.getLogger().log(Level.WARNING, "JSMainFrame.channelExist!", id);
209			return;
210			}
211
212			getSelectedChannelsPane().addChannel(e.getChannelModel());
213			}
214
215			/**
216			* Invoked when a sampler channel is removed.
217			* @param e A <code>SamplerChannelListEvent</code>
218			* instance providing the event information.
219			*/
220			public void
221			channelRemoved(SamplerChannelListEvent e) {
222	iliev	1143	removeChannel(e.getChannelModel().getChannelId());
223	iliev	787	}
224			}
225
226			/**
227			* Searches for the first occurence of a channel with numerical ID <code>id</code>.
228			* @return The first occurence of a channel with numerical ID <code>id</code> or
229			* <code>null</code> if there is no channel with numerical ID <code>id</code>.
230			*/
231			public JSChannel
232			findChannel(int id) {
233			if(id < 0) return null;
234
235			for(JSChannelsPane cp : getChannelsPaneList()) {
236	iliev	1143	for(JSChannel c : cp.getChannels()) if(c.getChannelId() == id) return c;
237	iliev	787	}
238
239			return null;
240			}
241
242			/**
243			* Removes the first occurence of a channel with numerical ID <code>id</code>.
244			* This method is invoked when a sampler channel is removed in the back-end.
245			* @return The removed channel or <code>null</code>
246			* if there is no channel with numerical ID <code>id</code>.
247			*/
248			public JSChannel
249			removeChannel(int id) {
250			if(id < 0) return null;
251
252			for(JSChannelsPane cp : getChannelsPaneList()) {
253			for(JSChannel c : cp.getChannels()) {
254	iliev	1143	if(c.getChannelId() == id) {
255	iliev	787	cp.removeChannel(c);
256			return c;
257			}
258			}
259			}
260
261			return null;
262			}
263	iliev	1734
264			/**
265			* Determines whether the channel list UI should be automatically updated
266			* when channel is added/removed. The default value is <code>true</code>.
267			*/
268			public boolean
269			getAutoUpdateChannelListUI() { return autoUpdateChannelListUI; }
270
271			/**
272			* Determines whether the channel list UI should be automatically updated
273			* when channel is added/removed.
274			*/
275			public void
276			setAutoUpdateChannelListUI(boolean b) {
277			if(b == autoUpdateChannelListUI) return;
278
279			autoUpdateChannelListUI = b;
280			for(JSChannelsPane cp : getChannelsPaneList()) {
281			cp.setAutoUpdate(b);
282			}
283			}
284
285			/**
286			* Updates the channel list UI.
287			*/
288			public void
289			updateChannelListUI() {
290			for(JSChannelsPane cp : getChannelsPaneList()) {
291			cp.updateChannelListUI();
292			}
293			}
294	iliev	787	}