3 import java.io.IOException;
5 import java.util.Hashtable;
7 import jalview.api.AlignViewportI;
8 import jalview.datamodel.ColumnSelection;
9 import jalview.datamodel.HiddenColumns;
10 import jalview.datamodel.PDBEntry;
11 import jalview.datamodel.SequenceGroup;
12 import jalview.datamodel.SequenceI;
13 import jalview.gui.AlignFrame;
14 import jalview.io.DataSourceType;
15 import jalview.structure.SelectionSource;
16 import jalview.structure.VamsasSource;
19 * JAL-3369 JalviewJS API BH 2019.07.17
24 public interface JalviewJSApi
27 // debug flag - controls output to standard out
28 public static boolean debug = false;
31 * bind a pdb file to a sequence in the given AlignFrame.
34 * - null or specific AlignFrame. This specifies the dataset that
35 * will be searched for a seuqence called sequenceId
37 * - sequenceId within the dataset.
38 * @param pdbEntryString
39 * - the short name for the PDB file
41 * - pdb file - either a URL or a valid PDB file.
42 * @return true if binding was as success TODO: consider making an exception
43 * structure for indicating when PDB parsing or sequenceId location
46 public boolean addPdbFile(AlignFrame alFrame, String sequenceId, String pdbEntryString, String pdbFile);
48 public String arrayToSeparatorList(String[] array);
51 * The following public methods may be called externally, eg via javascript in
55 * <em>TODO: introduce interface for
56 * jalview.appletgui.AlignFrame</em><br>
58 * Most function arguments are strings, which contain serialised versions of
59 * lists. Lists of things are separated by a separator character - either the
60 * default or a user supplied one. Ranges and positions on an alignment or
61 * sequence can be specified as a list, where an item containing a single
62 * number is a single position, and an item like 1-2 specifies columns 1 and 2
70 // public interface JalviewLiteJsApi
74 * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
75 * PFAM - see jalview.io.AppletFormatAdapter for full list);
81 public String getAlignment(String format);
84 * get alignment as format with jalview start-end sequence suffix appended
91 public String getAlignment(String format, String suffix);
94 * get alignment displayed in alf as format
100 public String getAlignmentFrom(AlignFrame alf, String format);
103 * get alignment displayed in alf as format with or without the jalview
104 * start-end sequence suffix appended
111 public String getAlignmentFrom(AlignFrame alf, String format, String suffix);
114 * get a separator separated list of sequence IDs reflecting the order of the
120 public String getAlignmentOrder();
123 * get a separator separated list of sequence IDs reflecting the order of the
129 public String getAlignmentOrderFrom(AlignFrame alf);
132 * get a sep separated list of sequence IDs reflecting the order of the
140 public String getAlignmentOrderFrom(AlignFrame alf, String sep);
143 * get current alignment's annotation as an annotation file
148 public String getAnnotation();
151 * get alignment view alf's annotation as an annotation file
156 public String getAnnotationFrom(AlignFrame alf);
158 public Object getAppletParameter(String name, boolean asString);
160 public URL getCodeBase();
162 public URL getDocumentBase();
167 * @see jalview.appletgui.AlignFrame#getFeatureGroups();
170 public String getFeatureGroups();
175 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean);
178 public String getFeatureGroupsOfState(boolean visible);
182 * align frame to get groups of state visible
185 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean);
187 public String getFeatureGroupsOfStateOn(AlignFrame alf, boolean visible);
191 * AlignFrame to get feature groups on
193 * @see jalview.appletgui.AlignFrame#getFeatureGroups();
195 public String getFeatureGroupsOn(AlignFrame alf);
198 * get the sequence features in the given format (Jalview or GFF);
204 public String getFeatures(String format);
207 * get the sequence features in alf in the given format (Jalview or GFF);
213 public String getFeaturesFrom(AlignFrame alf, String format);
215 public Object getFrameForSource(VamsasSource source);
217 public jalview.renderer.seqfeatures.FeatureRenderer getNewFeatureRenderer(AlignViewportI vp);
219 public String getParameter(String name);
222 * @return String list of selected sequence IDs, each terminated by the
223 * 'boolean not' character (""+0x00AC); or (¬);
226 public SequenceI[] getSelectedSequences();
230 * separator string or null for default
231 * @return String list of selected sequence IDs, each terminated by given
235 public SequenceI[] getSelectedSequences(String sep);
238 * get sequences selected in current AlignFrame and return their alignment in
239 * format 'format' either with or without suffix
242 * - where selection is
244 * - format of alignment file
246 * - "true" to append /start-end string to each sequence ID
247 * @return selected sequences as flat file or empty string if there was no
251 public String getSelectedSequencesAsAlignment(String format, String suffix);
254 * get sequences selected in alf and return their alignment in format 'format'
255 * either with or without suffix
258 * - where selection is
260 * - format of alignment file
262 * - "true" to append /start-end string to each sequence ID
263 * @return selected sequences as flat file or empty string if there was no
266 public String getSelectedSequencesAsAlignmentFrom(AlignFrame alf, String format, String suffix);
270 * AlignFrame containing selection
271 * @return String list of selected sequence IDs, each terminated by current
272 * default separator sequence
275 public SequenceI[] getSelectedSequencesFrom(AlignFrame alf);
277 // BH incompatibility here -- JalviewLite created an AlignFrame; Jalview
278 // creates an AlignmentPanel
280 // * create a new view and return the AlignFrame instance
285 // public AlignFrame newView();
288 // * create a new view named name and return the AlignFrame instance
294 // public AlignFrame newView(String name);
297 // * create a new view on alf and return the AlignFrame instance
302 // public AlignFrame newViewFrom(AlignFrame alf);
305 // * create a new view named name on alf
311 // public AlignFrame newViewFrom(AlignFrame alf, String name);
314 * get list of selected sequence IDs separated by given separator
317 * window containing selection
319 * separator string to use - default is 'boolean not'
320 * @return String list of selected sequence IDs, each terminated by the given
323 public SequenceI[] getSelectedSequencesFrom(AlignFrame alf, String sep);
325 public Object[] getSelectionForListener(SequenceGroup seqsel, ColumnSelection colsel, HiddenColumns hidden, SelectionSource source, Object alignFrame);
328 * List separator string
330 * @return the separator
333 public String getSeparator();
335 public AlignViewportI getViewport();
340 * id of sequence to highlight
342 * integer position [ tobe implemented or range ] on sequence
343 * @param alignedPosition
344 * true/false/empty string - indicate if position is an alignment
345 * column or unaligned sequence position
348 public void highlight(String sequenceId, String position, String alignedPosition);
353 * id of sequence to highlight
355 * integer position [ tobe implemented or range ] on sequence
356 * @param alignedPosition
357 * false, blank or something else - indicate if position is an
358 * alignment column or unaligned sequence position
360 public void highlightIn(AlignFrame alf, String sequenceId, String position, String alignedPosition);
365 * alignment file as a string
368 * @return null or new alignment frame
371 public AlignFrame loadAlignment(String text, String title);
374 * add the given features or annotation to the current alignment
379 public void loadAnnotation(String annotation);
382 * add the given features or annotation to the given alignment view
387 public void loadAnnotationFrom(AlignFrame alf, String annotation);
390 * parse the given string as a jalview feature or GFF annotation file and
391 * optionally enable feature display on the current AlignFrame
394 * - gff or features file
395 * @param autoenabledisplay
396 * - when true, feature display will be enabled if any features can
397 * be parsed from the string.
400 public void loadFeatures(String features, boolean autoenabledisplay);
403 * parse the given string as a jalview feature or GFF annotation file and
404 * optionally enable feature display on the given AlignFrame.
408 * - gff or features file
409 * @param autoenabledisplay
410 * - when true, feature display will be enabled if any features can
411 * be parsed from the string.
412 * @return true if data parsed as features
414 public boolean loadFeaturesFrom(AlignFrame alf, String features, boolean autoenabledisplay);
416 public boolean loadScoreFile(String sScoreFile) throws IOException;
418 public void newFeatureSettings();
420 public void newStructureView(PDBEntry pdb, SequenceI[] seqs, String[] chains, DataSourceType protocol);
423 * public static method for JalviewJS API to open a PCAPanel without
424 * necessarily using a dialog.
429 * @return the PCAPanel, or the string "label.you_need_at_least_n_sequences"
430 * if number of sequences selected is inappropriate
432 public Object openPcaPanel(AlignFrame af, String modelName);
435 * Open a new Tree panel on the desktop statically. Params are standard (not
436 * set by Groovy). No dialog is opened.
442 * @return null, or the string "label.you_need_at_least_n_sequences" if number
443 * of sequences selected is inappropriate
445 public Object openTreePanel(AlignFrame af, String treeType, String modelName);
447 /// in http://www.jalview.org/examples/jalviewLiteJs.html but missing here
449 // get selected sequences as alignment as format with or without start-end
453 * re-order the given alignment using the given list of sequence IDs separated
458 * - sep separated list
460 * - string to use when referring to ordering action in undo buffer
462 * @return 'true' if alignment was actually reordered. empty string if
463 * alignment did not contain sequences.
465 public String orderAlignmentBy(AlignFrame alf, String order, String undoName, String sep);
467 // get a string array from a list
470 * re-order the current alignment using the given list of sequence IDs
473 * - sep separated list
475 * - string to use when referring to ordering action in undo buffer
476 * @return 'true' if alignment was actually reordered. empty string if
477 * alignment did not contain sequences.
480 public String orderBy(String order, String undoName);
483 * re-order the current alignment using the given list of sequence IDs
487 * - sep separated list
489 * - string to use when referring to ordering action in undo buffer
491 * @return 'true' if alignment was actually reordered. empty string if
492 * alignment did not contain sequences.
495 public String orderBy(String order, String undoName, String sep);
498 * process commandline arguments after the JavaScript application has started
503 public Object parseArguments(String[] args);
505 // public boolean getDefaultParameter(String name, boolean def);
507 public boolean parseFeaturesFile(String param, DataSourceType protocol);
510 * remove any callback using the given listener function and associated with
511 * the given AlignFrame (or null for all callbacks);
518 public void removeSelectionListener(AlignFrame af, String listener);
520 // public void setAlignPdbStructures(boolean defaultParameter);
523 * adjust horizontal scroll to make the given column the left one in the given
527 * @param leftHandColumn
529 public void scrollViewToColumnIn(AlignFrame alf, String leftHandColumn);
532 * adjust horizontal/vertical scroll to make the given location the top left
533 * hand corner for the given view
537 * @param leftHandColumn
539 public void scrollViewToIn(AlignFrame alf, String topRow, String leftHandColumn);
542 * adjust vertical scroll to make the given row the top one for given view
547 public void scrollViewToRowIn(AlignFrame alf, String topRow);
550 * select regions of the currrent alignment frame
553 * String separated list of sequence ids or empty string
555 * String separated list { column range or column, ..} or empty
559 public void select(String sequenceIds, String columns);
562 * select regions of the currrent alignment frame
565 * String separated list { column range, seq1...seqn sequence ids }
567 * separator between toselect fields
570 public void select(String sequenceIds, String columns, String sep);
573 * select regions of the given alignment frame
577 * String separated list { column range, seq1...seqn sequence ids }
579 * separator between toselect fields
581 public void selectIn(AlignFrame alf, String sequenceIds, String columns);
584 * select regions of the given alignment frame
588 * String separated list { column range, seq1...seqn sequence ids }
590 * separator between toselect fields
592 public void selectIn(AlignFrame alf, String sequenceIds, String columns, String sep);
594 public String[] separatorListToArray(String list);
596 public void setFeatureGroupState(String groups, boolean state);
598 public void setFeatureGroupState(String[] groups, boolean state);
600 // public StructureSelectionManagerProvider
601 // getStructureSelectionManagerProvider();
605 * tab separated list of group names
608 * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
611 public void setFeatureGroupStateOn(AlignFrame alf, String groups, boolean state);
613 public void setSelectionListener(AlignFrame af, String listener);
616 * register a javascript function to handle any alignment selection events.
617 * Events are generated when the user completes a selection event, or when the
618 * user deselects all selected regions.
621 * name of javascript function (called with arguments
622 * [jalview.appletgui.AlignFrame, String(sequence set id);,
623 * String(separator separated list of sequences which were
624 * selected);, String(separator separated list of column ranges (i.e.
625 * single number or hyphenated range); that were selected);]
628 public void setSelectionListener(String listener);
631 * List separator string
634 * the separator to set. empty string will reset separator to default
637 public void setSeparator(String separator);
639 public void showOverview();
641 public void updateForAnnotations();