jsampler/view/JSMainFrame.java

/*
 *   JSampler - a java front-end for LinuxSampler
 *
 *   Copyright (C) 2005-2011 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.util.Vector;

import org.jsampler.CC;
import org.jsampler.LSConsoleModel;
import org.jsampler.SamplerChannelModel;
import org.jsampler.Server;
import org.jsampler.event.ListSelectionListener;


/**
 * Defines the skeleton of a JSampler's main frame.
 * @author Grigor Iliev
 */
public interface JSMainFrame<CP extends JSChannelsPane> {
        /**
         * Invoked when this window is about to close.
         * Don't forget to call <code>super.onWindowClose()</code> at the end,
         * when override this method.
         */
        public void onWindowClose();
        
        /**
         * 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 void installJSamplerHome();
        
        /** Shows a detailed error information about the specified exception. */
        public void showDetailedErrorMessage(String err, String details);
        
        public void handleConnectionFailure();
        
        /**
         * Registers the specified listener for receiving event messages.
         * @param l The <code>ListSelectionListener</code> to register.
         */
        public void
        addChannelsPaneSelectionListener(ListSelectionListener l);
        
        /**
         * Removes the specified listener.
         * @param l The <code>ListSelectionListener</code> to remove.
         */
        public void
        removeChannelsPaneSelectionListener(ListSelectionListener l);
        
        /**
         * Returns a list containing all channels' panes added to the view.
         * @return A list containing all channels' panes added to the view.
         * @see #addChannelsPane
         * @see #removeChannelsPane
         */
        public Vector<CP> getChannelsPaneList();
        
        /**
         * Return the channels' pane at the specified position.
         * @param idx The position of the channels' pane to be returned.
         * @return The channels' pane at the specified position.
         */
        public CP getChannelsPane(int idx);
        
        /**
         * Adds the specified channels' pane to the view.
         * @param chnPane The channels' pane to be added.
         */
        public void addChannelsPane(CP chnPane);
        
        /**
         * Removes the specified channels' pane 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 channels' pane 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(CP chnPane);
        
        /**
         * Gets the current number of channels' panes added to the view.
         * @return The current number of channels' panes added to the view.
         */
        public int getChannelsPaneCount();
        
        /**
         * Returns the index of the specified channels pane, or -1 if
         * the specified channels pane is not found.
         */
        public int getChannelsPaneIndex(CP chnPane);
        
        public void setVisible(boolean b);
        
        /**
         * Inserts the specified channels' pane at the specified position
         * in the view and in the channels' pane 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 channels' pane to be inserted.
         * @param idx Specifies the position of the channels' pane.
         * @see #getChannelsPaneList
         */
        public void insertChannelsPane(CP pane, int idx);
        
        /**
         * Gets the channels' pane 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 channels' pane
         * with index 0).
         * @return The selected channels' pane.
         */
        public CP getSelectedChannelsPane();
        
        /**
         * Get the server address to which to connect (asynchronously if needed)
         * and pass it to <code>r.run()</code>.
         * If the server should be manually selected, a dialog asking
         * the user to choose a server is displayed.
         */
        public void getServer(CC.Run<Server> r);
        
        /**
         * Get the server address to which to connect (asynchronously if needed)
         * and pass it to <code>r.run()</code>.
         * 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 void getServer(CC.Run<Server> r, boolean manualSelect);
        
        /**
         * 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 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 Server getServer(boolean manualSelect);

        /**
         * Gets the LS Console model.
         * @return The LS Console model or <code>null</code>.
         */
        public LSConsoleModel getLSConsoleModel();
        
        /**
         * Sets the channels' pane to be selected.
         * Note that all registered listeners should be notified
         * when the selection is changed.
         * @param pane The channels' pane to be shown.
         * @see #fireChannelsPaneSelectionChanged
         */
        public void setSelectedChannelsPane(CP pane);
        
