formatting
[jalview.git] / src / jalview / javascript / JalviewLiteJsApi.java
1 /*******************************************************************************
2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.7)
3  * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, G Barton, M Clamp, S Searle
4  *
5  * This file is part of Jalview.
6  *
7  * Jalview is free software: you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License 
9  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
10  *
11  * Jalview is distributed in the hope that it will be useful, but 
12  * WITHOUT ANY WARRANTY; without even the implied warranty 
13  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
14  * PURPOSE.  See the GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
17  *******************************************************************************/
18 package jalview.javascript;
19
20 import jalview.appletgui.AlignFrame;
21
22 /**
23  * The following public methods may be called
24  * externally, eg via javascript in an HTML page.
25  * 
26  * <br><em>TODO: introduce abstract interface for jalview.appletgui.AlignFrame</em><br>
27  * 
28  * Most function arguments are strings, which contain serialised versions of lists.
29  * Lists of things are separated by a separator character - either the default or a user supplied one.
30  * Ranges and positions on an alignment or sequence can be specified as a list, where an item containing a single number is a single position, and an item like 1-2 specifies columns 1 and 2 as a range.
31  */
32
33 /**
34  * @author jimp
35  *
36  */
37 public interface JalviewLiteJsApi
38 {
39
40   /**
41    * @return String list of selected sequence IDs, each terminated by the
42    *         'boolean not' character (""+0x00AC) or (&#172;)
43    */
44   public abstract String getSelectedSequences();
45
46   /**
47    * @param sep
48    *          separator string or null for default
49    * @return String list of selected sequence IDs, each terminated by given
50    *         separator string
51    */
52   public abstract String getSelectedSequences(String sep);
53
54   /**
55    * @param alf
56    *          alignframe containing selection
57    * @return String list of selected sequence IDs, each terminated by current
58    *         default separator sequence
59    * 
60    */
61   public abstract String getSelectedSequencesFrom(AlignFrame alf);
62
63   /**
64    * get list of selected sequence IDs separated by given separator
65    * 
66    * @param alf
67    *          window containing selection
68    * @param sep
69    *          separator string to use - default is 'boolean not'
70    * @return String list of selected sequence IDs, each terminated by the given
71    *         separator
72    */
73   public abstract String getSelectedSequencesFrom(AlignFrame alf, String sep);
74
75   /**
76    * 
77    * @param sequenceId
78    *          id of sequence to highlight
79    * @param position
80    *          integer position [ tobe implemented or range ] on sequence
81    * @param alignedPosition
82    *          true/false/empty string - indicate if position is an alignment
83    *          column or unaligned sequence position
84    */
85   public abstract void highlight(String sequenceId, String position,
86           String alignedPosition);
87
88   /**
89    * 
90    * @param sequenceId
91    *          id of sequence to highlight
92    * @param position
93    *          integer position [ tobe implemented or range ] on sequence
94    * @param alignedPosition
95    *          false, blank or something else - indicate if position is an
96    *          alignment column or unaligned sequence position
97    */
98   public abstract void highlightIn(AlignFrame alf, String sequenceId,
99           String position, String alignedPosition);
100
101   /**
102    * select regions of the currrent alignment frame
103    * 
104    * @param sequenceIds
105    *          String separated list of sequence ids or empty string
106    * @param columns
107    *          String separated list { column range or column, ..} or empty
108    *          string
109    */
110   public abstract void select(String sequenceIds, String columns);
111
112   /**
113    * select regions of the currrent alignment frame
114    * 
115    * @param toselect
116    *          String separated list { column range, seq1...seqn sequence ids }
117    * @param sep
118    *          separator between toselect fields
119    */
120   public abstract void select(String sequenceIds, String columns, String sep);
121
122   /**
123    * select regions of the given alignment frame
124    * 
125    * @param alf
126    * @param toselect
127    *          String separated list { column range, seq1...seqn sequence ids }
128    * @param sep
129    *          separator between toselect fields
130    */
131   public abstract void selectIn(AlignFrame alf, String sequenceIds,
132           String columns);
133
134   /**
135    * select regions of the given alignment frame
136    * 
137    * @param alf
138    * @param toselect
139    *          String separated list { column range, seq1...seqn sequence ids }
140    * @param sep
141    *          separator between toselect fields
142    */
143   public abstract void selectIn(AlignFrame alf, String sequenceIds,
144           String columns, String sep);
145
146   /**
147    * get sequences selected in current alignFrame and return their alignment in
148    * format 'format' either with or without suffix
149    * 
150    * @param alf
151    *          - where selection is
152    * @param format
153    *          - format of alignment file
154    * @param suffix
155    *          - "true" to append /start-end string to each sequence ID
156    * @return selected sequences as flat file or empty string if there was no
157    *         current selection
158    */
159   public abstract String getSelectedSequencesAsAlignment(String format,
160           String suffix);
161
162   /**
163    * get sequences selected in alf and return their alignment in format 'format'
164    * either with or without suffix
165    * 
166    * @param alf
167    *          - where selection is
168    * @param format
169    *          - format of alignment file
170    * @param suffix
171    *          - "true" to append /start-end string to each sequence ID
172    * @return selected sequences as flat file or empty string if there was no
173    *         current selection
174    */
175   public abstract String getSelectedSequencesAsAlignmentFrom(
176           AlignFrame alf, String format, String suffix);
177
178   /**
179    * get a separator separated list of sequence IDs reflecting the order of the current alignment 
180    * @return
181    */
182   public abstract String getAlignmentOrder();
183   /**
184    * get a separator separated list of sequence IDs reflecting the order of the alignment in alf 
185    *
186    * @param alf
187    * @return
188    */
189   public abstract String getAlignmentOrderFrom(AlignFrame alf);
190
191   /**
192    * get a sep separated list of sequence IDs reflecting the order of the alignment in alf 
193    * 
194    * @param alf
195    * @param sep - separator to use
196    * @return
197    */
198   public abstract String getAlignmentOrderFrom(AlignFrame alf, String sep);
199   /**
200    * re-order the current alignment using the given list of sequence IDs
201    * @param order - sep separated list
202    * @param undoName - string to use when referring to ordering action in undo buffer
203    * @return 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
204    */
205   public abstract String orderBy(String order, String undoName);
206
207   /**
208    * re-order the current alignment using the given list of sequence IDs
209    * separated by sep
210    * 
211    * @param order
212    *          - sep separated list
213    * @param undoName
214    *          - string to use when referring to ordering action in undo buffer
215    * @param sep
216    * @return 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
217    */
218   public abstract String orderBy(String order, String undoName, String sep);
219
220   /**
221    * re-order the given alignment using the given list of sequence IDs
222    * separated by sep
223    * 
224    * @param alf
225    * @param order
226    *          - sep separated list
227    * @param undoName
228    *          - string to use when referring to ordering action in undo buffer
229    * @param sep
230    * @return 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
231    */
232   public abstract String orderAlignmentBy(AlignFrame alf, String order,
233           String undoName, String sep);
234
235   /**
236    * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP, PFAM - see jalview.io.AppletFormatAdapter for full list)
237    * @param format
238    * @return
239    */
240   public abstract String getAlignment(String format);
241
242   /**
243    * get alignment displayed in alf as format
244    * @param alf
245    * @param format
246    * @return
247    */
248   public abstract String getAlignmentFrom(AlignFrame alf, String format);
249
250   /**
251    * get alignment as format with jalview start-end sequence suffix appended
252    * @param format
253    * @param suffix
254    * @return
255    */
256   public abstract String getAlignment(String format, String suffix);
257
258   /**
259    * get alignment displayed in alf as format 
260    *  with or without the jalview start-end sequence suffix appended
261    * @param alf
262    * @param format
263    * @param suffix
264    * @return
265    */
266   public abstract String getAlignmentFrom(AlignFrame alf, String format,
267           String suffix);
268
269   /**
270    * add the given features or annotation to the current alignment
271    * @param annotation
272    */
273   public abstract void loadAnnotation(String annotation);
274
275   /**
276    * add the given features or annotation to the given alignment view
277    * @param alf
278    * @param annotation
279    */
280   public abstract void loadAnnotationFrom(AlignFrame alf, String annotation);
281
282   /**
283    * parse the given string as a jalview feature or GFF annotation file and optionally enable feature display on the current alignFrame
284    * @param features - gff or features file
285    * @param autoenabledisplay - when true, feature display will be enabled if any features can be parsed from the string.
286    */
287   public abstract void loadFeatures(String features, boolean autoenabledisplay);
288
289   /**
290    * parse the given string as a jalview feature or GFF annotation file and optionally enable feature display on the given alignFrame.
291    * @param alf
292    * @param features - gff or features file
293    * @param autoenabledisplay - when true, feature display will be enabled if any features can be parsed from the string.
294    */
295   public abstract void loadFeaturesFrom(AlignFrame alf, String features, boolean autoenabledisplay);
296
297   /**
298    * get the sequence features in the given format (Jalview or GFF)
299    * @param format
300    * @return
301    */
302   public abstract String getFeatures(String format);
303
304   /**
305    * get the sequence features in alf in the given format (Jalview or GFF)
306    * @param alf
307    * @param format
308    * @return
309    */
310   public abstract String getFeaturesFrom(AlignFrame alf, String format);
311
312   /**
313    * get current alignment's annotation as an annotation file
314    * @return
315    */
316   public abstract String getAnnotation();
317
318   /**
319    * get alignment view alf's annotation as an annotation file
320    * @param alf
321    * @return
322    */
323   public abstract String getAnnotationFrom(AlignFrame alf);
324
325   /**
326    * create a new view and return the alignFrame instance
327    * @return
328    */
329   public abstract AlignFrame newView();
330
331   /**
332    * create a new view named name and return the alignFrame instance
333    * @param name
334    * @return
335    */
336   public abstract AlignFrame newView(String name);
337
338   /**
339    * create a new view on alf and return the alignFrame instance
340    * @param alf
341    * @return
342    */
343   public abstract AlignFrame newViewFrom(AlignFrame alf);
344
345   /**
346    * create a new view named name on alf
347    * @param alf
348    * @param name
349    * @return
350    */
351   public abstract AlignFrame newViewFrom(AlignFrame alf, String name);
352
353   /**
354    * 
355    * @param text
356    *          alignment file as a string
357    * @param title
358    *          window title
359    * @return null or new alignment frame
360    */
361   public abstract AlignFrame loadAlignment(String text, String title);
362
363   /**
364    * register a javascript function to handle any alignment mouseover events
365    * @param listener name of javascript function  (called with arguments [jalview.appletgui.AlignFrame,String(sequence id),String(column in alignment), String(position in sequence)]
366    */
367   public abstract void setMouseoverListener(String listener);
368
369   /**
370    * register a javascript function to handle mouseover events
371    * @param af (null or specific alignframe for which events are to be listened for)
372    * @param listener name of javascript function 
373    */
374   public abstract void setMouseoverListener(AlignFrame af, String listener);
375
376   /**
377    * register a javascript function to handle any alignment selection events. Events are generated when the user completes a selection event, or when the user deselects all selected regions.
378    * @param listener name of javascript function  (called with arguments [jalview.appletgui.AlignFrame, String(sequence set id), String(separator separated list of sequences which were selected), String(separator separated list of column ranges (i.e. single number or hyphenated range) that were selected)]
379    */
380   public abstract void setSelectionListener(String listener);
381
382   public abstract void setSelectionListener(AlignFrame af, String listener);
383
384   /**
385    * register a javascript function to handle events normally routed to a Jmol structure viewer.
386    * @param listener - javascript function (arguments are variable, see jalview.javascript.MouseOverStructureListener for full details)
387    * @param modelSet - separator separated list of PDB file URIs that this viewer is handling. These files must be in the same order they appear in Jmol (e.g. first one is frame 1, second is frame 2, etc). 
388      @see jalview.javascript.MouseOverStructureListener 
389    */
390   public abstract void setStructureListener(String listener, String modelSet);
391
392   /**
393    * remove any callback using the given listener function and associated with
394    * the given alignFrame (or null for all callbacks)
395    * 
396    * @param af
397    *          (may be null)
398    * @param listener
399    *          (may be null)
400    */
401   public abstract void removeJavascriptListener(AlignFrame af,
402           String listener);
403
404   /**
405    * send a mouseover message to all the alignment windows associated with the
406    * given residue in the pdbfile
407    * 
408    * @param pdbResNum
409    * @param chain
410    * @param pdbfile
411    */
412   public abstract void mouseOverStructure(String pdbResNum, String chain,
413           String pdbfile);
414
415   /**
416    * bind a pdb file to a sequence in the given alignFrame.
417    * 
418    * @param alFrame
419    *          - null or specific alignFrame. This specifies the dataset that
420    *          will be searched for a seuqence called sequenceId
421    * @param sequenceId
422    *          - sequenceId within the dataset.
423    * @param pdbEntryString
424    *          - the short name for the PDB file
425    * @param pdbFile
426    *          - pdb file - either a URL or a valid PDB file.
427    * @return true if binding was as success TODO: consider making an exception
428    *         structure for indicating when PDB parsing or sequenceId location
429    *         fails.
430    */
431   public abstract boolean addPdbFile(AlignFrame alFrame, String sequenceId,
432           String pdbEntryString, String pdbFile);
433
434   /**
435    * adjust horizontal/vertical scroll to make the given location the top left hand corner for the given view
436    * 
437    * @param alf
438    * @param topRow
439    * @param leftHandColumn
440    */
441   public abstract void scrollViewToIn(AlignFrame alf, String topRow,
442           String leftHandColumn);
443   /**
444    * adjust vertical scroll to make the given row the top one for given view
445    * 
446    * @param alf
447    * @param topRow
448    */
449   public abstract void scrollViewToRowIn(AlignFrame alf, String topRow);
450   /**
451    * adjust horizontal scroll to make the given column the left one in the given view
452    * 
453    * @param alf
454    * @param leftHandColumn
455    */
456   public abstract void scrollViewToColumnIn(AlignFrame alf, String leftHandColumn);
457
458   /**
459    * 
460    * @return
461    * @see jalview.appletgui.AlignFrame#getFeatureGroups()
462    */
463   public abstract String getFeatureGroups();
464
465   /**
466    * @param alf
467    *          alignframe to get feature groups on
468    * @return
469    * @see jalview.appletgui.AlignFrame#getFeatureGroups()
470    */
471   public abstract String getFeatureGroupsOn(AlignFrame alf);
472
473   /**
474    * @param visible
475    * @return
476    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
477    */
478   public abstract String getFeatureGroupsOfState(boolean visible);
479
480   /**
481    * @param alf
482    *          align frame to get groups of state visible
483    * @param visible
484    * @return
485    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
486    */
487   public abstract String getFeatureGroupsOfStateOn(AlignFrame alf,
488           boolean visible);
489
490   /**
491    * @param groups
492    *          tab separated list of group names
493    * @param state
494    *          true or false
495    * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
496    *      boolean)
497    */
498   public abstract void setFeatureGroupStateOn(AlignFrame alf,
499           String groups, boolean state);
500
501   public abstract void setFeatureGroupState(String groups, boolean state);
502
503   /**
504    * List separator string
505    * 
506    * @return the separator
507    */
508   public abstract String getSeparator();
509
510   /**
511    * List separator string
512    * 
513    * @param separator
514    *          the separator to set. empty string will reset separator to default
515    */
516   public abstract void setSeparator(String separator);
517
518   /**
519    * Retrieve fragments of a large packet of data made available by JalviewLite.
520    * @param messageclass
521    * @param viewId
522    * @return next chunk of message
523    */
524   public abstract String getJsMessage(String messageclass, String viewId);
525
526 }