Classes

Class	Line #	Total Statements	Complexity	TOTAL Coverage	Actions
JalviewLiteJsApi	40	0	0	-1.0 -	Show methods

Class JalviewLiteJsApi

Class JalviewLiteJsApi	Line # 40	Total Statements 0	Complexity 0	TOTAL Coverage -1.0 -

 

Contributing tests

Source view

1		/*
2		* Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3		* Copyright (C) $$Year-Rel$$ The Jalview Authors
4		*
5		* This file is part of Jalview.
6		*
7		* Jalview is free software: you can redistribute it and/or
8		* modify it under the terms of the GNU General Public License
9		* as published by the Free Software Foundation, either version 3
10		* of the License, or (at your option) any later version.
11		*
12		* Jalview is distributed in the hope that it will be useful, but
13		* WITHOUT ANY WARRANTY; without even the implied warranty
14		* of MERCHANTABILITY or FITNESS FOR A PARTICULAR
15		* PURPOSE. See the GNU General Public License for more details.
16		*
17		* You should have received a copy of the GNU General Public License
18		* along with Jalview. If not, see <http://www.gnu.org/licenses/>.
19		* The Jalview Authors are detailed in the 'AUTHORS' file.
20		*/
21		package jalview.javascript;
22
23		import jalview.appletgui.AlignFrame;
24
25		/**
26		* The following public methods may be called
27		* externally, eg via javascript in an HTML page.
28		*
29		* <br><em>TODO: introduce abstract interface for jalview.appletgui.AlignFrame</em><br>
30		*
31		* Most function arguments are strings, which contain serialised versions of lists.
32		* Lists of things are separated by a separator character - either the default or a user supplied one.
33		* 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.
34		*/
35
36		/**
37		* @author jimp
38		*
39		*/
		- Uncovered Elements: 0 (0) Complexity: 0 Complexity Density: -
