1 /*--------------------------------------------------------------------------
2 * Copyright 2007 utgenome.org
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 //--------------------------------------
17 // GenomeBrowser Project
18 //
19 // Track.java
20 // Since: Jun 5, 2007
21 //
22 // $URL$
23 // $Author$
24 //--------------------------------------
25 package org.utgenome.gwt.utgb.client.track;
26
27 import org.utgenome.gwt.utgb.client.track.lib.ToolBoxTrack;
28 import org.utgenome.gwt.utgb.client.util.CanonicalProperties;
29 import org.utgenome.gwt.utgb.client.util.Properties;
30 import org.utgenome.gwt.utgb.client.util.xml.XMLWriter;
31 import org.utgenome.gwt.utgb.client.view.TrackView;
32
33 import com.google.gwt.core.client.GWT;
34 import com.google.gwt.user.client.ui.Widget;
35
36 /**
37 * Track is an interface for implementing your own track.
38 *
39 * Rather than directly implements this interface, it might be better to start with extending {@link TrackBase} class,
40 * which already implements several naive methods such as {@link #setTrackGroup(TrackGroup)} , {@link #getTrackGroup()},
41 * etc.
42 *
43 *
44 * <p>
45 * Tips to implement your own track:
46 * </p>
47 * <ul>
48 * <li>A {@link Track} must have a {@link Widget} that can be retrieved via {@link #getWidget()} method. This returned
49 * widget is used to display your track.</li>
50 * <li>Initialize your track in the {@link #setUp(TrackFrame, TrackGroup)} method, which is automatically called by the
51 * track group to which your track belongs.</li>
52 * <li>Use {@link #getFrame()}, to interact with {@link TrackFrame} surrounding your track.</li>
53 * <li>Use {@link #getTrackGroup()} to retrieve shared properties (e.g., {@link TrackGroupProperty}, {@link TrackWindow}
54 * , etc.) among tracks within the currnt track group.</li>
55 * <li>Override {@link #onChangeTrackGroupProperty(TrackGroupPropertyChange)} and
56 * {@link #onChangeTrackWindow(TrackWindow)} to recieve changes on properties of the track group. These methods become
57 * active only after {@link #setUp(TrackFrame, TrackGroup)} is called.</li>
58 * </ul>
59 *
60 * <p>
61 * The initialization process of tracks is as follows:
62 * </p>
63 * <ol>
64 * <li>Create an instance of your track using a public consutructor of your track or {@link TrackFactory#newInstance()}
65 * method.</li>
66 * <li>Call the {@link TrackGroup#addTrack(Track)} method to add your tracks.</li>
67 * <li>{@link TrackGroup} automatically calls your {@link Track#setUp(TrackFrame, TrackGroup)} method on appropricate
68 * timing, that is, when {@link TrackFrame} and {@link TrackGroup} are ready.</li>
69 * <li>After the setup, {@link #onChangeTrackGroupProperty(TrackGroupPropertyChange)} and
70 * {@link #onChangeTrackWindow(TrackWindow)} are activated.</li>
71 * <li>{@link Track#refresh()} is called in the {@link TrackQueue}</li>
72 * </ol>
73 *
74 * @author leo
75 *
76 */
77 public interface Track extends TrackEntry, TrackGroupPropertyChangeListener {
78 /**
79 * TrackFactory helps to create new Track instance, which can be used to defer its instantiation.
80 *
81 * Since GWT has no {@link Class.newInstance} method with configurable parameters, you have to implement your own
82 * factory() method for each track to support deferred instantiation.
83 *
84 * <p>
85 * Note that, {@link GWT#create(Class)} supports deferred instantiation, but you cannot configure any parameter
86 * values, when instanticate classes.
87 * </p>
88 *
89 * <p>
90 * How to use:
91 * </p>
92 * <code>
93 * class YourOwnTrack extends TrackBase
94 * {
95 * public static abstract TrackFactory factory()
96 * {
97 * return new TrackFactory() {
98 * Map properties = new HashMap();
99 *
100 * public Track newInstance() {]
101 * Track track = new YourOwnTrack();
102 *
103 * // You should set properties to a Track instance.
104 * // for example
105 * //
106 * // Set propertySet = properties.entrySet();
107 * // Iterator it = propertySet.iterator();
108 * // while ( it.hasNext() ) {
109 * // Map.Entry entry = (Map.Entry)(it.next());
110 * // String key = entry.getKey();
111 * // String value = entry.getValue();
112 * //
113 * // track.setProperty(key, value); // YourOwnTrack#setProperty(String, String)
114 * // }
115 *
116 * return track;
117 * }
118 *
119 * public void setProperty(String key, String value) {
120 * properties.put(key, value);
121 * }
122 * }
123 * }
124 * }
125 *
126 * </code>
127 *
128 * See also the usage examles in {@link ToolBoxTrack}.
129 *
130 * @author leo
131 *
132 */
133 public static abstract class TrackFactory {
134 /**
135 * obtain a new factory instance.
136 *
137 * @return new Factory instance.
138 */
139 public abstract Track newInstance();
140
141 /**
142 * set a property.
143 *
144 * @param key
145 * property name to be set.
146 * @param value
147 * property value to be set.
148 */
149 public void setProperty(final String key, final String value) {
150 }
151
152 /**
153 * get a property value.
154 *
155 * @param key
156 * property name you want to know.
157 * @return property value.
158 */
159 public String getProperty(final String key) {
160 return null;
161 }
162
163 public void clear() {
164 }
165 }
166
167 /**
168 * This method is invoked when {@link TrackFrame} and {@link TrackGroup} for this track become ready, that is, the
169 * track is drawable. Override this method to write initialization codes for your tracks.
170 *
171 * @param tracKFrame
172 * the {@link TrackFrame} of this track
173 * @param group
174 * the {@link TrackGroup} of this track
175 */
176 public void setUp(TrackFrame trackFrame, TrackGroup group);
177
178 /**
179 * @return true if {@link #setUp(TrackFrame, TrackGroup)} has already done.
180 */
181 public boolean isInitialized();
182
183 /**
184 * @return the information of the track
185 */
186 public TrackInfo getTrackInfo();
187
188 /**
189 * draw the track widget
190 */
191 public void draw();
192
193 /**
194 * draw and resize the frame
195 */
196 public void refresh();
197
198 /**
199 * @return the track widget
200 */
201 public Widget getWidget();
202
203 /**
204 *
205 * @return default height of the track window
206 */
207 public int getDefaultWindowHeight();
208
209 /**
210 *
211 * @return minimum height of the track window
212 */
213 public int getMinimumWindowHeight();
214
215 /**
216 * An event handler when some cofigurations of the track changes
217 *
218 * @param config
219 */
220 public void onChangeTrackConfig(TrackConfigChange change);
221
222 /**
223 * set a mediator of this track
224 *
225 * @param trackGroup
226 * mediator of this track
227 */
228 public void setTrackGroup(TrackGroup trackGroup);
229
230 /**
231 * @return the mediator of this track
232 */
233 public TrackGroup getTrackGroup();
234
235 public String getTrackGroupProperty(String key, String defaultValue);
236
237 public String getTrackGroupProperty(String key);
238
239 public void setTrackGroupProperty(String key, String value);
240
241 /**
242 * Set the frame that wraps this track
243 *
244 * @param frame
245 * a frame for this track
246 */
247 public void setFrame(TrackFrame frame);
248
249 /**
250 * Get the frame of this track
251 *
252 * @return the frame of this track
253 */
254 public TrackFrame getFrame();
255
256 /**
257 * Get the {@link TrackConfig} panel. Override this method to return your own configuration panel
258 *
259 * @return
260 */
261 public TrackConfig getConfig();
262
263 public void setConfig(TrackConfig config);
264
265 public String toXML();
266
267 public void toXML(XMLWriter xmlWriter);
268
269 /**
270 * load the track parameters from the view definition
271 *
272 * @param view
273 */
274 public void loadView(TrackView.Track view);
275
276 /**
277 * Override this method to save internal state of this track into a {@link Properties} object
278 *
279 * @param xmlWriter
280 */
281 public void saveProperties(CanonicalProperties saveData);
282
283 /**
284 * Override this method to restore internal state of this track
285 *
286 * @param properties
287 */
288 public void restoreProperties(CanonicalProperties properties);
289
290 /**
291 * An event handler when some properties shared within the track group has changed
292 *
293 * @param change
294 */
295 public void onChangeTrackGroupProperty(TrackGroupPropertyChange change);
296
297 public void onChangeTrackHeight(int newHeight);
298
299 /**
300 * An event handler that will be invoked before the track window location change
301 *
302 * @param newWindow
303 */
304 public void beforeChangeTrackWindow(TrackWindow newWindow);
305
306 /**
307 * An event handler when the track window location has changed
308 *
309 * @param newWindow
310 */
311 public void onChangeTrackWindow(TrackWindow newWindow);
312
313 // @see org.utgenome.gwt.utgb.client.track.TrackGroupPropertyChangeListener#onChange(org.utgenome.gwt.utgb.client.track.TrackGroupPropertyChange, org.utgenome.gwt.utgb.client.track.TrackWindow)
314 public void onChange(TrackGroupPropertyChange change, TrackWindow newWindow);
315
316 /**
317 * Report an error
318 *
319 * @param string
320 */
321 public void error(String string);
322
323 }