3 import java.io.IOException;
6 import jalview.api.AlignViewportI;
7 import jalview.datamodel.ColumnSelection;
8 import jalview.datamodel.HiddenColumns;
9 import jalview.datamodel.PDBEntry;
10 import jalview.datamodel.SequenceGroup;
11 import jalview.datamodel.SequenceI;
12 import jalview.gui.AlignFrame;
13 import jalview.io.DataSourceType;
14 import jalview.structure.SelectionSource;
15 import jalview.structure.VamsasSource;
18 * JAL-3369 JalviewJS API BH 2019.07.17
23 public interface JalviewJSApi
26 // debug flag - controls output to standard out
27 public static boolean debug = false;
30 * bind a pdb file to a sequence in the given AlignFrame.
33 * - null or specific AlignFrame. This specifies the dataset that
34 * will be searched for a seuqence called sequenceId
36 * - sequenceId within the dataset or null
38 * - the four-character PDB ID
40 * - pdb file - either a URL or a valid PDB file or null.
41 * @return true if binding was success
43 public boolean addPdbFile(AlignFrame alFrame, String sequenceId,
44 String pdbId, String pdbFile);
47 * The following public methods may be called externally, eg via javascript in
51 * <em>TODO: introduce interface for jalview.appletgui.AlignFrame</em><br>
53 * Most function arguments are strings, which contain serialised versions of
54 * lists. Lists of things are separated by a separator character - either the
55 * default or a user supplied one. Ranges and positions on an alignment or
56 * sequence can be specified as a list, where an item containing a single
57 * number is a single position, and an item like 1-2 specifies columns 1 and 2
65 // public interface JalviewLiteJsApi
69 * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
70 * PFAM - see jalview.io.AppletFormatAdapter for full list);
76 public String getAlignment(String format);
79 * get alignment as format with jalview start-end sequence suffix appended
86 public String getAlignment(String format, String suffix);
89 * get alignment displayed in alf as format
95 public String getAlignmentFrom(AlignFrame alf, String format);
98 * get alignment displayed in alf as format with or without the jalview
99 * start-end sequence suffix appended
106 public String getAlignmentFrom(AlignFrame alf, String format,
110 * get a separator separated list of sequence IDs reflecting the order of the
116 public String getAlignmentOrder();
119 * get a separator separated list of sequence IDs reflecting the order of the
125 public String[] getAlignmentOrderFrom(AlignFrame alf);
128 * get current alignment's annotation as an annotation file
133 public String getAnnotation();
136 * get alignment view alf's annotation as an annotation file
141 public String getAnnotationFrom(AlignFrame alf);
143 public Object getAppletParameter(String name, boolean asString);
145 public URL getCodeBase();
147 public URL getDocumentBase();
152 * @see jalview.appletgui.AlignFrame#getFeatureGroups();
155 public String[] getFeatureGroups();
160 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean);
163 public String[] getFeatureGroupsOfState(boolean visible);
167 * align frame to get groups of state visible
170 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean);
172 public String[] getFeatureGroupsOfStateOn(AlignFrame alf,
177 * AlignFrame to get feature groups on
179 * @see jalview.appletgui.AlignFrame#getFeatureGroups();
181 public String[] getFeatureGroupsOn(AlignFrame alf);
184 * get the sequence features in the given format (Jalview or GFF);
190 public String getFeatures(String format);
193 * get the sequence features in alf in the given format (Jalview or GFF);
199 public String getFeaturesFrom(AlignFrame alf, String format);
201 public Object getFrameForSource(VamsasSource source);
203 public String getParameter(String name);
206 * @return String list of selected sequence IDs, each terminated by the
207 * 'boolean not' character (""+0x00AC); or (¬);
210 public SequenceI[] getSelectedSequences();
214 * separator string or null for default
215 * @return String list of selected sequence IDs, each terminated by given
219 public SequenceI[] getSelectedSequences(String sep);
222 * get sequences selected in current AlignFrame and return their alignment in
223 * format 'format' either with or without suffix
226 * - where selection is
228 * - format of alignment file
230 * - "true" to append /start-end string to each sequence ID
231 * @return selected sequences as flat file or empty string if there was no
235 public String getSelectedSequencesAsAlignment(String format,
239 * get sequences selected in alf and return their alignment in format 'format'
240 * either with or without suffix
243 * - where selection is
245 * - format of alignment file
247 * - "true" to append /start-end string to each sequence ID
248 * @return selected sequences as flat file or empty string if there was no
251 public String getSelectedSequencesAsAlignmentFrom(AlignFrame alf,
252 String format, String suffix);
256 * AlignFrame containing selection
257 * @return String list of selected sequence IDs, each terminated by current
258 * default separator sequence
261 public SequenceI[] getSelectedSequencesFrom(AlignFrame alf);
263 // BH incompatibility here -- JalviewLite created an AlignFrame; Jalview
264 // creates an AlignmentPanel
266 // * create a new view and return the AlignFrame instance
271 // public AlignFrame newView();
274 // * create a new view named name and return the AlignFrame instance
280 // public AlignFrame newView(String name);
283 // * create a new view on alf and return the AlignFrame instance
288 // public AlignFrame newViewFrom(AlignFrame alf);
291 // * create a new view named name on alf
297 // public AlignFrame newViewFrom(AlignFrame alf, String name);
300 * get list of selected sequence IDs separated by given separator
303 * window containing selection
305 * separator string to use - default is 'boolean not'
306 * @return String list of selected sequence IDs, each terminated by the given
309 public SequenceI[] getSelectedSequencesFrom(AlignFrame alf, String sep);
311 public Object[] getSelectionForListener(SequenceGroup seqsel,
312 ColumnSelection colsel, HiddenColumns hidden,
313 SelectionSource source, Object alignFrame);
315 public AlignViewportI getViewport();
320 * id of sequence to highlight
322 * integer position [ tobe implemented or range ] on sequence
323 * @param alignedPosition
324 * true/false/empty string - indicate if position is an alignment
325 * column or unaligned sequence position
328 public void highlight(String sequenceId, String position,
329 String alignedPosition);
334 * id of sequence to highlight
336 * integer position [ tobe implemented or range ] on sequence
337 * @param alignedPosition
338 * false, blank or something else - indicate if position is an
339 * alignment column or unaligned sequence position
341 public void highlightIn(AlignFrame alf, String sequenceId,
342 String position, String alignedPosition);
347 * alignment file as a string
350 * @return null or new alignment frame
353 public AlignFrame loadAlignment(String text, String title);
356 * add the given features or annotation to the current alignment
361 public void loadAnnotation(String annotation);
364 * add the given features or annotation to the given alignment view
369 public void loadAnnotationFrom(AlignFrame alf, String annotation);
372 * parse the given string as a jalview feature or GFF annotation file and
373 * optionally enable feature display on the current AlignFrame
376 * - gff or features file
377 * @param autoenabledisplay
378 * - when true, feature display will be enabled if any features can
379 * be parsed from the string.
382 public void loadFeatures(String features, boolean autoenabledisplay);
385 * parse the given string as a jalview feature or GFF annotation file and
386 * optionally enable feature display on the given AlignFrame.
390 * - gff or features file
391 * @param autoenabledisplay
392 * - when true, feature display will be enabled if any features can
393 * be parsed from the string.
394 * @return true if data parsed as features
396 public boolean loadFeaturesFrom(AlignFrame alf, String features,
397 boolean autoenabledisplay);
399 public boolean loadScoreFile(String sScoreFile) throws IOException;
401 public void newFeatureSettings();
403 public void newStructureView(PDBEntry pdb, SequenceI[] seqs,
404 String[] chains, DataSourceType protocol);
406 /// in http://www.jalview.org/examples/jalviewLiteJs.html but missing here
408 // get selected sequences as alignment as format with or without start-end
412 * re-order the given alignment using the given array of sequence IDs
416 * array of sequence IDs
418 * - string to use when referring to ordering action in undo buffer
419 * @return 'true' if alignment was actually reordered. empty string if
420 * alignment did not contain sequences.
422 String orderAlignmentBy(AlignFrame alf, String[] ids, String undoName);
424 // get a string array from a list
427 * re-order the current alignment using the given list of sequence IDs
430 * array of sequence IDs
432 * - string to use when referring to ordering action in undo buffer
433 * @return 'true' if alignment was actually reordered. empty string if
434 * alignment did not contain sequences.
437 public String orderBy(String[] ids, String undoName);
440 * re-order the current alignment using the given list of sequence IDs
443 * array of sequence IDs
445 * - string to use when referring to ordering action in undo buffer
447 * @return 'true' if alignment was actually reordered. empty string if
448 * alignment did not contain sequences.
451 // public String orderBy(String[] ids, String undoName, String sep);
454 // public boolean getDefaultParameter(String name, boolean def);
456 public boolean parseFeaturesFile(String param, DataSourceType protocol);
459 * remove any callback using the given listener function and associated with
460 * the given AlignFrame (or null for all callbacks);
467 public void removeSelectionListener(AlignFrame af, String listener);
469 // public void setAlignPdbStructures(boolean defaultParameter);
472 * adjust horizontal scroll to make the given column the left one in the given
476 * @param leftHandColumn
478 public void scrollViewToColumnIn(AlignFrame alf, String leftHandColumn);
481 * adjust horizontal/vertical scroll to make the given location the top left
482 * hand corner for the given view
486 * @param leftHandColumn
488 public void scrollViewToIn(AlignFrame alf, String topRow,
489 String leftHandColumn);
492 * adjust vertical scroll to make the given row the top one for given view
497 public void scrollViewToRowIn(AlignFrame alf, String topRow);
500 * select regions of the currrent alignment frame
503 * String separated list of sequence ids or empty string
505 * String separated list { column range or column, ..} or empty
509 public void select(String sequenceIds, String columns);
512 * select regions of the currrent alignment frame
515 * String separated list { column range, seq1...seqn sequence ids }
517 * separator between toselect fields
520 public void select(String sequenceIds, String columns, String sep);
523 * select regions of the given alignment frame
527 * String separated list { column range, seq1...seqn sequence ids }
529 * separator between toselect fields
531 public void selectIn(AlignFrame alf, String sequenceIds, String columns);
534 * select regions of the given alignment frame
538 * String separated list { column range, seq1...seqn sequence ids }
540 * separator between toselect fields
542 public void selectIn(AlignFrame alf, String sequenceIds, String columns,
545 public void setFeatureGroupState(String groups, boolean state);
547 public void setFeatureGroupState(String[] groups, boolean state);
549 // public StructureSelectionManagerProvider
550 // getStructureSelectionManagerProvider();
554 * tab separated list of group names
557 * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
560 public void setFeatureGroupStateOn(AlignFrame alf, String groups,
563 public void setSelectionListener(AlignFrame af, String listener);
566 * register a javascript function to handle any alignment selection events.
567 * Events are generated when the user completes a selection event, or when the
568 * user deselects all selected regions.
571 * name of javascript function (called with arguments
572 * [jalview.appletgui.AlignFrame, String(sequence set id);,
573 * String(separator separated list of sequences which were
574 * selected);, String(separator separated list of column ranges (i.e.
575 * single number or hyphenated range); that were selected);]
578 public void setSelectionListener(String listener);
580 public void updateForAnnotations();
585 * public static method for JalviewJS API to open a PCAPanel without
586 * necessarily using a dialog.
591 * @return the PCAPanel, or the string "label.you_need_at_least_n_sequences"
592 * if number of sequences selected is inappropriate
594 public Object openPcaPanel(AlignFrame af, String modelName);
597 * Open a new Tree panel on the desktop statically. Params are standard (not
598 * set by Groovy). No dialog is opened.
604 * @return null, or the string "label.you_need_at_least_n_sequences" if number
605 * of sequences selected is inappropriate
607 public Object openTreePanel(AlignFrame af, String treeType,
611 * process commandline arguments after the JavaScript application has started
616 public Object parseArguments(String[] args);
618 public void showStructure(AlignFrame af, String pdbID, String fileType);
620 public void showOverview();