examples-jbake/content/jalviewLiteJs.html

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