        /**
         * 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);
        
        /**
         * Removes the first occurrence 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);
        
        /**
         * Gets the zero-based position of the specified sampler channel
         * in the channels pane, to which the channel is added.
         * Note that the position may change when adding/removing sampler channels.
         * @return The zero-based position of the specified sampler channel
         * in the channels pane, or -1 if the specified channels is not found.
         */
        public int getChannelNumber(SamplerChannelModel channel);
        
        /**
         * Returns a string in the format <code>channelPaneNumber.channelNumber</code>,
         * where <code>channelPaneNumber</code> is the one-based number of the channels
         * pane containing the specified channel and <code>channelNumber</code> is the
         * one-based number of the channel's position in the channels pane.
         * Note that this path may change when adding/removing channels/channels panes.
         * @return The channels path, or <code>null</code> if the specified channels is not found.
         */
        public String getChannelPath(SamplerChannelModel channel);
        
        /**
         * Gets the zero-based number of the channels pane,
         * to which the specified sampler channel is added.
         * Note that the can be moved from one channels pane to another.
         * @return The zero-based index of the channels pane,
         * to which the specified sampler channel is added, or
         * -1 if the specified channels is not found.
         */
        public int getChannelsPaneNumber(SamplerChannelModel channel);
        
        /**
         * Sends the specified script to the backend.
         * @param script The file name of the script to run.
         */
        public void runScript(String script);
        
        /**
         * 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();
        
        /**
         * Determines whether the channel list UI should be automatically updated
         * when channel is added/removed.
         */
        public void setAutoUpdateChannelListUI(boolean b);
        
