2 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3 * Copyright (C) $$Year-Rel$$ The Jalview Authors
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
10 * of the License, or (at your option) any later version.
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.
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.
21 package jalview.javascript;
23 import jalview.api.AlignFrameI;
26 * The following public methods may be called
27 * externally, eg via javascript in an HTML page.
29 * <br><em>TODO: introduce abstract interface for jalview.appletgui.AlignFrameI</em><br>
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.
40 public interface JalviewLiteJsApi
44 * @return String list of selected sequence IDs, each terminated by the
45 * 'boolean not' character (""+0x00AC) or (¬)
47 public abstract String getSelectedSequences();
51 * separator string or null for default
52 * @return String list of selected sequence IDs, each terminated by given
55 public abstract String getSelectedSequences(String sep);
59 * AlignFrameI containing selection
60 * @return String list of selected sequence IDs, each terminated by current
61 * default separator sequence
64 public abstract String getSelectedSequencesFrom(AlignFrameI alf);
67 * get list of selected sequence IDs separated by given separator
70 * window containing selection
72 * separator string to use - default is 'boolean not'
73 * @return String list of selected sequence IDs, each terminated by the given
76 public abstract String getSelectedSequencesFrom(AlignFrameI alf,
82 * id of sequence to highlight
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
89 public abstract void highlight(String sequenceId, String position,
90 String alignedPosition);
95 * id of sequence to highlight
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
102 public abstract void highlightIn(AlignFrameI alf, String sequenceId,
103 String position, String alignedPosition);
106 * select regions of the currrent alignment frame
109 * String separated list of sequence ids or empty string
111 * String separated list { column range or column, ..} or empty
114 public abstract void select(String sequenceIds, String columns);
117 * select regions of the currrent alignment frame
120 * String separated list { column range, seq1...seqn sequence ids }
122 * separator between toselect fields
124 public abstract void select(String sequenceIds, String columns,
128 * select regions of the given alignment frame
132 * String separated list { column range, seq1...seqn sequence ids }
134 * separator between toselect fields
136 public abstract void selectIn(AlignFrameI alf, String sequenceIds,
140 * select regions of the given alignment frame
144 * String separated list { column range, seq1...seqn sequence ids }
146 * separator between toselect fields
148 public abstract void selectIn(AlignFrameI alf, String sequenceIds,
149 String columns, String sep);
152 * get sequences selected in current AlignFrameI and return their alignment in
153 * format 'format' either with or without suffix
156 * - where selection is
158 * - format of alignment file
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
164 public abstract String getSelectedSequencesAsAlignment(String format,
168 * get sequences selected in alf and return their alignment in format 'format'
169 * either with or without suffix
172 * - where selection is
174 * - format of alignment file
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
180 public abstract String getSelectedSequencesAsAlignmentFrom(
182 String format, String suffix);
185 * get a separator separated list of sequence IDs reflecting the order of the
190 public abstract String getAlignmentOrder();
193 * get a separator separated list of sequence IDs reflecting the order of the
199 public abstract String getAlignmentOrderFrom(AlignFrameI alf);
202 * get a sep separated list of sequence IDs reflecting the order of the
210 public abstract String getAlignmentOrderFrom(AlignFrameI alf, String sep);
213 * re-order the current alignment using the given list of sequence IDs
216 * - sep separated list
218 * - string to use when referring to ordering action in undo buffer
219 * @return 'true' if alignment was actually reordered. empty string if
220 * alignment did not contain sequences.
222 public abstract String orderBy(String order, String undoName);
225 * re-order the current alignment using the given list of sequence IDs
229 * - sep separated list
231 * - string to use when referring to ordering action in undo buffer
233 * @return 'true' if alignment was actually reordered. empty string if
234 * alignment did not contain sequences.
236 public abstract String orderBy(String order, String undoName, String sep);
239 * re-order the given alignment using the given list of sequence IDs separated
244 * - sep separated list
246 * - string to use when referring to ordering action in undo buffer
248 * @return 'true' if alignment was actually reordered. empty string if
249 * alignment did not contain sequences.
251 public abstract String orderAlignmentBy(AlignFrameI alf, String order,
252 String undoName, String sep);
255 * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
256 * PFAM - see jalview.io.AppletFormatAdapter for full list)
261 public abstract String getAlignment(String format);
264 * get alignment displayed in alf as format
270 public abstract String getAlignmentFrom(AlignFrameI alf, String format);
273 * get alignment as format with jalview start-end sequence suffix appended
279 public abstract String getAlignment(String format, String suffix);
282 * get alignment displayed in alf as format with or without the jalview
283 * start-end sequence suffix appended
290 public abstract String getAlignmentFrom(AlignFrameI alf, String format,
294 * add the given features or annotation to the current alignment
298 public abstract void loadAnnotation(String annotation);
301 * add the given features or annotation to the given alignment view
306 public abstract void loadAnnotationFrom(AlignFrameI alf,
310 * parse the given string as a jalview feature or GFF annotation file and
311 * optionally enable feature display on the current AlignFrameI
314 * - gff or features file
315 * @param autoenabledisplay
316 * - when true, feature display will be enabled if any features can
317 * be parsed from the string.
319 public abstract void loadFeatures(String features,
320 boolean autoenabledisplay);
323 * parse the given string as a jalview feature or GFF annotation file and
324 * optionally enable feature display on the given AlignFrameI.
328 * - gff or features file
329 * @param autoenabledisplay
330 * - when true, feature display will be enabled if any features can
331 * be parsed from the string.
332 * @return true if data parsed as features
334 public abstract boolean loadFeaturesFrom(AlignFrameI alf, String features,
335 boolean autoenabledisplay);
338 * get the sequence features in the given format (Jalview or GFF)
343 public abstract String getFeatures(String format);
346 * get the sequence features in alf in the given format (Jalview or GFF)
352 public abstract String getFeaturesFrom(AlignFrameI alf, String format);
355 * get current alignment's annotation as an annotation file
359 public abstract String getAnnotation();
362 * get alignment view alf's annotation as an annotation file
367 public abstract String getAnnotationFrom(AlignFrameI alf);
370 * create a new view and return the AlignFrameI instance
374 public abstract AlignFrameI newView();
377 * create a new view named name and return the AlignFrameI instance
382 public abstract AlignFrameI newView(String name);
385 * create a new view on alf and return the AlignFrameI instance
390 public abstract AlignFrameI newViewFrom(AlignFrameI alf);
393 * create a new view named name on alf
399 public abstract AlignFrameI newViewFrom(AlignFrameI alf, String name);
404 * alignment file as a string
407 * @return null or new alignment frame
409 public abstract AlignFrameI loadAlignment(String text, String title);
412 * register a javascript function to handle any alignment mouseover events
415 * name of javascript function (called with arguments
416 * [jalview.appletgui.AlignFrameI,String(sequence id),String(column
417 * in alignment), String(position in sequence)]
419 public abstract void setMouseoverListener(String listener);
422 * register a javascript function to handle mouseover events
425 * (null or specific AlignFrameI for which events are to be listened
428 * name of javascript function
430 public abstract void setMouseoverListener(AlignFrameI af,
434 * register a javascript function to handle any alignment selection events.
435 * Events are generated when the user completes a selection event, or when the
436 * user deselects all selected regions.
439 * name of javascript function (called with arguments
440 * [jalview.appletgui.AlignFrameI, String(sequence set id),
441 * String(separator separated list of sequences which were selected),
442 * String(separator separated list of column ranges (i.e. single
443 * number or hyphenated range) that were selected)]
445 public abstract void setSelectionListener(String listener);
447 public abstract void setSelectionListener(AlignFrameI af,
451 * register a javascript function to handle events normally routed to a Jmol
455 * - javascript function (arguments are variable, see
456 * jalview.javascript.MouseOverStructureListener for full details)
458 * - separator separated list of PDB file URIs that this viewer is
459 * handling. These files must be in the same order they appear in
460 * Jmol (e.g. first one is frame 1, second is frame 2, etc).
461 * @see jalview.javascript.MouseOverStructureListener
463 public abstract void setStructureListener(String listener,
467 * remove any callback using the given listener function and associated with
468 * the given AlignFrameI (or null for all callbacks)
475 public abstract void removeJavascriptListener(AlignFrameI af,
479 * send a mouseover message to all the alignment windows associated with the
480 * given residue in the pdbfile
486 public abstract void mouseOverStructure(String pdbResNum, String chain,
490 * bind a pdb file to a sequence in the given AlignFrameI.
493 * - null or specific AlignFrameI. This specifies the dataset that
494 * will be searched for a seuqence called sequenceId
496 * - sequenceId within the dataset.
497 * @param pdbEntryString
498 * - the short name for the PDB file
500 * - pdb file - either a URL or a valid PDB file.
501 * @return true if binding was as success TODO: consider making an exception
502 * structure for indicating when PDB parsing or sequenceId location
505 public abstract boolean addPdbFile(AlignFrameI alFrame, String sequenceId,
506 String pdbEntryString, String pdbFile);
509 * adjust horizontal/vertical scroll to make the given location the top left
510 * hand corner for the given view
514 * @param leftHandColumn
516 public abstract void scrollViewToIn(AlignFrameI alf, String topRow,
517 String leftHandColumn);
520 * adjust vertical scroll to make the given row the top one for given view
525 public abstract void scrollViewToRowIn(AlignFrameI alf, String topRow);
528 * adjust horizontal scroll to make the given column the left one in the given
532 * @param leftHandColumn
534 public abstract void scrollViewToColumnIn(AlignFrameI alf,
535 String leftHandColumn);
540 * @see jalview.appletgui.AlignFrameI#getFeatureGroups()
542 public abstract String getFeatureGroups();
546 * AlignFrameI to get feature groups on
548 * @see jalview.appletgui.AlignFrameI#getFeatureGroups()
550 public abstract String getFeatureGroupsOn(AlignFrameI alf);
555 * @see jalview.appletgui.AlignFrameI#getFeatureGroupsOfState(boolean)
557 public abstract String getFeatureGroupsOfState(boolean visible);
561 * align frame to get groups of state visible
564 * @see jalview.appletgui.AlignFrameI#getFeatureGroupsOfState(boolean)
566 public abstract String getFeatureGroupsOfStateOn(AlignFrameI alf,
571 * tab separated list of group names
574 * @see jalview.appletgui.AlignFrameI#setFeatureGroupState(java.lang.String[],
577 public abstract void setFeatureGroupStateOn(AlignFrameI alf,
581 public abstract void setFeatureGroupState(String groups, boolean state);
584 * List separator string
586 * @return the separator
588 public abstract String getSeparator();
591 * List separator string
594 * the separator to set. empty string will reset separator to default
596 public abstract void setSeparator(String separator);
599 * Retrieve fragments of a large packet of data made available by JalviewLite.
601 * @param messageclass
603 * @return next chunk of message
605 public abstract String getJsMessage(String messageclass, String viewId);