1 package jalview.javascript;
3 import jalview.appletgui.AlignFrame;
6 * The following public methods may be called
7 * externally, eg via javascript in an HTML page.
9 * <br><em>TODO: introduce abstract interface for jalview.appletgui.AlignFrame</em><br>
11 * Most function arguments are strings, which contain serialised versions of lists.
12 * Lists of things are separated by a separator character - either the default or a user supplied one.
13 * 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.
20 public interface JalviewLiteJsApi
24 * @return String list of selected sequence IDs, each terminated by the
25 * 'boolean not' character (""+0x00AC) or (¬)
27 public abstract String getSelectedSequences();
31 * separator string or null for default
32 * @return String list of selected sequence IDs, each terminated by given
35 public abstract String getSelectedSequences(String sep);
39 * alignframe containing selection
40 * @return String list of selected sequence IDs, each terminated by current
41 * default separator sequence
44 public abstract String getSelectedSequencesFrom(AlignFrame alf);
47 * get list of selected sequence IDs separated by given separator
50 * window containing selection
52 * separator string to use - default is 'boolean not'
53 * @return String list of selected sequence IDs, each terminated by the given
56 public abstract String getSelectedSequencesFrom(AlignFrame alf, String sep);
61 * id of sequence to highlight
63 * integer position [ tobe implemented or range ] on sequence
64 * @param alignedPosition
65 * true/false/empty string - indicate if position is an alignment
66 * column or unaligned sequence position
68 public abstract void highlight(String sequenceId, String position,
69 String alignedPosition);
74 * id of sequence to highlight
76 * integer position [ tobe implemented or range ] on sequence
77 * @param alignedPosition
78 * false, blank or something else - indicate if position is an
79 * alignment column or unaligned sequence position
81 public abstract void highlightIn(AlignFrame alf, String sequenceId,
82 String position, String alignedPosition);
85 * select regions of the currrent alignment frame
88 * String separated list of sequence ids or empty string
90 * String separated list { column range or column, ..} or empty
93 public abstract void select(String sequenceIds, String columns);
96 * select regions of the currrent alignment frame
99 * String separated list { column range, seq1...seqn sequence ids }
101 * separator between toselect fields
103 public abstract void select(String sequenceIds, String columns, String sep);
106 * select regions of the given alignment frame
110 * String separated list { column range, seq1...seqn sequence ids }
112 * separator between toselect fields
114 public abstract void selectIn(AlignFrame alf, String sequenceIds,
118 * select regions of the given alignment frame
122 * String separated list { column range, seq1...seqn sequence ids }
124 * separator between toselect fields
126 public abstract void selectIn(AlignFrame alf, String sequenceIds,
127 String columns, String sep);
130 * get sequences selected in current alignFrame and return their alignment in
131 * format 'format' either with or without suffix
134 * - where selection is
136 * - format of alignment file
138 * - "true" to append /start-end string to each sequence ID
139 * @return selected sequences as flat file or empty string if there was no
142 public abstract String getSelectedSequencesAsAlignment(String format,
146 * get sequences selected in alf and return their alignment in format 'format'
147 * either with or without suffix
150 * - where selection is
152 * - format of alignment file
154 * - "true" to append /start-end string to each sequence ID
155 * @return selected sequences as flat file or empty string if there was no
158 public abstract String getSelectedSequencesAsAlignmentFrom(
159 AlignFrame alf, String format, String suffix);
162 * get a separator separated list of sequence IDs reflecting the order of the current alignment
165 public abstract String getAlignmentOrder();
167 * get a separator separated list of sequence IDs reflecting the order of the alignment in alf
172 public abstract String getAlignmentOrderFrom(AlignFrame alf);
175 * get a sep separated list of sequence IDs reflecting the order of the alignment in alf
178 * @param sep - separator to use
181 public abstract String getAlignmentOrderFrom(AlignFrame alf, String sep);
183 * re-order the current alignment using the given list of sequence IDs
184 * @param order - sep separated list
185 * @param undoName - string to use when referring to ordering action in undo buffer
186 * @return 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
188 public abstract String orderBy(String order, String undoName);
191 * re-order the current alignment using the given list of sequence IDs
195 * - sep separated list
197 * - string to use when referring to ordering action in undo buffer
199 * @return 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
201 public abstract String orderBy(String order, String undoName, String sep);
204 * re-order the given alignment using the given list of sequence IDs
209 * - sep separated list
211 * - string to use when referring to ordering action in undo buffer
213 * @return 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
215 public abstract String orderAlignmentBy(AlignFrame alf, String order,
216 String undoName, String sep);
219 * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP, PFAM - see jalview.io.AppletFormatAdapter for full list)
223 public abstract String getAlignment(String format);
226 * get alignment displayed in alf as format
231 public abstract String getAlignmentFrom(AlignFrame alf, String format);
234 * get alignment as format with jalview start-end sequence suffix appended
239 public abstract String getAlignment(String format, String suffix);
242 * get alignment displayed in alf as format
243 * with or without the jalview start-end sequence suffix appended
249 public abstract String getAlignmentFrom(AlignFrame alf, String format,
253 * add the given features or annotation to the current alignment
256 public abstract void loadAnnotation(String annotation);
259 * add the given features or annotation to the given alignment view
263 public abstract void loadAnnotationFrom(AlignFrame alf, String annotation);
266 * get the sequence features in the given format (Jalview or GFF)
270 public abstract String getFeatures(String format);
273 * get the sequence features in alf in the given format (Jalview or GFF)
278 public abstract String getFeaturesFrom(AlignFrame alf, String format);
281 * get current alignment's annotation as an annotation file
284 public abstract String getAnnotation();
287 * get alignment view alf's annotation as an annotation file
291 public abstract String getAnnotationFrom(AlignFrame alf);
294 * create a new view and return the alignFrame instance
297 public abstract AlignFrame newView();
300 * create a new view named name and return the alignFrame instance
304 public abstract AlignFrame newView(String name);
307 * create a new view on alf and return the alignFrame instance
311 public abstract AlignFrame newViewFrom(AlignFrame alf);
314 * create a new view named name on alf
319 public abstract AlignFrame newViewFrom(AlignFrame alf, String name);
324 * alignment file as a string
327 * @return null or new alignment frame
329 public abstract AlignFrame loadAlignment(String text, String title);
332 * register a javascript function to handle any alignment mouseover events
333 * @param listener name of javascript function (called with arguments [jalview.appletgui.AlignFrame,String(sequence id),String(column in alignment), String(position in sequence)]
335 public abstract void setMouseoverListener(String listener);
338 * register a javascript function to handle mouseover events
339 * @param af (null or specific alignframe for which events are to be listened for)
340 * @param listener name of javascript function
342 public abstract void setMouseoverListener(AlignFrame af, String listener);
345 * register a javascript function to handle any alignment selection events. Events are generated when the user completes a selection event, or when the user deselects all selected regions.
346 * @param listener name of javascript function (called with arguments [jalview.appletgui.AlignFrame, String(sequence set id), String(separator separated list of sequences which were selected), String(separator separated list of column ranges (i.e. single number or hyphenated range) that were selected)]
348 public abstract void setSelectionListener(String listener);
350 public abstract void setSelectionListener(AlignFrame af, String listener);
353 * register a javascript function to handle events normally routed to a Jmol structure viewer.
354 * @param listener - javascript function (arguments are variable, see jalview.javascript.MouseOverStructureListener for full details)
355 * @param modelSet - separator separated list of PDB file URIs that this viewer is handling. These files must be in the same order they appear in Jmol (e.g. first one is frame 1, second is frame 2, etc).
356 @see jalview.javascript.MouseOverStructureListener
358 public abstract void setStructureListener(String listener, String modelSet);
361 * remove any callback using the given listener function and associated with
362 * the given alignFrame (or null for all callbacks)
369 public abstract void removeJavascriptListener(AlignFrame af,
373 * send a mouseover message to all the alignment windows associated with the
374 * given residue in the pdbfile
380 public abstract void mouseOverStructure(String pdbResNum, String chain,
384 * bind a pdb file to a sequence in the given alignFrame.
387 * - null or specific alignFrame. This specifies the dataset that
388 * will be searched for a seuqence called sequenceId
390 * - sequenceId within the dataset.
391 * @param pdbEntryString
392 * - the short name for the PDB file
394 * - pdb file - either a URL or a valid PDB file.
395 * @return true if binding was as success TODO: consider making an exception
396 * structure for indicating when PDB parsing or sequenceId location
399 public abstract boolean addPdbFile(AlignFrame alFrame, String sequenceId,
400 String pdbEntryString, String pdbFile);
403 * adjust horizontal/vertical scroll to make the given location the top left hand corner for the given view
407 * @param leftHandColumn
409 public abstract void scrollViewToIn(AlignFrame alf, String topRow,
410 String leftHandColumn);
412 * adjust vertical scroll to make the given row the top one for given view
417 public abstract void scrollViewToRowIn(AlignFrame alf, String topRow);
419 * adjust horizontal scroll to make the given column the left one in the given view
422 * @param leftHandColumn
424 public abstract void scrollViewToColumnIn(AlignFrame alf, String leftHandColumn);
429 * @see jalview.appletgui.AlignFrame#getFeatureGroups()
431 public abstract String getFeatureGroups();
435 * alignframe to get feature groups on
437 * @see jalview.appletgui.AlignFrame#getFeatureGroups()
439 public abstract String getFeatureGroupsOn(AlignFrame alf);
444 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
446 public abstract String getFeatureGroupsOfState(boolean visible);
450 * align frame to get groups of state visible
453 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
455 public abstract String getFeatureGroupsOfStateOn(AlignFrame alf,
460 * tab separated list of group names
463 * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
466 public abstract void setFeatureGroupStateOn(AlignFrame alf,
467 String groups, boolean state);
469 public abstract void setFeatureGroupState(String groups, boolean state);
472 * List separator string
474 * @return the separator
476 public abstract String getSeparator();
479 * List separator string
482 * the separator to set. empty string will reset separator to default
484 public abstract void setSeparator(String separator);
487 * Retrieve fragments of a large packet of data made available by JalviewLite.
488 * @param messageclass
490 * @return next chunk of message
492 public abstract String getJsMessage(String messageclass, String viewId);