JAL-629 Method to use for printStackTrace
[jalview.git] / examples / jalviewLiteJs.html
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 of the License, or (at your option) any later version.
10  *  
11  * Jalview is distributed in the hope that it will be useful, but 
12  * WITHOUT ANY WARRANTY; without even the implied warranty 
13  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
14  * PURPOSE.  See the GNU General Public License for more details.
15  * 
16  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
17  * The Jalview Authors are detailed in the 'AUTHORS' file.
18 -->
19
20
21
22 <div id="view_decorated" name="view_decorated"  style="margin:8px; padding:10px; border: 2px solid red; text-align:center; display:none;"><b>Click <a href="index.html#jalviewLiteJs"> here</a> to view decorated page</b></div>
23
24 <!-- content start -->
25 <p>The jalviewLite applet's application programming interface (API) includes two components. A <a href="javascript/jalview.js">JalviewLite Javascript Library</a> and the <a href="#api">public methods on the JalviewLite applet</a>.
26 </p>
27                 <h3>Notes</h3>
28                 <ul>
29                 <li>Unfortunately Javascript - Java communication is not possible
30                 using Internet Explorer or Opera on Macs. Please use Safari or
31                 Firefox.</li>
32                 <li>If more than one Jalview window is open, Jalview returns the
33                 alignment in the active window, unless you provide an AlignFrame
34                 object reference.</li>
35                 <li>The alignment output format can be either Fasta, PFAM, Clustal,
36                 MSF, PIR, or BLC.</li>
37                 <li>When referring to the Jalview applet in javascript, you must
38                 either give Jalview a name in the applet tag or use the document.applets index.</li>
39                 <li>When creating javascript functions that are called by jalviewLite (e.g. the <em>oninit</em> parameter, or any mouseOver, selection or structureListener handlers), ensure they complete very quickly, and do not access any jalview API methods that might result in more javascript calls (this which will cause your browser to hang). If you need to do this, we suggest that jalviewLite callbacks are used to add new javascript events to a queue (e.g. using a Jquery timer callback) to avoid any concurrency issues.
40                 </li>
41                 </ul>
42                 <a name="api">
43                 <h1>JalviewLite's Javascript API</h1></a>
44                 <p>The following public methods on the jalviewLite applet are available to be called from javascript:</p>
45                 <pre>//get list of IDs of selected sequences
46 public String getSelectedSequences()
47
48 // list of IDs of selected sequences terminated by sep or, if sep is null, '&#172;' (&amp;#172;)
49 public String getSelectedSequences(sep)
50
51 // get list of selected sequences from specific alignFrame. (2.7)
52 public String getSelectedSequencesFrom(AlignFrame alf)
53 public String getSelectedSequencesFrom(AlignFrame alf, String sep)
54
55 // highlight a position in a specific sequence or a column in an alignment containing it
56 // provide ID sequence to highlight, integer (range highlighting will be supported in future versions)
57 // and flag indicating if position is an alignment column or given according to sequence numbering (2.7)
58 public void highlight(String sequenceId, String position, String alignedPosition)
59 public void highlightIn(AlignFrame alf, String sequenceId, String position, String alignedPosition)
60
61
62 // select regions of the currrent alignment frame using a list of sequence ids and a list of 
63 // column numbers and ranges (with minus sign indicating start-end) (separated by default separator) (2.7) 
64 public void select(String sequenceIds, String columns)
65 public void select(String sequenceIds, String columns, String sep)
66 public void selectIn(AlignFrame alf, String sequenceIds, String columns)
67 public void selectIn(AlignFrame alf, String sequenceIds, String columns, String sep)
68
69
70 // get selected sequences as alignment as format with or without start-end suffix
71 public String getSelectedSequencesAsAlignment(String format, boolean suffix)
72
73 // get selected sequences as alignment from given view as format with or without start-end suffix
74 public String getSelectedSequencesAsAlignmentFrom(AlignFrame alf, String format, boolean suffix)
75
76 // get a separator separated list of sequence IDs reflecting the order of the current alignment (2.7)
77 public String getAlignmentOrder();
78 public String getAlignmentOrderFrom(AlignFrame alf);
79 public String getAlignmentOrderFrom(AlignFrame alf, String sep);
80
81 // re-order the current alignment using the given list of sequence IDs separated by sep
82 // undoName - is string to use when referring to ordering action in undo buffer
83 // returns 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
84 // (v2.7)
85 public String orderBy(String order, String undoName)
86 public String orderBy(String order, String undoName, String sep)
87 String orderAlignmentBy(AlignFrame alf, String order, String undoName, String sep)
88
89
90 // get alignment as format
91 public String getAlignment(String format)
92
93 // get alignment as format with jalview 
94 // start-end sequence suffix appended
95 public String getAlignment(String format, String suffix)
96
97 // get alignment displayed in alf as format
98 public String getAlignmentFrom(AlignFrame alf, String format)
99
100 // get alignment displayed in alf as format 
101 // with jalview start-end sequence suffix appended
102 public String getAlignmentFrom(AlignFrame alf, String format, String suffix)
103
104 // add the given features or annotation to the current alignment
105 // if features are loaded, feature display is automatically enabled
106 public void loadAnnotation(String annotation)
107
108 // add the given features or annotation to the given alignment view
109 // if features are loaded, feature display is automatically enabled
110 public void loadAnnotationFrom(AlignFrame alf, String annotation)
111
112 // parse the given string as a jalview or GFF features file and optionally enable feature display on the current alignment
113 // (v2.8)
114 public abstract void loadFeatures(String features, boolean autoenabledisplay)
115
116 // parse the given string as a jalview or GFF features file and optionally enable feature display on the given alignment
117 // (v2.8)
118 public abstract void loadFeaturesFrom(AlignFrame alf, String features, boolean autoenabledisplay)
119
120 // get the sequence features in the given format (Jalview or GFF)
121 public String getFeatures(String format)
122
123 // get the sequence features in alf in the given format (Jalview or GFF)
124 public String getFeaturesFrom(AlignFrame alf, String format)
125
126 // get current alignment's annotation as an annotation file
127 public String getAnnotation()
128
129 // get alignment view alf's annotation as an annotation file
130 public String getAnnotationFrom(AlignFrame alf)
131
132 // create a new view and return the alignFrame instance
133 public AlignFrame newView()
134
135 // create a new view named name and return the alignFrame instance
136 public AlignFrame newView(String name)
137
138 // create a new view on alf and return the alignFrame instance
139 public AlignFrame newViewFrom(AlignFrame alf)
140
141 // create a new view named name on alf 
142 // and return the alignFrame instance
143 public AlignFrame newViewFrom(AlignFrame alf, String name)
144
145 // load a new alignment 
146 // remember to store the AlignFrame object reference 
147 // if you want to manipulate the new alignment view.
148 public AlignFrame loadAlignment(String text, String title)
149
150
151 // register a javascript function to handle any alignment mouseover events
152 // listener is name of javascript function  which will be called
153 // with arguments [jalview.appletgui.AlignFrame,String(sequence id),
154 // String(column in alignment), String(position in sequence)]
155 // (v2.7)
156 public void setMouseoverListener(String listener)
157
158 // register a javascript function to handle mouseover events for specific alignframe
159 // (v2.7)
160 public void setMouseoverListener(AlignFrame af, String listener)
161
162 // register a javascript function to handle alignment selection events. 
163 // Events are generated when the user completes a selection event, or when
164 // the user deselects all selected regions.
165 // listener is name of javascript function  that will be called with arguments
166 //  [jalview.appletgui.AlignFrame, String(sequence set id), 
167 //   String(separator separated list of sequences which were selected), 
168 //   String(separator separated list of column ranges)]
169 // (v2.7)
170 public void setSelectionListener(String listener)
171
172 // register a selection listener for a specific alignment frame
173 // (v2.7)
174 public void setSelectionListener(AlignFrame af, String listener)
175
176 // register a javascript function to handle events normally routed 
177 // to a Jmol structure viewer.
178 // listener is a javascript function called with several different types 
179 // of arguments, dependent on the type of structure callback event. 
180 // See jalview.javascript.MouseOverStructureListener for full details or
181 // the embedded Jmol example.
182 // modelSet - is a separator separated list of PDB file URIs that this viewer is handling (where position in list equals model number in Jmol).
183 // (v2.7)
184 public void setStructureListener(String listener, String modelSet)
185
186 // remove any callback using the given listener function and associated with
187 // the given alignFrame (or null for all callbacks) (v2.7)
188 public void removeJavascriptListener(AlignFrame af, String listener)
189
190 // send a mouseover message to all the alignment windows associated with the
191 // given residue in the pdbfile (v2.7)
192 public void mouseOverStructure(String pdbResNum, String chain, String pdbfile)
193
194 // bind a pdb file to a sequence in the given alignFrame - this will be searched
195 // for sequences matching sequenceId. The PDB file in pdbFile is either the contents
196 // of a PDB file or a URI that can be used to retrieve the file, and the pdbEntryString
197 // is the user friendly name (or PDBID) shown in jalview's user interface.
198 // returns true if binding was as success (v2.7)
199 public boolean addPdbFile(AlignFrame alFrame, 
200     String sequenceId, String pdbEntryString, String pdbFile)
201
202 // adjust horizontal/vertical scroll in alf to the make 
203 // the given location the top left hand corner for given current view (v2.7)
204 public void scrollViewToIn(AlignFrame alf, String topRow, String leftHandColumn)
205
206 // adjust horizontal scroll in alf to the make 
207 // the given location the left hand corner for given current view (v2.7)
208 public void scrollViewToColumnIn(AlignFrame alf, String leftHandColumn)
209
210 // adjust horizontal/vertical scroll in alf to the make 
211 // the given location the top row for given current view (v2.7)
212 public void scrollViewToRowIn(AlignFrame alf, String topRow)
213
214
215 // return separator separated list of feature groups 
216 // on the current alignment
217 public String getFeatureGroups()
218
219 // return separator separated list of feature groups on alf
220 public String getFeatureGroupsOn(AlignFrame alf)
221
222 // return separator separated list of feature groups 
223 // either visible or hidden
224 public String getFeatureGroupsOfState(boolean state)
225
226 // return separator separated list of feature groups 
227 // either visible or hidden on alf
228 public String getFeatureGroupsOfStateOn(AlignFrame alf, boolean state)
229
230 // set the separator separated list of feature groups as 
231 // visible or hidden on the current alignment
232 public void setFeatureGroupState(String groupList, boolean state)
233
234 // set the separator separated list of feature groups 
235 // as visible or hidden on alf
236 public void setFeatureGroupStateOn(AlignFrame alf, String groupList, boolean state)
237
238 // helper functions
239
240 // Asynchronously retrieve next chunk of a large packet of data made available 
241 // for a JalviewLite event handler, or the empty string if no more data is available.
242 // messageclass and viewId are keys used to retrieve a specific message related
243 // to an event.  
244 // Use this in a javascript timer or GUI update thread to retrieve data without 
245 // blocking the JalviewLite applet. DO NOT USE IN THE CALLBACK THAT HANDLED THE EVENT
246 // (v2.7)
247 public String getJsMessage(String messageclass, String viewId)
248
249
250 // convert list to a separator separated array
251 public String arrayToSeparatorList(String[] list) 
252
253 // get a string array from a list
254 public String[] separatorListToArray(String list)
255
256 // get the current separator
257 public String getSeparator()
258
259 // set the current separator
260 public void setSeparator(String)
261
262 //// JalviewLite global state methods and fields
263
264 // return the build date as a string
265 public static String getBuildDate() 
266
267 // return the JalviewLite version as a string
268 public static String getVersion()
269
270 // debug flag - controls output to standard out
271 public static boolean debug
272
273 </pre>
274 <!-- content end -->