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.
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 the make the given location the top left hand corner for given current view
407 * @param leftHandColumn
409 public abstract void scrollViewToIn(AlignFrame alf, String topRow,
410 String leftHandColumn);
415 * @see jalview.appletgui.AlignFrame#getFeatureGroups()
417 public abstract String getFeatureGroups();
421 * alignframe to get feature groups on
423 * @see jalview.appletgui.AlignFrame#getFeatureGroups()
425 public abstract String getFeatureGroupsOn(AlignFrame alf);
430 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
432 public abstract String getFeatureGroupsOfState(boolean visible);
436 * align frame to get groups of state visible
439 * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
441 public abstract String getFeatureGroupsOfStateOn(AlignFrame alf,
446 * tab separated list of group names
449 * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
452 public abstract void setFeatureGroupStateOn(AlignFrame alf,
453 String groups, boolean state);
455 public abstract void setFeatureGroupState(String groups, boolean state);
458 * List separator string
460 * @return the separator
462 public abstract String getSeparator();
465 * List separator string
468 * the separator to set. empty string will reset separator to default
470 public abstract void setSeparator(String separator);
473 * Retrieve fragments of a large packet of data made available by JalviewLite.
474 * @param messageclass
476 * @return next chunk of message
478 public abstract String getJsMessage(String messageclass, String viewId);