40		public interface JalviewLiteJsApi
41		{
42
43		/**
44		* @return String list of selected sequence IDs, each terminated by the
45		* 'boolean not' character (""+0x00AC) or (&#172;)
46		*/
47		public abstract String getSelectedSequences();
48
49		/**
50		* @param sep
51		* separator string or null for default
52		* @return String list of selected sequence IDs, each terminated by given
53		* separator string
54		*/
55		public abstract String getSelectedSequences(String sep);
56
57		/**
58		* @param alf
59		* alignframe containing selection
60		* @return String list of selected sequence IDs, each terminated by current
61		* default separator sequence
62		*
63		*/
64		public abstract String getSelectedSequencesFrom(AlignFrame alf);
65
66		/**
67		* get list of selected sequence IDs separated by given separator
68		*
69		* @param alf
70		* window containing selection
71		* @param sep
72		* separator string to use - default is 'boolean not'
73		* @return String list of selected sequence IDs, each terminated by the given
74		* separator
75		*/
76		public abstract String getSelectedSequencesFrom(AlignFrame alf,
77		String sep);
78
79		/**
80		*
81		* @param sequenceId
82		* id of sequence to highlight
83		* @param position
84		* integer position [ tobe implemented or range ] on sequence
85		* @param alignedPosition
86		* true/false/empty string - indicate if position is an alignment
87		* column or unaligned sequence position
88		*/
89		public abstract void highlight(String sequenceId, String position,
90		String alignedPosition);
91
92		/**
93		*
94		* @param sequenceId
95		* id of sequence to highlight
96		* @param position
97		* integer position [ tobe implemented or range ] on sequence
98		* @param alignedPosition
99		* false, blank or something else - indicate if position is an
100		* alignment column or unaligned sequence position
101		*/
102		public abstract void highlightIn(AlignFrame alf, String sequenceId,
103		String position, String alignedPosition);
104
105		/**
106		* select regions of the currrent alignment frame
107		*
108		* @param sequenceIds
109		* String separated list of sequence ids or empty string
110		* @param columns
111		* String separated list { column range or column, ..} or empty
112		* string
113		*/
114		public abstract void select(String sequenceIds, String columns);
115
116		/**
117		* select regions of the currrent alignment frame
118		*
119		* @param toselect
120		* String separated list { column range, seq1...seqn sequence ids }
121		* @param sep
122		* separator between toselect fields
123		*/
124		public abstract void select(String sequenceIds, String columns,
125		String sep);
126
127		/**
128		* select regions of the given alignment frame
129		*
130		* @param alf
131		* @param toselect
132		* String separated list { column range, seq1...seqn sequence ids }
133		* @param sep
134		* separator between toselect fields
135		*/
136		public abstract void selectIn(AlignFrame alf, String sequenceIds,
137		String columns);
138
139		/**
140		* select regions of the given alignment frame
141		*
142		* @param alf
143		* @param toselect
144		* String separated list { column range, seq1...seqn sequence ids }
145		* @param sep
146		* separator between toselect fields
147		*/
148		public abstract void selectIn(AlignFrame alf, String sequenceIds,
149		String columns, String sep);
150
151		/**
152		* get sequences selected in current alignFrame and return their alignment in
153		* format 'format' either with or without suffix
154		*
155		* @param alf
156		* - where selection is
157		* @param format
158		* - format of alignment file
159		* @param suffix
160		* - "true" to append /start-end string to each sequence ID
161		* @return selected sequences as flat file or empty string if there was no
162		* current selection
163		*/
164		public abstract String getSelectedSequencesAsAlignment(String format,
165		String suffix);
166
167		/**
168		* get sequences selected in alf and return their alignment in format 'format'
169		* either with or without suffix
170		*
171		* @param alf
172		* - where selection is
173		* @param format
174		* - format of alignment file
175		* @param suffix
176		* - "true" to append /start-end string to each sequence ID
177		* @return selected sequences as flat file or empty string if there was no
178		* current selection
179		*/
180		public abstract String getSelectedSequencesAsAlignmentFrom(AlignFrame alf,
181		String format, String suffix);
182
183		/**
184		* get a separator separated list of sequence IDs reflecting the order of the
185		* current alignment
186		*
187		* @return
188		*/
189		public abstract String getAlignmentOrder();
190
191		/**
192		* get a separator separated list of sequence IDs reflecting the order of the
193		* alignment in alf
194		*
195		* @param alf
196		* @return
197		*/
198		public abstract String getAlignmentOrderFrom(AlignFrame alf);
199
200		/**
201		* get a sep separated list of sequence IDs reflecting the order of the
202		* alignment in alf
203		*
204		* @param alf
205		* @param sep
206		* - separator to use
207		* @return
208		*/
209		public abstract String getAlignmentOrderFrom(AlignFrame alf, String sep);
210
211		/**
212		* re-order the current alignment using the given list of sequence IDs
213		*
214		* @param order
215		* - sep separated list
216		* @param undoName
217		* - string to use when referring to ordering action in undo buffer
218		* @return 'true' if alignment was actually reordered. empty string if
219		* alignment did not contain sequences.
220		*/
221		public abstract String orderBy(String order, String undoName);
222
223		/**
224		* re-order the current alignment using the given list of sequence IDs
225		* separated by sep
226		*
227		* @param order
228		* - sep separated list
229		* @param undoName
230		* - string to use when referring to ordering action in undo buffer
231		* @param sep
232		* @return 'true' if alignment was actually reordered. empty string if
233		* alignment did not contain sequences.
234		*/
235		public abstract String orderBy(String order, String undoName, String sep);
236
237		/**
238		* re-order the given alignment using the given list of sequence IDs separated
239		* by sep
240		*
241		* @param alf
242		* @param order
243		* - sep separated list
244		* @param undoName
245		* - string to use when referring to ordering action in undo buffer
246		* @param sep
247		* @return 'true' if alignment was actually reordered. empty string if
248		* alignment did not contain sequences.
249		*/
250		public abstract String orderAlignmentBy(AlignFrame alf, String order,
251		String undoName, String sep);
252
253		/**
254		* get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
255		* PFAM - see jalview.io.AppletFormatAdapter for full list)
256		*
257		* @param format
258		* @return
259		*/
260		public abstract String getAlignment(String format);
261
262		/**
263		* get alignment displayed in alf as format
264		*
265		* @param alf
266		* @param format
267		* @return
268		*/
269		public abstract String getAlignmentFrom(AlignFrame alf, String format);
270
271		/**
272		* get alignment as format with jalview start-end sequence suffix appended
273		*
274		* @param format
275		* @param suffix
276		* @return
277		*/
278		public abstract String getAlignment(String format, String suffix);
279
280		/**
281		* get alignment displayed in alf as format with or without the jalview
282		* start-end sequence suffix appended
283		*
284		* @param alf
285		* @param format
286		* @param suffix
287		* @return
288		*/
289		public abstract String getAlignmentFrom(AlignFrame alf, String format,
290		String suffix);
291
292		/**
293		* add the given features or annotation to the current alignment
294		*
295		* @param annotation
296		*/
297		public abstract void loadAnnotation(String annotation);
298
299		/**
300		* add the given features or annotation to the given alignment view
301		*
302		* @param alf
303		* @param annotation
304		*/
305		public abstract void loadAnnotationFrom(AlignFrame alf,
306		String annotation);
307
308		/**
309		* parse the given string as a jalview feature or GFF annotation file and
310		* optionally enable feature display on the current alignFrame
311		*
312		* @param features
313		* - gff or features file
314		* @param autoenabledisplay
315		* - when true, feature display will be enabled if any features can
316		* be parsed from the string.
317		*/
318		public abstract void loadFeatures(String features,
319		boolean autoenabledisplay);
320
321		/**
322		* parse the given string as a jalview feature or GFF annotation file and
323		* optionally enable feature display on the given alignFrame.
324		*
325		* @param alf
326		* @param features
327		* - gff or features file
328		* @param autoenabledisplay
329		* - when true, feature display will be enabled if any features can
330		* be parsed from the string.
331		* @return true if data parsed as features
332		*/
333		public abstract boolean loadFeaturesFrom(AlignFrame alf, String features,
334		boolean autoenabledisplay);
335
336		/**
337		* get the sequence features in the given format (Jalview or GFF)
338		*
339		* @param format
340		* @return
341		*/
342		public abstract String getFeatures(String format);
343
344		/**
345		* get the sequence features in alf in the given format (Jalview or GFF)
346		*
347		* @param alf
348		* @param format
349		* @return
350		*/
351		public abstract String getFeaturesFrom(AlignFrame alf, String format);
352
353		/**
354		* get current alignment's annotation as an annotation file
355		*
356		* @return
357		*/
358		public abstract String getAnnotation();
359
360		/**
361		* get alignment view alf's annotation as an annotation file
362		*
363		* @param alf
364		* @return
365		*/
366		public abstract String getAnnotationFrom(AlignFrame alf);
367
368		/**
369		* create a new view and return the alignFrame instance
370		*
371		* @return
372		*/
373		public abstract AlignFrame newView();
374
375		/**
376		* create a new view named name and return the alignFrame instance
377		*
378		* @param name
379		* @return
380		*/
381		public abstract AlignFrame newView(String name);
382
383		/**
384		* create a new view on alf and return the alignFrame instance
385		*
386		* @param alf
387		* @return
388		*/
389		public abstract AlignFrame newViewFrom(AlignFrame alf);
390
391		/**
392		* create a new view named name on alf
393		*
394		* @param alf
395		* @param name
396		* @return
397		*/
398		public abstract AlignFrame newViewFrom(AlignFrame alf, String name);
399
400		/**
401		*
402		* @param text
403		* alignment file as a string
404		* @param title
405		* window title
406		* @return null or new alignment frame
407		*/
408		public abstract AlignFrame loadAlignment(String text, String title);
409
410		/**
411		* register a javascript function to handle any alignment mouseover events
412		*
413		* @param listener
414		* name of javascript function (called with arguments
415		* [jalview.appletgui.AlignFrame,String(sequence id),String(column in
416		* alignment), String(position in sequence)]
417		*/
418		public abstract void setMouseoverListener(String listener);
419
420		/**
421		* register a javascript function to handle mouseover events
422		*
423		* @param af
424		* (null or specific alignframe for which events are to be listened
425		* for)
426		* @param listener
427		* name of javascript function
428		*/
429		public abstract void setMouseoverListener(AlignFrame af, String listener);
430
431		/**
432		* register a javascript function to handle any alignment selection events.
433		* Events are generated when the user completes a selection event, or when the
434		* user deselects all selected regions.
435		*
436		* @param listener
437		* name of javascript function (called with arguments
438		* [jalview.appletgui.AlignFrame, String(sequence set id),
439		* String(separator separated list of sequences which were selected),
440		* String(separator separated list of column ranges (i.e. single
441		* number or hyphenated range) that were selected)]
442		*/
443		public abstract void setSelectionListener(String listener);
444
445		public abstract void setSelectionListener(AlignFrame af, String listener);
446
447		/**
448		* register a javascript function to handle events normally routed to a Jmol
449		* structure viewer.
450		*
451		* @param listener
452		* - javascript function (arguments are variable, see
453		* jalview.javascript.MouseOverStructureListener for full details)
454		* @param modelSet
455		* - separator separated list of PDB file URIs that this viewer is
456		* handling. These files must be in the same order they appear in
457		* Jmol (e.g. first one is frame 1, second is frame 2, etc).
458		* @see jalview.javascript.MouseOverStructureListener
459		*/
460		public abstract void setStructureListener(String listener,
461		String modelSet);
462
463		/**
464		* remove any callback using the given listener function and associated with
465		* the given alignFrame (or null for all callbacks)
466		*
467		* @param af
468		* (may be null)
469		* @param listener
470		* (may be null)
471		*/
472		public abstract void removeJavascriptListener(AlignFrame af,
473		String listener);
474
475		/**
476		* send a mouseover message to all the alignment windows associated with the
477		* given residue in the pdbfile
478		*
479		* @param pdbResNum
480		* @param chain
481		* @param pdbfile
482		*/
483		public abstract void mouseOverStructure(String pdbResNum, String chain,
484		String pdbfile);
485
486		/**
487		* bind a pdb file to a sequence in the given alignFrame.
488		*
489		* @param alFrame
490		* - null or specific alignFrame. This specifies the dataset that
491		* will be searched for a seuqence called sequenceId
492		* @param sequenceId
493		* - sequenceId within the dataset.
494		* @param pdbEntryString
495		* - the short name for the PDB file
496		* @param pdbFile
497		* - pdb file - either a URL or a valid PDB file.
498		* @return true if binding was as success TODO: consider making an exception
499		* structure for indicating when PDB parsing or sequenceId location
500		* fails.
501		*/
502		public abstract boolean addPdbFile(AlignFrame alFrame, String sequenceId,
503		String pdbEntryString, String pdbFile);
504
505		/**
506		* adjust horizontal/vertical scroll to make the given location the top left
507		* hand corner for the given view
508		*
509		* @param alf
510		* @param topRow
511		* @param leftHandColumn
512		*/
513		public abstract void scrollViewToIn(AlignFrame alf, String topRow,
514		String leftHandColumn);
515
516		/**
517		* adjust vertical scroll to make the given row the top one for given view
518		*
519		* @param alf
520		* @param topRow
521		*/
522		public abstract void scrollViewToRowIn(AlignFrame alf, String topRow);
523
524		/**
525		* adjust horizontal scroll to make the given column the left one in the given
526		* view
527		*
528		* @param alf
529		* @param leftHandColumn
530		*/
531		public abstract void scrollViewToColumnIn(AlignFrame alf,
532		String leftHandColumn);
533
534		/**
535		*
536		* @return
537		* @see jalview.appletgui.AlignFrame#getFeatureGroups()
538		*/
539		public abstract String getFeatureGroups();
540
541		/**
542		* @param alf
543		* alignframe to get feature groups on
544		* @return
545		* @see jalview.appletgui.AlignFrame#getFeatureGroups()
546		*/
547		public abstract String getFeatureGroupsOn(AlignFrame alf);
548
549		/**
550		* @param visible
551		* @return
552		* @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
553		*/
554		public abstract String getFeatureGroupsOfState(boolean visible);
555
556		/**
557		* @param alf
558		* align frame to get groups of state visible
559		* @param visible
560		* @return
561		* @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
562		*/
563		public abstract String getFeatureGroupsOfStateOn(AlignFrame alf,
564		boolean visible);
565
566		/**
567		* @param groups
568		* tab separated list of group names
569		* @param state
570		* true or false
571		* @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
572		* boolean)
573		*/
574		public abstract void setFeatureGroupStateOn(AlignFrame alf, String groups,
575		boolean state);
576
577		public abstract void setFeatureGroupState(String groups, boolean state);
578
579		/**
580		* List separator string
581		*
582		* @return the separator
583		*/
584		public abstract String getSeparator();
585
586		/**
587		* List separator string
588		*
589		* @param separator
590		* the separator to set. empty string will reset separator to default
591		*/
592		public abstract void setSeparator(String separator);
593
594		/**
595		* Retrieve fragments of a large packet of data made available by JalviewLite.
596		*
597		* @param messageclass
598		* @param viewId
599		* @return next chunk of message
600		*/
601		public abstract String getJsMessage(String messageclass, String viewId);
602
603		}