2 * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8)
3 * Copyright (C) 2012 J Procter, AM Waterhouse, LM Lui, J Engelhardt, G Barton, M Clamp, S Searle
5 * This file is part of Jalview.
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.
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.
16 * You should have received a copy of the GNU General Public License along with Jalview. If not, see <http://www.gnu.org/licenses/>.
18 package jalview.javascript;
20 import jalview.appletgui.AlignFrame;
23 * The following public methods may be called
24 * externally, eg via javascript in an HTML page.
26 * <br><em>TODO: introduce abstract interface for jalview.appletgui.AlignFrame</em><br>
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.
37 public interface JalviewLiteJsApi
41 * @return String list of selected sequence IDs, each terminated by the
42 * 'boolean not' character (""+0x00AC) or (¬)
44 public abstract String getSelectedSequences();
48 * separator string or null for default
49 * @return String list of selected sequence IDs, each terminated by given
52 public abstract String getSelectedSequences(String sep);
56 * alignframe containing selection
57 * @return String list of selected sequence IDs, each terminated by current
58 * default separator sequence
61 public abstract String getSelectedSequencesFrom(AlignFrame alf);
64 * get list of selected sequence IDs separated by given separator
67 * window containing selection
69 * separator string to use - default is 'boolean not'
70 * @return String list of selected sequence IDs, each terminated by the given
73 public abstract String getSelectedSequencesFrom(AlignFrame alf, String sep);
78 * id of sequence to highlight
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
85 public abstract void highlight(String sequenceId, String position,
86 String alignedPosition);
91 * id of sequence to highlight
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
98 public abstract void highlightIn(AlignFrame alf, String sequenceId,
99 String position, String alignedPosition);
102 * select regions of the currrent alignment frame
105 * String separated list of sequence ids or empty string
107 * String separated list { column range or column, ..} or empty
110 public abstract void select(String sequenceIds, String columns);
113 * select regions of the currrent alignment frame
116 * String separated list { column range, seq1...seqn sequence ids }
118 * separator between toselect fields
120 public abstract void select(String sequenceIds, String columns, String sep);
123 * select regions of the given alignment frame
127 * String separated list { column range, seq1...seqn sequence ids }
129 * separator between toselect fields
131 public abstract void selectIn(AlignFrame alf, String sequenceIds,
135 * select regions of the given alignment frame
139 * String separated list { column range, seq1...seqn sequence ids }
141 * separator between toselect fields
143 public abstract void selectIn(AlignFrame alf, String sequenceIds,
144 String columns, String sep);
147 * get sequences selected in current alignFrame and return their alignment in
148 * format 'format' either with or without suffix
151 * - where selection is
153 * - format of alignment file
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
159 public abstract String getSelectedSequencesAsAlignment(String format,
163 * get sequences selected in alf and return their alignment in format 'format'
164 * either with or without suffix
167 * - where selection is
169 * - format of alignment file
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
175 public abstract String getSelectedSequencesAsAlignmentFrom(
176 AlignFrame alf, String format, String suffix);
179 * get a separator separated list of sequence IDs reflecting the order of the
184 public abstract String getAlignmentOrder();
187 * get a separator separated list of sequence IDs reflecting the order of the
193 public abstract String getAlignmentOrderFrom(AlignFrame alf);
196 * get a sep separated list of sequence IDs reflecting the order of the
204 public abstract String getAlignmentOrderFrom(AlignFrame alf, String sep);
207 * re-order the current alignment using the given list of sequence IDs
210 * - sep separated list
212 * - string to use when referring to ordering action in undo buffer
213 * @return 'true' if alignment was actually reordered. empty string if
214 * alignment did not contain sequences.
216 public abstract String orderBy(String order, String undoName);
219 * re-order the current alignment using the given list of sequence IDs
223 * - sep separated list
225 * - string to use when referring to ordering action in undo buffer
227 * @return 'true' if alignment was actually reordered. empty string if
228 * alignment did not contain sequences.
230 public abstract String orderBy(String order, String undoName, String sep);
233 * re-order the given alignment using the given list of sequence IDs separated
238 * - sep separated list
240 * - string to use when referring to ordering action in undo buffer
242 * @return 'true' if alignment was actually reordered. empty string if
243 * alignment did not contain sequences.
245 public abstract String orderAlignmentBy(AlignFrame alf, String order,
246 String undoName, String sep);
249 * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
250 * PFAM - see jalview.io.AppletFormatAdapter for full list)
255 public abstract String getAlignment(String format);
258 * get alignment displayed in alf as format
264 public abstract String getAlignmentFrom(AlignFrame alf, String format);
267 * get alignment as format with jalview start-end sequence suffix appended
273 public abstract String getAlignment(String format, String suffix);
276 * get alignment displayed in alf as format with or without the jalview
277 * start-end sequence suffix appended
284 public abstract String getAlignmentFrom(AlignFrame alf, String format,
288 * add the given features or annotation to the current alignment
292 public abstract void loadAnnotation(String annotation);
295 * add the given features or annotation to the given alignment view
300 public abstract void loadAnnotationFrom(AlignFrame alf, String annotation);
303 * parse the given string as a jalview feature or GFF annotation file and
304 * optionally enable feature display on the current alignFrame
307 * - gff or features file
308 * @param autoenabledisplay
309 * - when true, feature display will be enabled if any features can
310 * be parsed from the string.
312 public abstract void loadFeatures(String features,
313 boolean autoenabledisplay);
316 * parse the given string as a jalview feature or GFF annotation file and
317 * optionally enable feature display on the given alignFrame.
321 * - gff or features file
322 * @param autoenabledisplay
323 * - when true, feature display will be enabled if any features can
324 * be parsed from the string.
325 * @return true if data parsed as features
327 public abstract boolean loadFeaturesFrom(AlignFrame alf, String features,
328 boolean autoenabledisplay);
331 * get the sequence features in the given format (Jalview or GFF)
336 public abstract String getFeatures(String format);
339 * get the sequence features in alf in the given format (Jalview or GFF)
345 public abstract String getFeaturesFrom(AlignFrame alf, String format);
348 * get current alignment's annotation as an annotation file
352 public abstract String getAnnotation();
355 * get alignment view alf's annotation as an annotation file
360 public abstract String getAnnotationFrom(AlignFrame alf);
363 * create a new view and return the alignFrame instance
367 public abstract AlignFrame newView();
370 * create a new view named name and return the alignFrame instance
375 public abstract AlignFrame newView(String name);
378 * create a new view on alf and return the alignFrame instance
383 public abstract AlignFrame newViewFrom(AlignFrame alf);
386 * create a new view named name on alf
392 public abstract AlignFrame newViewFrom(AlignFrame alf, String name);
397 * alignment file as a string
400 * @return null or new alignment frame
402 public abstract AlignFrame loadAlignment(String text, String title);
405 * register a javascript function to handle any alignment mouseover events
408 * name of javascript function (called with arguments
409 * [jalview.appletgui.AlignFrame,String(sequence id),String(column in
410 * alignment), String(position in sequence)]
412 public abstract void setMouseoverListener(String listener);
415 * register a javascript function to handle mouseover events
418 * (null or specific alignframe for which events are to be listened
421 * name of javascript function
423 public abstract void setMouseoverListener(AlignFrame af, String listener);
426 * register a javascript function to handle any alignment selection events.
427 * Events are generated when the user completes a selection event, or when the
428 * user deselects all selected regions.
431 * name of javascript function (called with arguments
432 * [jalview.appletgui.AlignFrame, String(sequence set id),
433 * String(separator separated list of sequences which were selected),
434 * String(separator separated list of column ranges (i.e. single
435 * number or hyphenated range) that were selected)]
437 public abstract void setSelectionListener(String listener);
439 public abstract void setSelectionListener(AlignFrame af, String listener);
442 * register a javascript function to handle events normally routed to a Jmol
446 * - javascript function (arguments are variable, see
447 * jalview.javascript.MouseOverStructureListener for full details)
449 * - separator separated list of PDB file URIs that this viewer is
450 * handling. These files must be in the same order they appear in
451 * Jmol (e.g. first one is frame 1, second is frame 2, etc).
452 * @see jalview.javascript.MouseOverStructureListener
454 public abstract void setStructureListener(String listener, String modelSet);
457 * remove any callback using the given listener function and associated with
458 * the given alignFrame (or null for all callbacks)
465 public abstract void removeJavascriptListener(AlignFrame af,
469 * send a mouseover message to all the alignment windows associated with the
470 * given residue in the pdbfile
476 public abstract void mouseOverStructure(String pdbResNum, String chain,
480 * bind a pdb file to a sequence in the given alignFrame.
483 * - null or specific alignFrame. This specifies the dataset that
484 * will be searched for a seuqence called sequenceId
486 * - sequenceId within the dataset.
487 * @param pdbEntryString
488 * - the short name for the PDB file
490 * - pdb file - either a URL or a valid PDB file.
491 * @return true if binding was as success TODO: consider making an exception
492 * structure for indicating when PDB parsing or sequenceId location
495 public abstract boolean addPdbFile(AlignFrame alFrame, String sequenceId,
496 String pdbEntryString, String pdbFile);
499 * adjust horizontal/vertical scroll to make the given location the top left
500 * hand corner for the given view
504 * @param leftHandColumn
506 public abstract void scrollViewToIn(AlignFrame alf, String topRow,
507 String leftHandColumn);
510 * adjust vertical scroll to make the given row the top one for given view
515 public abstract void scrollViewToRowIn(AlignFrame alf, String topRow);
518 * adjust horizontal scroll to make the given column the left one in the given
522 * @param leftHandColumn
524 public abstract void scrollViewToColumnIn(AlignFrame alf,
525 String leftHandColumn);
530 * @see jalview.appletgui.AlignFrame#getFeatureGroups()
532 public abstract String getFeatureGroups();
536 * alignframe to get feature groups on
538 * @see jalview.appletgui.AlignFrame#getFeatureGroups()
540 public abstract String getFeatureGroupsOn(AlignFrame alf);
545 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
547 public abstract String getFeatureGroupsOfState(boolean visible);
551 * align frame to get groups of state visible
554 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
556 public abstract String getFeatureGroupsOfStateOn(AlignFrame alf,
561 * tab separated list of group names
564 * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
567 public abstract void setFeatureGroupStateOn(AlignFrame alf,
568 String groups, boolean state);
570 public abstract void setFeatureGroupState(String groups, boolean state);
573 * List separator string
575 * @return the separator
577 public abstract String getSeparator();
580 * List separator string
583 * the separator to set. empty string will reset separator to default
585 public abstract void setSeparator(String separator);
588 * Retrieve fragments of a large packet of data made available by JalviewLite.
590 * @param messageclass
592 * @return next chunk of message
594 public abstract String getJsMessage(String messageclass, String viewId);