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	/*
2	* JSampler - a java front-end for LinuxSampler
3	*
4	* Copyright (C) 2005-2011 Grigor Iliev <grigor@grigoriliev.com>
5	*
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	import org.jsampler.LSConsoleModel;
29	import org.jsampler.SamplerChannelModel;
30	import org.jsampler.Server;
31	import org.jsampler.event.ListSelectionListener;
32
33
34	/**
35	* Defines the skeleton of a JSampler's main frame.
36	* @author Grigor Iliev
37	*/
38	public interface JSMainFrame<CP extends JSChannelsPane> {
39	/**
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	public void onWindowClose();
45
46	/**
47	* 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	public void installJSamplerHome();
56
57	/** Shows a detailed error information about the specified exception. */
58	public void showDetailedErrorMessage(String err, String details);
59
60	public void handleConnectionFailure();
61
62	/**
63	* Registers the specified listener for receiving event messages.
64	* @param l The <code>ListSelectionListener</code> to register.
65	*/
66	public void
67	addChannelsPaneSelectionListener(ListSelectionListener l);
68
69	/**
70	* Removes the specified listener.
71	* @param l The <code>ListSelectionListener</code> to remove.
72	*/
73	public void
74	removeChannelsPaneSelectionListener(ListSelectionListener l);
75
76	/**
77	* Returns a list containing all channels' panes added to the view.
78	* @return A list containing all channels' panes added to the view.
79	* @see #addChannelsPane
80	* @see #removeChannelsPane
81	*/
82	public Vector<CP> getChannelsPaneList();
83
84	/**
85	* 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	*/
89	public CP getChannelsPane(int idx);
90
91	/**
92	* Adds the specified channels' pane to the view.
93	* @param chnPane The channels' pane to be added.
94	*/
95	public void addChannelsPane(CP chnPane);
96
97	/**
98	* Removes the specified channels' pane from the view.
99	* Override this method to remove <code>chnPane</code> from the view,
100	* and don't forget to call <code>super.removeChannelsPane(chnPane);</code>.
101	* @param chnPane The channels' pane to be removed.
102	* @return <code>true</code> if the specified code>JSChannelsPane</code>
103	* is actually removed from the view, <code>false</code> otherwise.
104	*/
105	public boolean removeChannelsPane(CP chnPane);
106
107	/**
108	* Gets the current number of channels' panes added to the view.
109	* @return The current number of channels' panes added to the view.
110	*/
111	public int getChannelsPaneCount();
112
113	/**
114	* Returns the index of the specified channels pane, or -1 if
115	* the specified channels pane is not found.
116	*/
117	public int getChannelsPaneIndex(CP chnPane);
118
119	public void setVisible(boolean b);
120
121	/**
122	* Inserts the specified channels' pane at the specified position
123	* in the view and in the channels' pane list.
124	* 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	* @param pane The channels' pane to be inserted.
127	* @param idx Specifies the position of the channels' pane.
128	* @see #getChannelsPaneList
129	*/
130	public void insertChannelsPane(CP pane, int idx);
131
132	/**
133	* Gets the channels' pane that is currently shown,
134	* 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	* than this method should always return that pane (the channels' pane
137	* with index 0).
138	* @return The selected channels' pane.
139	*/
140	public CP getSelectedChannelsPane();
141
142	/**
143	* 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	* 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	public Server getServer();
164
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	public Server getServer(boolean manualSelect);
171
172	/**
173	* Gets the LS Console model.
174	* @return The LS Console model or <code>null</code>.
175	*/
176	public LSConsoleModel getLSConsoleModel();
177
178	/**
179	* Sets the channels' pane to be selected.
180	* Note that all registered listeners should be notified
181	* when the selection is changed.
182	* @param pane The channels' pane to be shown.
183	* @see #fireChannelsPaneSelectionChanged
184	*/
185	public void setSelectedChannelsPane(CP pane);
186
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	public JSChannel findChannel(int id);
193
194	/**
195	* Removes the first occurrence of a channel with numerical ID <code>id</code>.
196	* 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	public JSChannel removeChannel(int id);
201
202	/**
203	* 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	public int getChannelNumber(SamplerChannelModel channel);
210
211	/**
212	* Returns a string in the format <code>channelPaneNumber.channelNumber</code>,
213	* 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	public String getChannelPath(SamplerChannelModel channel);
220
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	public int getChannelsPaneNumber(SamplerChannelModel channel);
230
231	/**
232	* Sends the specified script to the backend.
233	* @param script The file name of the script to run.
234	*/
235	public void runScript(String script);
236
237	/**
238	* 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	public boolean getAutoUpdateChannelListUI();
242
243	/**
244	* Determines whether the channel list UI should be automatically updated
245	* when channel is added/removed.
246	*/
247	public void setAutoUpdateChannelListUI(boolean b);
248
249	/**
250	* Updates the channel list UI.
251	*/
252	public void updateChannelListUI();
253	}