2 * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8.0b1)
3 * Copyright (C) 2014 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 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/>.
17 * The Jalview Authors are detailed in the 'AUTHORS' file.
19 package jalview.javascript;
21 import jalview.appletgui.AlignFrame;
24 * The following public methods may be called
25 * externally, eg via javascript in an HTML page.
27 * <br><em>TODO: introduce abstract interface for jalview.appletgui.AlignFrame</em><br>
29 * Most function arguments are strings, which contain serialised versions of lists.
30 * Lists of things are separated by a separator character - either the default or a user supplied one.
31 * 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.
38 public interface JalviewLiteJsApi
42 * @return String list of selected sequence IDs, each terminated by the
43 * 'boolean not' character (""+0x00AC) or (¬)
45 public abstract String getSelectedSequences();
49 * separator string or null for default
50 * @return String list of selected sequence IDs, each terminated by given
53 public abstract String getSelectedSequences(String sep);
57 * alignframe containing selection
58 * @return String list of selected sequence IDs, each terminated by current
59 * default separator sequence
62 public abstract String getSelectedSequencesFrom(AlignFrame alf);
65 * get list of selected sequence IDs separated by given separator
68 * window containing selection
70 * separator string to use - default is 'boolean not'
71 * @return String list of selected sequence IDs, each terminated by the given
74 public abstract String getSelectedSequencesFrom(AlignFrame alf, String sep);
79 * id of sequence to highlight
81 * integer position [ tobe implemented or range ] on sequence
82 * @param alignedPosition
83 * true/false/empty string - indicate if position is an alignment
84 * column or unaligned sequence position
86 public abstract void highlight(String sequenceId, String position,
87 String alignedPosition);
92 * id of sequence to highlight
94 * integer position [ tobe implemented or range ] on sequence
95 * @param alignedPosition
96 * false, blank or something else - indicate if position is an
97 * alignment column or unaligned sequence position
99 public abstract void highlightIn(AlignFrame alf, String sequenceId,
100 String position, String alignedPosition);
103 * select regions of the currrent alignment frame
106 * String separated list of sequence ids or empty string
108 * String separated list { column range or column, ..} or empty
111 public abstract void select(String sequenceIds, String columns);
114 * select regions of the currrent alignment frame
117 * String separated list { column range, seq1...seqn sequence ids }
119 * separator between toselect fields
121 public abstract void select(String sequenceIds, String columns, String sep);
124 * select regions of the given alignment frame
128 * String separated list { column range, seq1...seqn sequence ids }
130 * separator between toselect fields
132 public abstract void selectIn(AlignFrame alf, String sequenceIds,
136 * select regions of the given alignment frame
140 * String separated list { column range, seq1...seqn sequence ids }
142 * separator between toselect fields
144 public abstract void selectIn(AlignFrame alf, String sequenceIds,
145 String columns, String sep);
148 * get sequences selected in current alignFrame and return their alignment in
149 * format 'format' either with or without suffix
152 * - where selection is
154 * - format of alignment file
156 * - "true" to append /start-end string to each sequence ID
157 * @return selected sequences as flat file or empty string if there was no
160 public abstract String getSelectedSequencesAsAlignment(String format,
164 * get sequences selected in alf and return their alignment in format 'format'
165 * either with or without suffix
168 * - where selection is
170 * - format of alignment file
172 * - "true" to append /start-end string to each sequence ID
173 * @return selected sequences as flat file or empty string if there was no
176 public abstract String getSelectedSequencesAsAlignmentFrom(
177 AlignFrame alf, String format, String suffix);
180 * get a separator separated list of sequence IDs reflecting the order of the
185 public abstract String getAlignmentOrder();
188 * get a separator separated list of sequence IDs reflecting the order of the
194 public abstract String getAlignmentOrderFrom(AlignFrame alf);
197 * get a sep separated list of sequence IDs reflecting the order of the
205 public abstract String getAlignmentOrderFrom(AlignFrame alf, String sep);
208 * re-order the current alignment using the given list of sequence IDs
211 * - sep separated list
213 * - string to use when referring to ordering action in undo buffer
214 * @return 'true' if alignment was actually reordered. empty string if
215 * alignment did not contain sequences.
217 public abstract String orderBy(String order, String undoName);
220 * re-order the current alignment using the given list of sequence IDs
224 * - sep separated list
226 * - string to use when referring to ordering action in undo buffer
228 * @return 'true' if alignment was actually reordered. empty string if
229 * alignment did not contain sequences.
231 public abstract String orderBy(String order, String undoName, String sep);
234 * re-order the given alignment using the given list of sequence IDs separated
239 * - sep separated list
241 * - string to use when referring to ordering action in undo buffer
243 * @return 'true' if alignment was actually reordered. empty string if
244 * alignment did not contain sequences.
246 public abstract String orderAlignmentBy(AlignFrame alf, String order,
247 String undoName, String sep);
250 * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
251 * PFAM - see jalview.io.AppletFormatAdapter for full list)
256 public abstract String getAlignment(String format);
259 * get alignment displayed in alf as format
265 public abstract String getAlignmentFrom(AlignFrame alf, String format);
268 * get alignment as format with jalview start-end sequence suffix appended
274 public abstract String getAlignment(String format, String suffix);
277 * get alignment displayed in alf as format with or without the jalview
278 * start-end sequence suffix appended
285 public abstract String getAlignmentFrom(AlignFrame alf, String format,
289 * add the given features or annotation to the current alignment
293 public abstract void loadAnnotation(String annotation);
296 * add the given features or annotation to the given alignment view
301 public abstract void loadAnnotationFrom(AlignFrame alf, String annotation);
304 * parse the given string as a jalview feature or GFF annotation file and
305 * optionally enable feature display on the current alignFrame
308 * - gff or features file
309 * @param autoenabledisplay
310 * - when true, feature display will be enabled if any features can
311 * be parsed from the string.
313 public abstract void loadFeatures(String features,
314 boolean autoenabledisplay);
317 * parse the given string as a jalview feature or GFF annotation file and
318 * optionally enable feature display on the given alignFrame.
322 * - gff or features file
323 * @param autoenabledisplay
324 * - when true, feature display will be enabled if any features can
325 * be parsed from the string.
326 * @return true if data parsed as features
328 public abstract boolean loadFeaturesFrom(AlignFrame alf, String features,
329 boolean autoenabledisplay);
332 * get the sequence features in the given format (Jalview or GFF)
337 public abstract String getFeatures(String format);
340 * get the sequence features in alf in the given format (Jalview or GFF)
346 public abstract String getFeaturesFrom(AlignFrame alf, String format);
349 * get current alignment's annotation as an annotation file
353 public abstract String getAnnotation();
356 * get alignment view alf's annotation as an annotation file
361 public abstract String getAnnotationFrom(AlignFrame alf);
364 * create a new view and return the alignFrame instance
368 public abstract AlignFrame newView();
371 * create a new view named name and return the alignFrame instance
376 public abstract AlignFrame newView(String name);
379 * create a new view on alf and return the alignFrame instance
384 public abstract AlignFrame newViewFrom(AlignFrame alf);
387 * create a new view named name on alf
393 public abstract AlignFrame newViewFrom(AlignFrame alf, String name);
398 * alignment file as a string
401 * @return null or new alignment frame
403 public abstract AlignFrame loadAlignment(String text, String title);
406 * register a javascript function to handle any alignment mouseover events
409 * name of javascript function (called with arguments
410 * [jalview.appletgui.AlignFrame,String(sequence id),String(column in
411 * alignment), String(position in sequence)]
413 public abstract void setMouseoverListener(String listener);
416 * register a javascript function to handle mouseover events
419 * (null or specific alignframe for which events are to be listened
422 * name of javascript function
424 public abstract void setMouseoverListener(AlignFrame af, String listener);
427 * register a javascript function to handle any alignment selection events.
428 * Events are generated when the user completes a selection event, or when the
429 * user deselects all selected regions.
432 * name of javascript function (called with arguments
433 * [jalview.appletgui.AlignFrame, String(sequence set id),
434 * String(separator separated list of sequences which were selected),
435 * String(separator separated list of column ranges (i.e. single
436 * number or hyphenated range) that were selected)]
438 public abstract void setSelectionListener(String listener);
440 public abstract void setSelectionListener(AlignFrame af, String listener);
443 * register a javascript function to handle events normally routed to a Jmol
447 * - javascript function (arguments are variable, see
448 * jalview.javascript.MouseOverStructureListener for full details)
450 * - separator separated list of PDB file URIs that this viewer is
451 * handling. These files must be in the same order they appear in
452 * Jmol (e.g. first one is frame 1, second is frame 2, etc).
453 * @see jalview.javascript.MouseOverStructureListener
455 public abstract void setStructureListener(String listener, String modelSet);
458 * remove any callback using the given listener function and associated with
459 * the given alignFrame (or null for all callbacks)
466 public abstract void removeJavascriptListener(AlignFrame af,
470 * send a mouseover message to all the alignment windows associated with the
471 * given residue in the pdbfile
477 public abstract void mouseOverStructure(String pdbResNum, String chain,
481 * bind a pdb file to a sequence in the given alignFrame.
484 * - null or specific alignFrame. This specifies the dataset that
485 * will be searched for a seuqence called sequenceId
487 * - sequenceId within the dataset.
488 * @param pdbEntryString
489 * - the short name for the PDB file
491 * - pdb file - either a URL or a valid PDB file.
492 * @return true if binding was as success TODO: consider making an exception
493 * structure for indicating when PDB parsing or sequenceId location
496 public abstract boolean addPdbFile(AlignFrame alFrame, String sequenceId,
497 String pdbEntryString, String pdbFile);
500 * adjust horizontal/vertical scroll to make the given location the top left
501 * hand corner for the given view
505 * @param leftHandColumn
507 public abstract void scrollViewToIn(AlignFrame alf, String topRow,
508 String leftHandColumn);
511 * adjust vertical scroll to make the given row the top one for given view
516 public abstract void scrollViewToRowIn(AlignFrame alf, String topRow);
519 * adjust horizontal scroll to make the given column the left one in the given
523 * @param leftHandColumn
525 public abstract void scrollViewToColumnIn(AlignFrame alf,
526 String leftHandColumn);
531 * @see jalview.appletgui.AlignFrame#getFeatureGroups()
533 public abstract String getFeatureGroups();
537 * alignframe to get feature groups on
539 * @see jalview.appletgui.AlignFrame#getFeatureGroups()
541 public abstract String getFeatureGroupsOn(AlignFrame alf);
546 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
548 public abstract String getFeatureGroupsOfState(boolean visible);
552 * align frame to get groups of state visible
555 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
557 public abstract String getFeatureGroupsOfStateOn(AlignFrame alf,
562 * tab separated list of group names
565 * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
568 public abstract void setFeatureGroupStateOn(AlignFrame alf,
569 String groups, boolean state);
571 public abstract void setFeatureGroupState(String groups, boolean state);
574 * List separator string
576 * @return the separator
578 public abstract String getSeparator();
581 * List separator string
584 * the separator to set. empty string will reset separator to default
586 public abstract void setSeparator(String separator);
589 * Retrieve fragments of a large packet of data made available by JalviewLite.
591 * @param messageclass
593 * @return next chunk of message
595 public abstract String getJsMessage(String messageclass, String viewId);