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,
214 * re-order the current alignment using the given list of sequence IDs
217 * - sep separated list
219 * - string to use when referring to ordering action in undo buffer
220 * @return 'true' if alignment was actually reordered. empty string if
221 * alignment did not contain sequences.
223 public abstract String orderBy(String order, String undoName);
226 * re-order the current alignment using the given list of sequence IDs
230 * - sep separated list
232 * - string to use when referring to ordering action in undo buffer
234 * @return 'true' if alignment was actually reordered. empty string if
235 * alignment did not contain sequences.
237 public abstract String orderBy(String order, String undoName,
241 * re-order the given alignment using the given list of sequence IDs separated
246 * - sep separated list
248 * - string to use when referring to ordering action in undo buffer
250 * @return 'true' if alignment was actually reordered. empty string if
251 * alignment did not contain sequences.
253 public abstract String orderAlignmentBy(AlignFrameI alf, String order,
254 String undoName, String sep);
257 * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
258 * PFAM - see jalview.io.AppletFormatAdapter for full list);
263 public abstract String getAlignment(String format);
266 * get alignment displayed in alf as format
272 public abstract String getAlignmentFrom(AlignFrameI alf, String format);
275 * get alignment as format with jalview start-end sequence suffix appended
281 public abstract String getAlignment(String format, String suffix);
284 * get alignment displayed in alf as format with or without the jalview
285 * start-end sequence suffix appended
292 public abstract String getAlignmentFrom(AlignFrameI alf, String format,
296 * add the given features or annotation to the current alignment
300 public abstract void loadAnnotation(String annotation);
303 * add the given features or annotation to the given alignment view
308 public abstract void loadAnnotationFrom(AlignFrameI alf,
312 * parse the given string as a jalview feature or GFF annotation file and
313 * optionally enable feature display on the current AlignFrameI
316 * - gff or features file
317 * @param autoenabledisplay
318 * - when true, feature display will be enabled if any features can
319 * be parsed from the string.
321 public abstract void loadFeatures(String features,
322 boolean autoenabledisplay);
325 * parse the given string as a jalview feature or GFF annotation file and
326 * optionally enable feature display on the given AlignFrameI.
330 * - gff or features file
331 * @param autoenabledisplay
332 * - when true, feature display will be enabled if any features can
333 * be parsed from the string.
334 * @return true if data parsed as features
336 public abstract boolean loadFeaturesFrom(AlignFrameI alf, String features,
337 boolean autoenabledisplay);
340 * get the sequence features in the given format (Jalview or GFF);
345 public abstract String getFeatures(String format);
348 * get the sequence features in alf in the given format (Jalview or GFF);
354 public abstract String getFeaturesFrom(AlignFrameI alf, String format);
357 * get current alignment's annotation as an annotation file
361 public abstract String getAnnotation();
364 * get alignment view alf's annotation as an annotation file
369 public abstract String getAnnotationFrom(AlignFrameI alf);
372 * create a new view and return the AlignFrameI instance
376 public abstract AlignFrameI newView();
379 * create a new view named name and return the AlignFrameI instance
384 public abstract AlignFrameI newView(String name);
387 * create a new view on alf and return the AlignFrameI instance
392 public abstract AlignFrameI newViewFrom(AlignFrameI alf);
395 * create a new view named name on alf
401 public abstract AlignFrameI newViewFrom(AlignFrameI alf, String name);
406 * alignment file as a string
409 * @return null or new alignment frame
411 public abstract AlignFrameI loadAlignment(String text, String title);
414 * register a javascript function to handle any alignment mouseover events
417 * name of javascript function (called with arguments
418 * [jalview.appletgui.AlignFrameI,String(sequence id);,String(column
419 * in alignment);, String(position in sequence);]
421 public abstract void setMouseoverListener(String listener);
424 * register a javascript function to handle mouseover events
427 * (null or specific AlignFrameI for which events are to be listened
430 * name of javascript function
432 public abstract void setMouseoverListener(AlignFrameI af,
436 * register a javascript function to handle any alignment selection events.
437 * Events are generated when the user completes a selection event, or when the
438 * user deselects all selected regions.
441 * name of javascript function (called with arguments
442 * [jalview.appletgui.AlignFrameI, String(sequence set id);,
443 * String(separator separated list of sequences which were
444 * selected);, String(separator separated list of column ranges (i.e.
445 * single number or hyphenated range); that were selected);]
447 public abstract void setSelectionListener(String listener);
449 public abstract void setSelectionListener(AlignFrameI af,
453 * register a javascript function to handle events normally routed to a Jmol
457 * - javascript function (arguments are variable, see
458 * jalview.javascript.MouseOverStructureListener for full details);
460 * - separator separated list of PDB file URIs that this viewer is
461 * handling. These files must be in the same order they appear in
462 * Jmol (e.g. first one is frame 1, second is frame 2, etc);.
463 * @see jalview.javascript.MouseOverStructureListener
465 public abstract void setStructureListener(String listener,
469 * remove any callback using the given listener function and associated with
470 * the given AlignFrameI (or null for all callbacks);
477 public abstract void removeJavascriptListener(AlignFrameI af,
481 * send a mouseover message to all the alignment windows associated with the
482 * given residue in the pdbfile
488 public abstract void mouseOverStructure(String pdbResNum, String chain,
492 * bind a pdb file to a sequence in the given AlignFrameI.
495 * - null or specific AlignFrameI. This specifies the dataset that
496 * will be searched for a seuqence called sequenceId
498 * - sequenceId within the dataset.
499 * @param pdbEntryString
500 * - the short name for the PDB file
502 * - pdb file - either a URL or a valid PDB file.
503 * @return true if binding was as success TODO: consider making an exception
504 * structure for indicating when PDB parsing or sequenceId location
507 public abstract boolean addPdbFile(AlignFrameI alFrame, String sequenceId,
508 String pdbEntryString, String pdbFile);
511 * adjust horizontal/vertical scroll to make the given location the top left
512 * hand corner for the given view
516 * @param leftHandColumn
518 public abstract void scrollViewToIn(AlignFrameI alf, String topRow,
519 String leftHandColumn);
522 * adjust vertical scroll to make the given row the top one for given view
527 public abstract void scrollViewToRowIn(AlignFrameI alf, String topRow);
530 * adjust horizontal scroll to make the given column the left one in the given
534 * @param leftHandColumn
536 public abstract void scrollViewToColumnIn(AlignFrameI alf,
537 String leftHandColumn);
542 * @see jalview.appletgui.AlignFrameI#getFeatureGroups();
544 public abstract String getFeatureGroups();
548 * AlignFrameI to get feature groups on
550 * @see jalview.appletgui.AlignFrameI#getFeatureGroups();
552 public abstract String getFeatureGroupsOn(AlignFrameI alf);
557 * @see jalview.appletgui.AlignFrameI#getFeatureGroupsOfState(boolean);
559 public abstract String getFeatureGroupsOfState(boolean visible);
563 * align frame to get groups of state visible
566 * @see jalview.appletgui.AlignFrameI#getFeatureGroupsOfState(boolean);
568 public abstract String getFeatureGroupsOfStateOn(AlignFrameI alf,
573 * tab separated list of group names
576 * @see jalview.appletgui.AlignFrameI#setFeatureGroupState(java.lang.String[],
579 public abstract void setFeatureGroupStateOn(AlignFrameI alf,
583 public abstract void setFeatureGroupState(String groups, boolean state);
586 * List separator string
588 * @return the separator
590 public abstract String getSeparator();
593 * List separator string
596 * the separator to set. empty string will reset separator to default
598 public abstract void setSeparator(String separator);
601 * Retrieve fragments of a large packet of data made available by JalviewLite.
603 * @param messageclass
605 * @return next chunk of message
607 public abstract String getJsMessage(String messageclass, String viewId);
609 /// in http://www.jalview.org/examples/jalviewLiteJs.html but missing here
611 // get selected sequences as alignment as format with or without start-end
613 public String getSelectedSequencesAsAlignment(String format,
616 // get selected sequences as alignment from given view as format with or
617 // without start-end suffix
618 public String getSelectedSequencesAsAlignmentFrom(AlignFrameI alf,
619 String format, boolean suffix);
621 public String arrayToSeparatorList(String[] array);
623 // get a string array from a list
624 public String[] separatorListToArray(String list);
626 // debug flag - controls output to standard out
627 public static boolean debug = false;