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