3 import jalview.gui.AlignFrame;
6 * JAL-3369 JalviewJS API BH 2019.07.17
11 public interface JalviewJSApi
17 * process commandline arguments after the JavaScript application has started
22 Object parseArguments(String[] args);
26 * Open a new Tree panel on the desktop statically. Params are standard (not
27 * set by Groovy). No dialog is opened.
33 * @return null, or the string "label.you_need_at_least_n_sequences" if number
34 * of sequences selected is inappropriate
36 public Object openTreePanel(AlignFrame af, String treeType,
40 * public static method for JalviewJS API to open a PCAPanel without
41 * necessarily using a dialog.
46 * @return the PCAPanel, or the string "label.you_need_at_least_n_sequences"
47 * if number of sequences selected is inappropriate
49 public Object openPcaPanel(AlignFrame af, String modelName);
52 * The following public methods may be called externally, eg via javascript in
56 * <em>TODO: introduce abstract interface for
57 * jalview.appletgui.AlignFrame</em><br>
59 * Most function arguments are strings, which contain serialised versions of
60 * lists. Lists of things are separated by a separator character - either the
61 * default or a user supplied one. Ranges and positions on an alignment or
62 * sequence can be specified as a list, where an item containing a single
63 * number is a single position, and an item like 1-2 specifies columns 1 and 2
71 // public interface JalviewLiteJsApi
75 * @return String list of selected sequence IDs, each terminated by the
76 * 'boolean not' character (""+0x00AC); or (¬);
79 public abstract String getSelectedSequences();
83 * separator string or null for default
84 * @return String list of selected sequence IDs, each terminated by given
88 public abstract String getSelectedSequences(String sep);
92 * AlignFrame containing selection
93 * @return String list of selected sequence IDs, each terminated by current
94 * default separator sequence
97 public abstract String getSelectedSequencesFrom(AlignFrame alf);
100 * get list of selected sequence IDs separated by given separator
103 * window containing selection
105 * separator string to use - default is 'boolean not'
106 * @return String list of selected sequence IDs, each terminated by the given
109 public abstract String getSelectedSequencesFrom(AlignFrame alf,
115 * id of sequence to highlight
117 * integer position [ tobe implemented or range ] on sequence
118 * @param alignedPosition
119 * true/false/empty string - indicate if position is an alignment
120 * column or unaligned sequence position
123 public abstract void highlight(String sequenceId, String position,
124 String alignedPosition);
129 * id of sequence to highlight
131 * integer position [ tobe implemented or range ] on sequence
132 * @param alignedPosition
133 * false, blank or something else - indicate if position is an
134 * alignment column or unaligned sequence position
136 public abstract void highlightIn(AlignFrame alf, String sequenceId,
137 String position, String alignedPosition);
140 * select regions of the currrent alignment frame
143 * String separated list of sequence ids or empty string
145 * String separated list { column range or column, ..} or empty
149 public abstract void select(String sequenceIds, String columns);
152 * select regions of the currrent alignment frame
155 * String separated list { column range, seq1...seqn sequence ids }
157 * separator between toselect fields
160 public abstract void select(String sequenceIds, String columns,
164 * select regions of the given alignment frame
168 * String separated list { column range, seq1...seqn sequence ids }
170 * separator between toselect fields
172 public abstract void selectIn(AlignFrame alf, String sequenceIds,
176 * select regions of the given alignment frame
180 * String separated list { column range, seq1...seqn sequence ids }
182 * separator between toselect fields
184 public abstract void selectIn(AlignFrame alf, String sequenceIds,
185 String columns, String sep);
188 * get sequences selected in current AlignFrame and return their alignment in
189 * format 'format' either with or without suffix
192 * - where selection is
194 * - format of alignment file
196 * - "true" to append /start-end string to each sequence ID
197 * @return selected sequences as flat file or empty string if there was no
201 public abstract String getSelectedSequencesAsAlignment(String format,
205 * get sequences selected in alf and return their alignment in format 'format'
206 * either with or without suffix
209 * - where selection is
211 * - format of alignment file
213 * - "true" to append /start-end string to each sequence ID
214 * @return selected sequences as flat file or empty string if there was no
217 public abstract String getSelectedSequencesAsAlignmentFrom(
219 String format, String suffix);
222 * get a separator separated list of sequence IDs reflecting the order of the
228 public abstract String getAlignmentOrder();
231 * get a separator separated list of sequence IDs reflecting the order of the
237 public abstract String getAlignmentOrderFrom(AlignFrame alf);
240 * get a sep separated list of sequence IDs reflecting the order of the
248 public abstract String getAlignmentOrderFrom(AlignFrame alf,
252 * re-order the current alignment using the given list of sequence IDs
255 * - sep separated list
257 * - string to use when referring to ordering action in undo buffer
258 * @return 'true' if alignment was actually reordered. empty string if
259 * alignment did not contain sequences.
262 public abstract String orderBy(String order, String undoName);
265 * re-order the current alignment using the given list of sequence IDs
269 * - sep separated list
271 * - string to use when referring to ordering action in undo buffer
273 * @return 'true' if alignment was actually reordered. empty string if
274 * alignment did not contain sequences.
277 public abstract String orderBy(String order, String undoName,
281 * re-order the given alignment using the given list of sequence IDs separated
286 * - sep separated list
288 * - string to use when referring to ordering action in undo buffer
290 * @return 'true' if alignment was actually reordered. empty string if
291 * alignment did not contain sequences.
293 public abstract String orderAlignmentBy(AlignFrame alf, String order,
294 String undoName, String sep);
297 * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
298 * PFAM - see jalview.io.AppletFormatAdapter for full list);
304 public abstract String getAlignment(String format);
307 * get alignment displayed in alf as format
313 public abstract String getAlignmentFrom(AlignFrame alf, String format);
316 * get alignment as format with jalview start-end sequence suffix appended
323 public abstract String getAlignment(String format, String suffix);
326 * get alignment displayed in alf as format with or without the jalview
327 * start-end sequence suffix appended
334 public abstract String getAlignmentFrom(AlignFrame alf, String format,
338 * add the given features or annotation to the current alignment
343 public abstract void loadAnnotation(String annotation);
346 * add the given features or annotation to the given alignment view
351 public abstract void loadAnnotationFrom(AlignFrame alf,
355 * parse the given string as a jalview feature or GFF annotation file and
356 * optionally enable feature display on the current AlignFrame
359 * - gff or features file
360 * @param autoenabledisplay
361 * - when true, feature display will be enabled if any features can
362 * be parsed from the string.
365 public abstract void loadFeatures(String features,
366 boolean autoenabledisplay);
369 * parse the given string as a jalview feature or GFF annotation file and
370 * optionally enable feature display on the given AlignFrame.
374 * - gff or features file
375 * @param autoenabledisplay
376 * - when true, feature display will be enabled if any features can
377 * be parsed from the string.
378 * @return true if data parsed as features
380 public abstract boolean loadFeaturesFrom(AlignFrame alf, String features,
381 boolean autoenabledisplay);
384 * get the sequence features in the given format (Jalview or GFF);
390 public abstract String getFeatures(String format);
393 * get the sequence features in alf in the given format (Jalview or GFF);
399 public abstract String getFeaturesFrom(AlignFrame alf, String format);
402 * get current alignment's annotation as an annotation file
407 public abstract String getAnnotation();
410 * get alignment view alf's annotation as an annotation file
415 public abstract String getAnnotationFrom(AlignFrame alf);
417 // BH incompatibility here -- JalviewLite created an AlignFrame; Jalview
418 // creates an AlignmentPanel
420 // * create a new view and return the AlignFrame instance
425 // public abstract AlignFrame newView();
428 // * create a new view named name and return the AlignFrame instance
434 // public abstract AlignFrame newView(String name);
437 // * create a new view on alf and return the AlignFrame instance
442 // public abstract AlignFrame newViewFrom(AlignFrame alf);
445 // * create a new view named name on alf
451 // public abstract AlignFrame newViewFrom(AlignFrame alf, String name);
456 * alignment file as a string
459 * @return null or new alignment frame
462 public abstract AlignFrame loadAlignment(String text, String title);
465 * register a javascript function to handle any alignment mouseover events
468 * name of javascript function (called with arguments
469 * [jalview.appletgui.AlignFrame,String(sequence id);,String(column
470 * in alignment);, String(position in sequence);]
473 public abstract void setMouseoverListener(String listener);
476 * register a javascript function to handle mouseover events
479 * (null or specific AlignFrame for which events are to be listened
482 * name of javascript function
484 public abstract void setMouseoverListener(AlignFrame af,
488 * register a javascript function to handle any alignment selection events.
489 * Events are generated when the user completes a selection event, or when the
490 * user deselects all selected regions.
493 * name of javascript function (called with arguments
494 * [jalview.appletgui.AlignFrame, String(sequence set id);,
495 * String(separator separated list of sequences which were
496 * selected);, String(separator separated list of column ranges (i.e.
497 * single number or hyphenated range); that were selected);]
500 public abstract void setSelectionListener(String listener);
502 public abstract void setSelectionListener(AlignFrame af,
506 * register a javascript function to handle events normally routed to a Jmol
510 * - javascript function (arguments are variable, see
511 * jalview.javascript.MouseOverStructureListener for full details);
513 * - separator separated list of PDB file URIs that this viewer is
514 * handling. These files must be in the same order they appear in
515 * Jmol (e.g. first one is frame 1, second is frame 2, etc);.
516 * @see jalview.javascript.MouseOverStructureListener
519 public abstract void setStructureListener(String listener,
523 * remove any callback using the given listener function and associated with
524 * the given AlignFrame (or null for all callbacks);
531 public abstract void removeJavascriptListener(AlignFrame af,
535 * send a mouseover message to all the alignment windows associated with the
536 * given residue in the pdbfile
543 public abstract void mouseOverStructure(String pdbResNum, String chain,
547 * bind a pdb file to a sequence in the given AlignFrame.
550 * - null or specific AlignFrame. This specifies the dataset that
551 * will be searched for a seuqence called sequenceId
553 * - sequenceId within the dataset.
554 * @param pdbEntryString
555 * - the short name for the PDB file
557 * - pdb file - either a URL or a valid PDB file.
558 * @return true if binding was as success TODO: consider making an exception
559 * structure for indicating when PDB parsing or sequenceId location
562 public abstract boolean addPdbFile(AlignFrame alFrame, String sequenceId,
563 String pdbEntryString, String pdbFile);
566 * adjust horizontal/vertical scroll to make the given location the top left
567 * hand corner for the given view
571 * @param leftHandColumn
573 public abstract void scrollViewToIn(AlignFrame alf, String topRow,
574 String leftHandColumn);
577 * adjust vertical scroll to make the given row the top one for given view
582 public abstract void scrollViewToRowIn(AlignFrame alf, String topRow);
585 * adjust horizontal scroll to make the given column the left one in the given
589 * @param leftHandColumn
591 public abstract void scrollViewToColumnIn(AlignFrame alf,
592 String leftHandColumn);
597 * @see jalview.appletgui.AlignFrame#getFeatureGroups();
600 public abstract String getFeatureGroups();
604 * AlignFrame to get feature groups on
606 * @see jalview.appletgui.AlignFrame#getFeatureGroups();
608 public abstract String getFeatureGroupsOn(AlignFrame alf);
613 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean);
616 public abstract String getFeatureGroupsOfState(boolean visible);
620 * align frame to get groups of state visible
623 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean);
625 public abstract String getFeatureGroupsOfStateOn(AlignFrame alf,
630 * tab separated list of group names
633 * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
636 public abstract void setFeatureGroupStateOn(AlignFrame alf,
641 public abstract void setFeatureGroupState(String groups, boolean state);
644 * List separator string
646 * @return the separator
649 public abstract String getSeparator();
652 * List separator string
655 * the separator to set. empty string will reset separator to default
658 public abstract void setSeparator(String separator);
661 * Retrieve fragments of a large packet of data made available by JalviewLite.
663 * @param messageclass
665 * @return next chunk of message
668 public abstract String getJsMessage(String messageclass, String viewId);
670 /// in http://www.jalview.org/examples/jalviewLiteJs.html but missing here
672 // get selected sequences as alignment as format with or without start-end
675 public String getSelectedSequencesAsAlignment(String format,
678 // get selected sequences as alignment from given view as format with or
679 // without start-end suffix
680 public String getSelectedSequencesAsAlignmentFrom(AlignFrame alf,
681 String format, boolean suffix);
684 public String arrayToSeparatorList(String[] array);
686 // get a string array from a list
688 public String[] separatorListToArray(String list);
690 // debug flag - controls output to standard out
691 public static boolean debug = false;