        /**
         * Updates the channel list UI.
         */
        public void updateChannelListUI();
}
1	iliev	787	/*
2			* JSampler - a java front-end for LinuxSampler
3			*
4	iliev	2288	* Copyright (C) 2005-2011 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			import java.util.Vector;
26
27			import org.jsampler.CC;
28	iliev	1883	import org.jsampler.LSConsoleModel;
29	iliev	1785	import org.jsampler.SamplerChannelModel;
30	iliev	1688	import org.jsampler.Server;
31	iliev	2288	import org.jsampler.event.ListSelectionListener;
32	iliev	787
33
34			/**
35	iliev	911	* Defines the skeleton of a JSampler's main frame.
36	iliev	787	* @author Grigor Iliev
37			*/
38	iliev	2288	public interface JSMainFrame<CP extends JSChannelsPane> {
39	iliev	911	/**
40			* Invoked when this window is about to close.
41			* Don't forget to call <code>super.onWindowClose()</code> at the end,
42			* when override this method.
43			*/
44	iliev	2288	public void onWindowClose();
45	iliev	842
46	iliev	911	/**
47	iliev	1143	* Invoked on startup when no JSampler home directory is specified
48			* or the specified JSampler home directory doesn't exist.
49			* This method should ask the user to specify a JSampler
50			* home directory and then set the specified JSampler home directory using
51			* {@link org.jsampler.CC#setJSamplerHome} method.
52			* @see org.jsampler.CC#getJSamplerHome
53			* @see org.jsampler.CC#setJSamplerHome
54			*/
55	iliev	2288	public void installJSamplerHome();
56	iliev	1143
57	iliev	2288	/** Shows a detailed error information about the specified exception. */
58			public void showDetailedErrorMessage(String err, String details);
59	iliev	1204
60	iliev	2288	public void handleConnectionFailure();
61	iliev	1204
62			/**
63	iliev	1785	* Registers the specified listener for receiving event messages.
64			* @param l The <code>ListSelectionListener</code> to register.
65			*/
66			public void
67	iliev	2288	addChannelsPaneSelectionListener(ListSelectionListener l);
68	iliev	1785
69			/**
70			* Removes the specified listener.
71			* @param l The <code>ListSelectionListener</code> to remove.
72			*/
73			public void
74	iliev	2288	removeChannelsPaneSelectionListener(ListSelectionListener l);
75	iliev	1785
76			/**
77	iliev	2288	* Returns a list containing all channels' panes added to the view.
78			* @return A list containing all channels' panes added to the view.
79	iliev	911	* @see #addChannelsPane
80			* @see #removeChannelsPane
81			*/
82	iliev	2288	public Vector<CP> getChannelsPaneList();
83	iliev	787
84	iliev	911	/**
85	iliev	2288	* Return the channels' pane at the specified position.
86			* @param idx The position of the channels' pane to be returned.
87			* @return The channels' pane at the specified position.
88	iliev	911	*/
89	iliev	2288	public CP getChannelsPane(int idx);
90	iliev	787
91	iliev	911	/**
92	iliev	2288	* Adds the specified channels' pane to the view.
93			* @param chnPane The channels' pane to be added.
94	iliev	911	*/
95	iliev	2288	public void addChannelsPane(CP chnPane);
96	iliev	787
97	iliev	911	/**
98	iliev	2288	* Removes the specified channels' pane from the view.
99	iliev	911	* Override this method to remove <code>chnPane</code> from the view,
100			* and don't forget to call <code>super.removeChannelsPane(chnPane);</code>.
101	iliev	2288	* @param chnPane The channels' pane to be removed.
102	iliev	911	* @return <code>true</code> if the specified code>JSChannelsPane</code>
103			* is actually removed from the view, <code>false</code> otherwise.
104			*/
105	iliev	2288	public boolean removeChannelsPane(CP chnPane);
106	iliev	787
107	iliev	911	/**
108	iliev	2288	* Gets the current number of channels' panes added to the view.
109			* @return The current number of channels' panes added to the view.
110	iliev	911	*/
111	iliev	2288	public int getChannelsPaneCount();
112	iliev	787
113	iliev	911	/**
114	iliev	1785	* Returns the index of the specified channels pane, or -1 if
115			* the specified channels pane is not found.
116			*/
117	iliev	2288	public int getChannelsPaneIndex(CP chnPane);
118	iliev	1785
119	iliev	2288	public void setVisible(boolean b);
120
121	iliev	1785	/**
122	iliev	2288	* Inserts the specified channels' pane at the specified position
123			* in the view and in the channels' pane list.
124	iliev	911	* Where and how this pane will be shown depends on the view/GUI implementation.
125			* Note that some GUI implementation may have only one pane containing sampler channels.
126	iliev	2288	* @param pane The channels' pane to be inserted.
127			* @param idx Specifies the position of the channels' pane.
128	iliev	911	* @see #getChannelsPaneList
129			*/
130	iliev	2288	public void insertChannelsPane(CP pane, int idx);
131	iliev	911
132			/**
133	iliev	2288	* Gets the channels' pane that is currently shown,
134	iliev	911	* or has the focus if more than one channels' panes are shown.
135			* If the GUI implementation has only one pane containing sampler channels,
136	iliev	2288	* than this method should always return that pane (the channels' pane
137	iliev	911	* with index 0).
138	iliev	2288	* @return The selected channels' pane.
139	iliev	911	*/
140	iliev	2288	public CP getSelectedChannelsPane();
141	iliev	911
142			/**
143	iliev	2288	* Get the server address to which to connect (asynchronously if needed)
144			* and pass it to <code>r.run()</code>.
145			* If the server should be manually selected, a dialog asking
146			* the user to choose a server is displayed.
147			*/
148			public void getServer(CC.Run<Server> r);
149
150			/**
151			* Get the server address to which to connect (asynchronously if needed)
152			* and pass it to <code>r.run()</code>.
153			* If the server should be manually selected, a dialog asking
154			* the user to choose a server is displayed.
155			* @param manualSelect Determines whether the server should be manually selected.
156			*/
157			public void getServer(CC.Run<Server> r, boolean manualSelect);
158
159			/**
160	iliev	1688	* Gets the server address to which to connect. If the server should be
161			* manually selected, a dialog asking the user to choose a server is displayed.
162			*/
163	iliev	2288	public Server getServer();
164	iliev	1688
165			/**
166			* Gets the server address to which to connect. If the server should be
167			* manually selected, a dialog asking the user to choose a server is displayed.
168			* @param manualSelect Determines whether the server should be manually selected.
169			*/
170	iliev	2288	public Server getServer(boolean manualSelect);
171	iliev	1883
172			/**
173			* Gets the LS Console model.
174			* @return The LS Console model or <code>null</code>.
175			*/
176	iliev	2288	public LSConsoleModel getLSConsoleModel();
177	iliev	1688
178			/**
179	iliev	2288	* Sets the channels' pane to be selected.
180	iliev	1785	* Note that all registered listeners should be notified
181			* when the selection is changed.
182	iliev	2288	* @param pane The channels' pane to be shown.
183	iliev	1785	* @see #fireChannelsPaneSelectionChanged
184	iliev	911	*/
185	iliev	2288	public void setSelectedChannelsPane(CP pane);
186	iliev	787
187			/**
188			* Searches for the first occurence of a channel with numerical ID <code>id</code>.
189			* @return The first occurence of a channel with numerical ID <code>id</code> or
190			* <code>null</code> if there is no channel with numerical ID <code>id</code>.
191			*/
192	iliev	2288	public JSChannel findChannel(int id);
193	iliev	787
194			/**
195	iliev	2200	* Removes the first occurrence of a channel with numerical ID <code>id</code>.
196	iliev	787	* This method is invoked when a sampler channel is removed in the back-end.
197			* @return The removed channel or <code>null</code>
198			* if there is no channel with numerical ID <code>id</code>.
199			*/
200	iliev	2288	public JSChannel removeChannel(int id);
201	iliev	1734
202			/**
203	iliev	1785	* Gets the zero-based position of the specified sampler channel
204			* in the channels pane, to which the channel is added.
205			* Note that the position may change when adding/removing sampler channels.
206			* @return The zero-based position of the specified sampler channel
207			* in the channels pane, or -1 if the specified channels is not found.
208			*/
209	iliev	2288	public int getChannelNumber(SamplerChannelModel channel);
210	iliev	1785
211			/**
212	iliev	2200	* Returns a string in the format <code>channelPaneNumber.channelNumber</code>,
213	iliev	1785	* where <code>channelPaneNumber</code> is the one-based number of the channels
214			* pane containing the specified channel and <code>channelNumber</code> is the
215			* one-based number of the channel's position in the channels pane.
216			* Note that this path may change when adding/removing channels/channels panes.
217			* @return The channels path, or <code>null</code> if the specified channels is not found.
218			*/
219	iliev	2288	public String getChannelPath(SamplerChannelModel channel);
220	iliev	1785
221			/**
222			* Gets the zero-based number of the channels pane,
223			* to which the specified sampler channel is added.
224			* Note that the can be moved from one channels pane to another.
225			* @return The zero-based index of the channels pane,
226			* to which the specified sampler channel is added, or
227			* -1 if the specified channels is not found.
228			*/
229	iliev	2288	public int getChannelsPaneNumber(SamplerChannelModel channel);
230	iliev	1785
231			/**
232	iliev	1786	* Sends the specified script to the backend.
233			* @param script The file name of the script to run.
234			*/
235	iliev	2288	public void runScript(String script);
236	iliev	1786
237			/**
238	iliev	1734	* Determines whether the channel list UI should be automatically updated
239			* when channel is added/removed. The default value is <code>true</code>.
240			*/
241	iliev	2288	public boolean getAutoUpdateChannelListUI();
242	iliev	1734
243			/**
244			* Determines whether the channel list UI should be automatically updated
245			* when channel is added/removed.
246			*/
247	iliev	2288	public void setAutoUpdateChannelListUI(boolean b);
248	iliev	1734
249			/**
250			* Updates the channel list UI.
251			*/
252	iliev	2288	public void updateChannelListUI();
253	iliev	787	}