src/jalview/gui/StructureViewerBase.java

   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.gui;
  22
  23 import java.awt.Color;
  24 import java.awt.Component;
  25 import java.awt.event.ActionEvent;
  26 import java.awt.event.ActionListener;
  27 import java.awt.event.ItemEvent;
  28 import java.awt.event.ItemListener;
  29 import java.io.BufferedReader;
  30 import java.io.File;
  31 import java.io.FileOutputStream;
  32 import java.io.FileReader;
  33 import java.io.IOException;
  34 import java.io.PrintWriter;
  35 import java.util.ArrayList;
  36 import java.util.List;
  37 import java.util.Random;
  38 import java.util.Vector;
  39
  40 import javax.swing.ButtonGroup;
  41 import javax.swing.JCheckBoxMenuItem;
  42 import javax.swing.JMenu;
  43 import javax.swing.JMenuItem;
  44 import javax.swing.JRadioButtonMenuItem;
  45 import javax.swing.event.MenuEvent;
  46 import javax.swing.event.MenuListener;
  47
  48 import jalview.api.AlignmentViewPanel;
  49 import jalview.bin.Cache;
  50 import jalview.datamodel.AlignmentI;
  51 import jalview.datamodel.PDBEntry;
  52 import jalview.datamodel.SequenceI;
  53 import jalview.gui.JalviewColourChooser.ColourChooserListener;
  54 import jalview.gui.StructureViewer.ViewerType;
  55 import jalview.gui.ViewSelectionMenu.ViewSetProvider;
  56 import jalview.io.DataSourceType;
  57 import jalview.io.JalviewFileChooser;
  58 import jalview.io.JalviewFileView;
  59 import jalview.jbgui.GStructureViewer;
  60 import jalview.schemes.ColourSchemeI;
  61 import jalview.schemes.ColourSchemes;
  62 import jalview.structure.StructureMapping;
  63 import jalview.structures.models.AAStructureBindingModel;
  64 import jalview.util.BrowserLauncher;
  65 import jalview.util.MessageManager;
  66 import jalview.ws.dbsources.EBIAlfaFold;
  67 import jalview.ws.dbsources.Pdb;
  68 import jalview.ws.utils.UrlDownloadClient;
  69
  70 /**
  71  * Base class with common functionality for JMol, Chimera or other structure
  72  * viewers.
  73  *
  74  * @author gmcarstairs
  75  *
  76  */
  77 public abstract class StructureViewerBase extends GStructureViewer
  78         implements Runnable, ViewSetProvider
  79 {
  80   /*
  81    * names for colour options (additional to Jalview colour schemes)
  82    */
  83   enum ViewerColour
  84   {
  85     BySequence, ByChain, ChargeCysteine, ByViewer
  86   }
  87
  88   /**
  89    * list of sequenceSet ids associated with the view
  90    */
  91   protected List<String> _aps = new ArrayList<>();
  92
  93   /**
  94    * list of alignment panels to use for superposition
  95    */
  96   protected Vector<AlignmentViewPanel> _alignwith = new Vector<>();
  97
  98   /**
  99    * list of alignment panels that are used for colouring structures by aligned
 100    * sequences
 101    */
 102   protected Vector<AlignmentViewPanel> _colourwith = new Vector<>();
 103
 104   private String viewId = null;
 105
 106   private AlignmentPanel ap;
 107
 108   protected boolean alignAddedStructures = false;
 109
 110   protected volatile boolean _started = false;
 111
 112   protected volatile boolean addingStructures = false;
 113
 114   protected Thread worker = null;
 115
 116   protected boolean allChainsSelected = false;
 117
 118   protected JMenu viewSelectionMenu;
 119
 120   /**
 121    * set after sequence colouring has been applied for this structure viewer.
 122    * used to determine if the final sequence/structure mapping has been
 123    * determined
 124    */
 125   protected volatile boolean seqColoursApplied = false;
 126
 127   private IProgressIndicator progressBar = null;
 128
 129   private Random random = new Random();
 130
 131   /**
 132    * Default constructor
 133    */
 134   public StructureViewerBase()
 135   {
 136     super();
 137   }
 138
 139   /**
 140    * @return true if added structures should be aligned to existing one(s)
 141    */
 142   @Override
 143   public boolean isAlignAddedStructures()
 144   {
 145     return alignAddedStructures;
 146   }
 147
 148   /**
 149    *
 150    * @param true
 151    *          if added structures should be aligned to existing one(s)
 152    */
 153   @Override
 154   public void setAlignAddedStructures(boolean alignAdded)
 155   {
 156     alignAddedStructures = alignAdded;
 157   }
 158
 159   /**
 160    * called by the binding model to indicate when adding structures is happening or has been completed
 161    * @param addingStructures
 162    */
 163   public synchronized void setAddingStructures(boolean addingStructures)
 164   {
 165     this.addingStructures = addingStructures;
 166   }
 167
 168   /**
 169    *
 170    * @param ap2
 171    * @return true if this Jmol instance is linked with the given alignPanel
 172    */
 173   public boolean isLinkedWith(AlignmentPanel ap2)
 174   {
 175     return _aps.contains(ap2.av.getSequenceSetId());
 176   }
 177
 178   public boolean isUsedforaligment(AlignmentViewPanel ap2)
 179   {
 180
 181     return (_alignwith != null) && _alignwith.contains(ap2);
 182   }
 183
 184   @Override
 185   public boolean isUsedForColourBy(AlignmentViewPanel ap2)
 186   {
 187     return (_colourwith != null) && _colourwith.contains(ap2);
 188   }
 189
 190   /**
 191    *
 192    * @return TRUE if the view is NOT being coloured by the alignment colours.
 193    */
 194   public boolean isColouredByViewer()
 195   {
 196     return !getBinding().isColourBySequence();
 197   }
 198
 199   public String getViewId()
 200   {
 201     if (viewId == null)
 202     {
 203       viewId = System.currentTimeMillis() + "." + this.hashCode();
 204     }
 205     return viewId;
 206   }
 207
 208   protected void setViewId(String viewId)
 209   {
 210     this.viewId = viewId;
 211   }
 212
 213   protected void buildActionMenu()
 214   {
 215     if (_alignwith == null)
 216     {
 217       _alignwith = new Vector<>();
 218     }
 219     if (_alignwith.size() == 0 && ap != null)
 220     {
 221       _alignwith.add(ap);
 222     }
 223     ;
 224     // TODO: refactor to allow concrete classes to register buttons for adding
 225     // here
 226     // currently have to override to add buttons back in after they are cleared
 227     // in this loop
 228     for (Component c : viewerActionMenu.getMenuComponents())
 229     {
 230       if (c != alignStructs)
 231       {
 232         viewerActionMenu.remove((JMenuItem) c);
 233       }
 234     }
 235   }
 236
 237   @Override
 238   public AlignmentPanel getAlignmentPanel()
 239   {
 240     return ap;
 241   }
 242
 243   protected void setAlignmentPanel(AlignmentPanel alp)
 244   {
 245     this.ap = alp;
 246   }
 247
 248   @Override
 249   public AlignmentPanel[] getAllAlignmentPanels()
 250   {
 251     AlignmentPanel[] t, list = new AlignmentPanel[0];
 252     for (String setid : _aps)
 253     {
 254       AlignmentPanel[] panels = PaintRefresher.getAssociatedPanels(setid);
 255       if (panels != null)
 256       {
 257         t = new AlignmentPanel[list.length + panels.length];
 258         System.arraycopy(list, 0, t, 0, list.length);
 259         System.arraycopy(panels, 0, t, list.length, panels.length);
 260         list = t;
 261       }
 262     }
 263
 264     return list;
 265   }
 266
 267   /**
 268    * set the primary alignmentPanel reference and add another alignPanel to the
 269    * list of ones to use for colouring and aligning
 270    *
 271    * @param nap
 272    */
 273   public void addAlignmentPanel(AlignmentPanel nap)
 274   {
 275     if (getAlignmentPanel() == null)
 276     {
 277       setAlignmentPanel(nap);
 278     }
 279     if (!_aps.contains(nap.av.getSequenceSetId()))
 280     {
 281       _aps.add(nap.av.getSequenceSetId());
 282     }
 283   }
 284
 285   /**
 286    * remove any references held to the given alignment panel
 287    *
 288    * @param nap
 289    */
 290   @Override
 291   public void removeAlignmentPanel(AlignmentViewPanel nap)
 292   {
 293     try
 294     {
 295       _alignwith.remove(nap);
 296       _colourwith.remove(nap);
 297       if (getAlignmentPanel() == nap)
 298       {
 299         setAlignmentPanel(null);
 300         for (AlignmentPanel aps : getAllAlignmentPanels())
 301         {
 302           if (aps != nap)
 303           {
 304             setAlignmentPanel(aps);
 305             break;
 306           }
 307         }
 308       }
 309     } catch (Exception ex)
 310     {
 311     }
 312     if (getAlignmentPanel() != null)
 313     {
 314       buildActionMenu();
 315     }
 316   }
 317
 318   public void useAlignmentPanelForSuperposition(AlignmentPanel nap)
 319   {
 320     addAlignmentPanel(nap);
 321     if (!_alignwith.contains(nap))
 322     {
 323       _alignwith.add(nap);
 324     }
 325   }
 326
 327   public void excludeAlignmentPanelForSuperposition(AlignmentPanel nap)
 328   {
 329     if (_alignwith.contains(nap))
 330     {
 331       _alignwith.remove(nap);
 332     }
 333   }
 334
 335   public void useAlignmentPanelForColourbyseq(AlignmentPanel nap,
 336           boolean enableColourBySeq)
 337   {
 338     useAlignmentPanelForColourbyseq(nap);
 339     getBinding().setColourBySequence(enableColourBySeq);
 340     seqColour.setSelected(enableColourBySeq);
 341     viewerColour.setSelected(!enableColourBySeq);
 342   }
 343
 344   public void useAlignmentPanelForColourbyseq(AlignmentPanel nap)
 345   {
 346     addAlignmentPanel(nap);
 347     if (!_colourwith.contains(nap))
 348     {
 349       _colourwith.add(nap);
 350     }
 351   }
 352
 353   public void excludeAlignmentPanelForColourbyseq(AlignmentPanel nap)
 354   {
 355     if (_colourwith.contains(nap))
 356     {
 357       _colourwith.remove(nap);
 358     }
 359   }
 360
 361   public abstract ViewerType getViewerType();
 362
 363   /**
 364    * add a new structure (with associated sequences and chains) to this viewer,
 365    * retrieving it if necessary first.
 366    *
 367    * @param pdbentry
 368    * @param seqs
 369    * @param chains
 370    * @param align
 371    *          if true, new structure(s) will be aligned using associated
 372    *          alignment
 373    * @param alignFrame
 374    */
 375   protected void addStructure(final PDBEntry pdbentry,
 376           final SequenceI[] seqs, final String[] chains,
 377           final IProgressIndicator alignFrame)
 378   {
 379     if (pdbentry.getFile() == null)
 380     {
 381       if (worker != null && worker.isAlive())
 382       {
 383         // a retrieval is in progress, wait around and add ourselves to the
 384         // queue.
 385         new Thread(new Runnable()
 386         {
 387           @Override
 388           public void run()
 389           {
 390             while (worker != null && worker.isAlive() && _started)
 391             {
 392               try
 393               {
 394                 Thread.sleep(100 + ((int) Math.random() * 100));
 395
 396               } catch (Exception e)
 397               {
 398               }
 399             }
 400             // and call ourselves again.
 401             addStructure(pdbentry, seqs, chains, alignFrame);
 402           }
 403         }).start();
 404         return;
 405       }
 406     }
 407     // otherwise, start adding the structure.
 408     getBinding().addSequenceAndChain(new PDBEntry[] { pdbentry },
 409             new SequenceI[][]
 410             { seqs }, new String[][] { chains });
 411     addingStructures = true;
 412     _started = false;
 413     worker = new Thread(this);
 414     worker.start();
 415     return;
 416   }
 417
 418   protected boolean hasPdbId(String pdbId)
 419   {
 420     return getBinding().hasPdbId(pdbId);
 421   }
 422
 423   /**
 424    * Returns a list of any viewer of the instantiated type. The list is
 425    * restricted to those linked to the given alignment panel if it is not null.
 426    */
 427   protected List<StructureViewerBase> getViewersFor(AlignmentPanel alp)
 428   {
 429     return Desktop.getInstance().getStructureViewers(alp, this.getClass());
 430   }
 431
 432   @Override
 433   public void addToExistingViewer(PDBEntry pdbentry, SequenceI[] seq,
 434           String[] chains, final AlignmentViewPanel apanel, String pdbId)
 435   {
 436     /*
 437      * JAL-1742 exclude view with this structure already mapped (don't offer
 438      * to align chain B to chain A of the same structure); code may defend
 439      * against this possibility before we reach here
 440      */
 441     if (hasPdbId(pdbId))
 442     {
 443       return;
 444     }
 445     AlignmentPanel alignPanel = (AlignmentPanel) apanel; // Implementation error if this
 446                                                  // cast fails
 447     useAlignmentPanelForSuperposition(alignPanel);
 448     addStructure(pdbentry, seq, chains, alignPanel.alignFrame);
 449   }
 450
 451   /**
 452    * Adds mappings for the given sequences to an already opened PDB structure,
 453    * and updates any viewers that have the PDB file
 454    *
 455    * @param seq
 456    * @param chains
 457    * @param apanel
 458    * @param pdbFilename
 459    */
 460   public void addSequenceMappingsToStructure(SequenceI[] seq,
 461           String[] chains, final AlignmentViewPanel alpanel,
 462           String pdbFilename)
 463   {
 464     AlignmentPanel apanel = (AlignmentPanel) alpanel;
 465
 466     // TODO : Fix multiple seq to one chain issue here.
 467     /*
 468      * create the mappings
 469      */
 470     apanel.getStructureSelectionManager().setMapping(seq, chains,
 471             pdbFilename, DataSourceType.FILE, getProgressIndicator());
 472
 473     /*
 474      * alert the FeatureRenderer to show new (PDB RESNUM) features
 475      */
 476     if (apanel.getSeqPanel().seqCanvas.fr != null)
 477     {
 478       apanel.getSeqPanel().seqCanvas.fr.featuresAdded();
 479       // note - we don't do a refresh for structure here because we do it
 480       // explicitly for all panels later on
 481       apanel.paintAlignment(true, false);
 482     }
 483
 484     /*
 485      * add the sequences to any other viewers (of the same type) for this pdb
 486      * file
 487      */
 488     // JBPNOTE: this looks like a binding routine, rather than a gui routine
 489     for (StructureViewerBase viewer : getViewersFor(null))
 490     {
 491       AAStructureBindingModel bindingModel = viewer.getBinding();
 492       for (int pe = 0; pe < bindingModel.getPdbCount(); pe++)
 493       {
 494         if (bindingModel.getPdbEntry(pe).getFile().equals(pdbFilename))
 495         {
 496           bindingModel.addSequence(pe, seq);
 497           viewer.addAlignmentPanel(apanel);
 498           /*
 499            * add it to the set of alignments used for colouring structure by
 500            * sequence
 501            */
 502           viewer.useAlignmentPanelForColourbyseq(apanel);
 503           viewer.buildActionMenu();
 504           apanel.getStructureSelectionManager()
 505                   .sequenceColoursChanged(apanel);
 506           break;
 507         }
 508       }
 509     }
 510   }
 511
 512   @Override
 513   public boolean addAlreadyLoadedFile(SequenceI[] seq, String[] chains,
 514           final AlignmentViewPanel apanel, String pdbId)
 515   {
 516     String alreadyMapped = apanel.getStructureSelectionManager()
 517             .alreadyMappedToFile(pdbId);
 518
 519     if (alreadyMapped == null)
 520     {
 521       return false;
 522     }
 523
 524     addSequenceMappingsToStructure(seq, chains, apanel, alreadyMapped);
 525     return true;
 526   }
 527
 528   void setChainMenuItems(List<String> chainNames)
 529   {
 530     chainMenu.removeAll();
 531     if (chainNames == null || chainNames.isEmpty())
 532     {
 533       return;
 534     }
 535     JMenuItem menuItem = new JMenuItem(
 536             MessageManager.getString("label.all"));
 537     menuItem.addActionListener(new ActionListener()
 538     {
 539       @Override
 540       public void actionPerformed(ActionEvent evt)
 541       {
 542         allChainsSelected = true;
 543         for (int i = 0; i < chainMenu.getItemCount(); i++)
 544         {
 545           if (chainMenu.getItem(i) instanceof JCheckBoxMenuItem)
 546           {
 547             ((JCheckBoxMenuItem) chainMenu.getItem(i)).setSelected(true);
 548           }
 549         }
 550         showSelectedChains();
 551         allChainsSelected = false;
 552       }
 553     });
 554
 555     chainMenu.add(menuItem);
 556
 557     for (String chain : chainNames)
 558     {
 559       menuItem = new JCheckBoxMenuItem(chain, true);
 560       menuItem.addItemListener(new ItemListener()
 561       {
 562         @Override
 563         public void itemStateChanged(ItemEvent evt)
 564         {
 565           if (!allChainsSelected)
 566           {
 567             showSelectedChains();
 568           }
 569         }
 570       });
 571
 572       chainMenu.add(menuItem);
 573     }
 574   }
 575
 576   /**
 577    * Action on selecting one of Jalview's registered colour schemes
 578    */
 579   @Override
 580   public void changeColour_actionPerformed(String colourSchemeName)
 581   {
 582     AlignmentI al = getAlignmentPanel().av.getAlignment();
 583     ColourSchemeI cs = ColourSchemes.getInstance()
 584             .getColourScheme(colourSchemeName, getAlignmentPanel().av, al,
 585                     null);
 586     getBinding().colourByJalviewColourScheme(cs);
 587   }
 588
 589   /**
 590    * Builds the colour menu
 591    */
 592   protected void buildColourMenu()
 593   {
 594     colourMenu.removeAll();
 595     AlignmentI al = getAlignmentPanel().av.getAlignment();
 596
 597     /*
 598      * add colour by sequence, by chain, by charge and cysteine
 599      */
 600     colourMenu.add(seqColour);
 601     colourMenu.add(chainColour);
 602     colourMenu.add(chargeColour);
 603     chargeColour.setEnabled(!al.isNucleotide());
 604
 605     /*
 606      * add all 'simple' (per-residue) colour schemes registered to Jalview
 607      */
 608     ButtonGroup itemGroup = ColourMenuHelper.addMenuItems(colourMenu, this,
 609             al, true);
 610
 611     /*
 612      * add 'colour by viewer' (menu item text is set in subclasses)
 613      */
 614     viewerColour.setSelected(false);
 615     viewerColour.addActionListener(new ActionListener()
 616     {
 617       @Override
 618       public void actionPerformed(ActionEvent actionEvent)
 619       {
 620         viewerColour_actionPerformed();
 621       }
 622     });
 623     colourMenu.add(viewerColour);
 624
 625     /*
 626      * add 'set background colour'
 627      */
 628     JMenuItem backGround = new JMenuItem();
 629     backGround
 630             .setText(MessageManager.getString("action.background_colour"));
 631     backGround.addActionListener(new ActionListener()
 632     {
 633       @Override
 634       public void actionPerformed(ActionEvent actionEvent)
 635       {
 636         background_actionPerformed();
 637       }
 638     });
 639     colourMenu.add(backGround);
 640
 641     /*
 642      * add colour buttons to a group so their selection is
 643      * mutually exclusive (background colour is a separate option)
 644      */
 645     itemGroup.add(seqColour);
 646     itemGroup.add(chainColour);
 647     itemGroup.add(chargeColour);
 648     itemGroup.add(viewerColour);
 649   }
 650
 651   /**
 652    * Construct menu items
 653    */
 654   protected void initMenus()
 655   {
 656     AAStructureBindingModel binding = getBinding();
 657
 658     seqColour = new JRadioButtonMenuItem();
 659     seqColour.setText(MessageManager.getString("action.by_sequence"));
 660     seqColour.setName(ViewerColour.BySequence.name());
 661     seqColour.setSelected(binding.isColourBySequence());
 662     seqColour.addActionListener(new ActionListener()
 663     {
 664       @Override
 665       public void actionPerformed(ActionEvent actionEvent)
 666       {
 667         seqColour_actionPerformed();
 668       }
 669     });
 670
 671     chainColour = new JRadioButtonMenuItem();
 672     chainColour.setText(MessageManager.getString("action.by_chain"));
 673     chainColour.setName(ViewerColour.ByChain.name());
 674     chainColour.addActionListener(new ActionListener()
 675     {
 676       @Override
 677       public void actionPerformed(ActionEvent actionEvent)
 678       {
 679         chainColour_actionPerformed();
 680       }
 681     });
 682
 683     chargeColour = new JRadioButtonMenuItem();
 684     chargeColour.setText(MessageManager.getString("label.charge_cysteine"));
 685     chargeColour.setName(ViewerColour.ChargeCysteine.name());
 686     chargeColour.addActionListener(new ActionListener()
 687     {
 688       @Override
 689       public void actionPerformed(ActionEvent actionEvent)
 690       {
 691         chargeColour_actionPerformed();
 692       }
 693     });
 694
 695     viewerColour = new JRadioButtonMenuItem();
 696     viewerColour
 697             .setText(MessageManager.getString("label.colour_with_viewer"));
 698     viewerColour.setToolTipText(MessageManager
 699             .getString("label.let_viewer_manage_structure_colours"));
 700     viewerColour.setName(ViewerColour.ByViewer.name());
 701     viewerColour.setSelected(!binding.isColourBySequence());
 702
 703     if (_colourwith == null)
 704     {
 705       _colourwith = new Vector<>();
 706     }
 707     if (_alignwith == null)
 708     {
 709       _alignwith = new Vector<>();
 710     }
 711
 712     ViewSelectionMenu seqColourBy = new ViewSelectionMenu(
 713             MessageManager.getString("label.colour_by"), this, _colourwith,
 714             new ItemListener()
 715             {
 716               @Override
 717               public void itemStateChanged(ItemEvent e)
 718               {
 719                 if (!seqColour.isSelected())
 720                 {
 721                   seqColour.doClick();
 722                 }
 723                 else
 724                 {
 725                   // update the viewer display now.
 726                   seqColour_actionPerformed();
 727                 }
 728               }
 729             });
 730     viewMenu.add(seqColourBy);
 731
 732     final ItemListener handler = new ItemListener()
 733     {
 734       @Override
 735       public void itemStateChanged(ItemEvent e)
 736       {
 737         if (_alignwith.isEmpty())
 738         {
 739           alignStructs.setEnabled(false);
 740           alignStructs.setToolTipText(null);
 741         }
 742         else
 743         {
 744           alignStructs.setEnabled(true);
 745           alignStructs.setToolTipText(MessageManager.formatMessage(
 746                   "label.align_structures_using_linked_alignment_views",
 747                   _alignwith.size()));
 748         }
 749       }
 750     };
 751     viewSelectionMenu = new ViewSelectionMenu(
 752             MessageManager.getString("label.superpose_with"), this,
 753             _alignwith, handler);
 754     handler.itemStateChanged(null);
 755     viewerActionMenu.add(viewSelectionMenu, 0);
 756     viewerActionMenu.addMenuListener(new MenuListener()
 757     {
 758       @Override
 759       public void menuSelected(MenuEvent e)
 760       {
 761         handler.itemStateChanged(null);
 762       }
 763
 764       @Override
 765       public void menuDeselected(MenuEvent e)
 766       {
 767       }
 768
 769       @Override
 770       public void menuCanceled(MenuEvent e)
 771       {
 772       }
 773     });
 774
 775     viewerActionMenu.setText(getViewerName());
 776     helpItem.setText(MessageManager.formatMessage("label.viewer_help",
 777             getViewerName()));
 778
 779     buildColourMenu();
 780   }
 781
 782   /**
 783    * Sends commands to the structure viewer to superimpose structures based on
 784    * currently associated alignments. May optionally return an error message for
 785    * the operation.
 786    */
 787   @Override
 788   protected String alignStructsWithAllAlignPanels()
 789   {
 790     if (getAlignmentPanel() == null)
 791     {
 792       return null;
 793     }
 794
 795     if (_alignwith.size() == 0)
 796     {
 797       _alignwith.add(getAlignmentPanel());
 798     }
 799
 800     String reply = null;
 801     try
 802     {
 803       reply = getBinding().superposeStructures(_alignwith);
 804       if (reply != null && !reply.isEmpty())
 805       {
 806         String text = MessageManager
 807                 .formatMessage("error.superposition_failed", reply);
 808         statusBar.setText(text);
 809       }
 810     } catch (Exception e)
 811     {
 812       StringBuffer sp = new StringBuffer();
 813       for (AlignmentViewPanel alignPanel : _alignwith)
 814       {
 815         sp.append("'" + alignPanel.getViewName() + "' ");
 816       }
 817       Cache.log.info("Couldn't align structures with the " + sp.toString()
 818               + "associated alignment panels.", e);
 819     }
 820     return reply;
 821   }
 822
 823   /**
 824    * Opens a colour chooser dialog, and applies the chosen colour to the
 825    * background of the structure viewer
 826    */
 827   @Override
 828   public void background_actionPerformed()
 829   {
 830     String ttl = MessageManager.getString("label.select_background_colour");
 831     ColourChooserListener listener = new ColourChooserListener()
 832     {
 833       @Override
 834       public void colourSelected(Color c)
 835       {
 836         getBinding().setBackgroundColour(c);
 837       }
 838     };
 839     JalviewColourChooser.showColourChooser(this, ttl, null, listener);
 840   }
 841
 842   @Override
 843   public void viewerColour_actionPerformed()
 844   {
 845     if (viewerColour.isSelected())
 846     {
 847       // disable automatic sequence colouring.
 848       getBinding().setColourBySequence(false);
 849     }
 850   }
 851
 852   @Override
 853   public void chainColour_actionPerformed()
 854   {
 855     chainColour.setSelected(true);
 856     getBinding().colourByChain();
 857   }
 858
 859   @Override
 860   public void chargeColour_actionPerformed()
 861   {
 862     chargeColour.setSelected(true);
 863     getBinding().colourByCharge();
 864   }
 865
 866   @Override
 867   public void seqColour_actionPerformed()
 868   {
 869     AAStructureBindingModel binding = getBinding();
 870     binding.setColourBySequence(seqColour.isSelected());
 871     if (_colourwith == null)
 872     {
 873       _colourwith = new Vector<>();
 874     }
 875     if (binding.isColourBySequence())
 876     {
 877       if (!binding.isLoadingFromArchive())
 878       {
 879         if (_colourwith.size() == 0 && getAlignmentPanel() != null)
 880         {
 881           // Make the currently displayed alignment panel the associated view
 882           _colourwith.add(getAlignmentPanel().alignFrame.alignPanel);
 883         }
 884       }
 885       // Set the colour using the current view for the associated alignframe
 886       for (AlignmentViewPanel alignPanel : _colourwith)
 887       {
 888         binding.colourBySequence(alignPanel);
 889       }
 890       seqColoursApplied = true;
 891     }
 892   }
 893
 894   @Override
 895   public void pdbFile_actionPerformed()
 896   {
 897     // TODO: JAL-3048 not needed for Jalview-JS - save PDB file
 898     JalviewFileChooser chooser = new JalviewFileChooser(
 899             Cache.getProperty("LAST_DIRECTORY"));
 900
 901     chooser.setFileView(new JalviewFileView());
 902     chooser.setDialogTitle(MessageManager.getString("label.save_pdb_file"));
 903     chooser.setToolTipText(MessageManager.getString("action.save"));
 904
 905     int value = chooser.showSaveDialog(this);
 906
 907     if (value == JalviewFileChooser.APPROVE_OPTION)
 908     {
 909       BufferedReader in = null;
 910       try
 911       {
 912         // TODO: cope with multiple PDB files in view
 913         in = new BufferedReader(
 914                 new FileReader(getBinding().getStructureFiles()[0]));
 915         File outFile = chooser.getSelectedFile();
 916
 917         PrintWriter out = new PrintWriter(new FileOutputStream(outFile));
 918         String data;
 919         while ((data = in.readLine()) != null)
 920         {
 921           if (!(data.indexOf("<PRE>") > -1 || data.indexOf("</PRE>") > -1))
 922           {
 923             out.println(data);
 924           }
 925         }
 926         out.close();
 927       } catch (Exception ex)
 928       {
 929         ex.printStackTrace();
 930       } finally
 931       {
 932         if (in != null)
 933         {
 934           try
 935           {
 936             in.close();
 937           } catch (IOException e)
 938           {
 939             // ignore
 940           }
 941         }
 942       }
 943     }
 944   }
 945
 946   @Override
 947   public void viewMapping_actionPerformed()
 948   {
 949     CutAndPasteTransfer cap = new CutAndPasteTransfer();
 950     try
 951     {
 952       cap.appendText(getBinding().printMappings());
 953     } catch (OutOfMemoryError e)
 954     {
 955       new OOMWarning(
 956               "composing sequence-structure alignments for display in text box.",
 957               e);
 958       cap.dispose();
 959       return;
 960     }
 961     Desktop.addInternalFrame(cap,
 962             MessageManager.getString("label.pdb_sequence_mapping"), 550,
 963             600);
 964   }
 965
 966   protected abstract String getViewerName();
 967
 968   /**
 969    * Configures the title and menu items of the viewer panel.
 970    */
 971   @Override
 972   public void updateTitleAndMenus()
 973   {
 974     AAStructureBindingModel binding = getBinding();
 975     if (binding.hasFileLoadingError())
 976     {
 977       repaint();
 978       return;
 979     }
 980     setChainMenuItems(binding.getChainNames());
 981
 982     this.setTitle(binding.getViewerTitle(getViewerName(), true));
 983
 984     /*
 985      * enable 'Superpose with' if more than one mapped structure
 986      */
 987     viewSelectionMenu.setEnabled(false);
 988     if (getBinding().getMappedStructureCount() > 1
 989             && getBinding().getSequence().length > 1)
 990     {
 991       viewSelectionMenu.setEnabled(true);
 992     }
 993
 994     /*
 995      * Show action menu if it has any enabled items
 996      */
 997     viewerActionMenu.setVisible(false);
 998     for (int i = 0; i < viewerActionMenu.getItemCount(); i++)
 999     {
1000       if (viewerActionMenu.getItem(i).isEnabled())
1001       {
1002         viewerActionMenu.setVisible(true);
1003         break;
1004       }
1005     }
1006
1007     if (!binding.isLoadingFromArchive())
1008     {
1009       seqColour_actionPerformed();
1010     }
1011   }
1012
1013   @Override
1014   public String toString()
1015   {
1016     return getTitle();
1017   }
1018
1019   @Override
1020   public boolean hasMapping()
1021   {
1022     if (worker != null && (addingStructures || _started))
1023     {
1024       return false;
1025     }
1026     if (getBinding() == null)
1027     {
1028       if (_aps == null || _aps.size() == 0)
1029       {
1030         // viewer has been closed, but we did at some point run.
1031         return true;
1032       }
1033       return false;
1034     }
1035     String[] pdbids = getBinding().getStructureFiles();
1036     if (pdbids == null)
1037     {
1038       return false;
1039     }
1040     int p=0;
1041     for (String pdbid:pdbids) {
1042       StructureMapping sm[] = getBinding().getSsm().getMapping(pdbid);
1043       if (sm!=null && sm.length>0 && sm[0]!=null) {
1044         p++;
1045       }
1046     }
1047     // only return true if there is a mapping for every structure file we have loaded
1048     if (p == 0 || p != pdbids.length)
1049     {
1050       return false;
1051     }
1052     // and that coloring has been applied
1053     return seqColoursApplied;
1054   }
1055
1056   @Override
1057   public void raiseViewer()
1058   {
1059     toFront();
1060   }
1061
1062   @Override
1063   public long startProgressBar(String msg)
1064   {
1065     // TODO would rather have startProgress/stopProgress as the
1066     // IProgressIndicator interface
1067     long tm = random.nextLong();
1068     if (progressBar != null)
1069     {
1070       progressBar.setProgressBar(msg, tm);
1071     }
1072     return tm;
1073   }
1074
1075   @Override
1076   public void stopProgressBar(String msg, long handle)
1077   {
1078     if (progressBar != null)
1079     {
1080       progressBar.setProgressBar(msg, handle);
1081     }
1082   }
1083
1084   protected IProgressIndicator getProgressIndicator()
1085   {
1086     return progressBar;
1087   }
1088
1089   protected void setProgressIndicator(IProgressIndicator pi)
1090   {
1091     progressBar = pi;
1092   }
1093
1094   public void setProgressMessage(String message, long id)
1095   {
1096     if (progressBar != null)
1097     {
1098       progressBar.setProgressBar(message, id);
1099     }
1100   }
1101
1102   @Override
1103   public void showConsole(boolean show)
1104   {
1105     // default does nothing
1106   }
1107
1108   /**
1109    * Show only the selected chain(s) in the viewer
1110    */
1111   protected void showSelectedChains()
1112   {
1113     List<String> toshow = new ArrayList<>();
1114     for (int i = 0; i < chainMenu.getItemCount(); i++)
1115     {
1116       if (chainMenu.getItem(i) instanceof JCheckBoxMenuItem)
1117       {
1118         JCheckBoxMenuItem item = (JCheckBoxMenuItem) chainMenu.getItem(i);
1119         if (item.isSelected())
1120         {
1121           toshow.add(item.getText());
1122         }
1123       }
1124     }
1125     getBinding().showChains(toshow);
1126   }
1127
1128   /**
1129    * Tries to fetch a PDB file and save to a temporary local file. Returns the
1130    * saved file path if successful, or null if not.
1131    *
1132    * @param processingEntry
1133    * @return
1134    */
1135   protected String fetchPdbFile(PDBEntry processingEntry)
1136   {
1137     String filePath = null;
1138     Pdb pdbclient = new Pdb();
1139     EBIAlfaFold afclient =  new EBIAlfaFold();
1140     AlignmentI pdbseq = null;
1141     String pdbid = processingEntry.getId();
1142     long handle = System.currentTimeMillis()
1143             + Thread.currentThread().hashCode();
1144
1145     /*
1146      * Write 'fetching PDB' progress on AlignFrame as we are not yet visible
1147      */
1148     String msg = MessageManager.formatMessage("status.fetching_pdb",
1149             new Object[]
1150             { pdbid });
1151     getAlignmentPanel().alignFrame.setProgressBar(msg, handle);
1152     // long hdl = startProgressBar(MessageManager.formatMessage(
1153     // "status.fetching_pdb", new Object[]
1154     // { pdbid }));
1155     try
1156     {
1157       if (afclient.isValidReference(pdbid))
1158       {
1159         pdbseq = afclient.getSequenceRecords(pdbid);
1160       } else {
1161           if (processingEntry.hasRetrievalUrl())
1162           {
1163             // retrieve from URL to new local tmpfile
1164             File tmpFile = File.createTempFile(pdbid,
1165                     "." + (PDBEntry.Type.MMCIF.toString().equals(
1166                             processingEntry.getType().toString()) ? "cif"
1167                                     : "pdb"));
1168             String fromUrl = processingEntry.getRetrievalUrl();
1169             UrlDownloadClient.download(fromUrl, tmpFile);
1170
1171             // may not need this check ?
1172             String file = tmpFile.getAbsolutePath();
1173             if (file != null)
1174             {
1175               pdbseq = EBIAlfaFold.importDownloadedStructureFromUrl(fromUrl,tmpFile,pdbid,null,null,null);
1176             }
1177           } else {
1178             pdbseq = pdbclient.getSequenceRecords(pdbid);
1179           }
1180       }
1181     } catch (Exception e)
1182     {
1183       System.err.println(
1184               "Error retrieving PDB id " + pdbid + ": " + e.getMessage());
1185     } finally
1186     {
1187       msg = pdbid + " " + MessageManager.getString("label.state_completed");
1188       getAlignmentPanel().alignFrame.setProgressBar(msg, handle);
1189       // stopProgressBar(msg, hdl);
1190     }
1191     /*
1192      * If PDB data were saved and are not invalid (empty alignment), return the
1193      * file path.
1194      */
1195     if (pdbseq != null && pdbseq.getHeight() > 0)
1196     {
1197       // just use the file name from the first sequence's first PDBEntry
1198       filePath = new File(pdbseq.getSequenceAt(0).getAllPDBEntries()
1199               .elementAt(0).getFile()).getAbsolutePath();
1200       processingEntry.setFile(filePath);
1201     }
1202     return filePath;
1203   }
1204
1205   /**
1206    * If supported, saves the state of the structure viewer to a temporary file
1207    * and returns the file, else returns null
1208    *
1209    * @return
1210    */
1211   public File saveSession()
1212   {
1213     if (getBinding() == null) { return  null;}
1214     File session = getBinding().saveSession();
1215     long l = session.length();
1216     int wait=50;
1217     do {
1218       try {
1219         Thread.sleep(5);
1220       } catch (InterruptedException e) {
1221       }
1222       long nextl = session.length();
1223       if (nextl!=l)
1224       {
1225         wait = 50;
1226         l=nextl;
1227       }
1228     } while (--wait>0);
1229     return session;
1230   }
1231
1232   /**
1233    * Close down this instance of Jalview's Chimera viewer, giving the user the
1234    * option to close the associated Chimera window (process). They may wish to
1235    * keep it open until they have had an opportunity to save any work.
1236    *
1237    * @param forceClose
1238    *          if true, close any linked Chimera process; if false, prompt first
1239    */
1240   @Override
1241   public void closeViewer(boolean forceClose)
1242   {
1243     AAStructureBindingModel binding = getBinding();
1244     if (binding != null && binding.isViewerRunning())
1245     {
1246       if (!forceClose)
1247       {
1248         String viewerName = getViewerName();
1249         String prompt = MessageManager
1250                 .formatMessage("label.confirm_close_viewer", new Object[]
1251                 { binding.getViewerTitle(viewerName, false), viewerName });
1252         prompt = JvSwingUtils.wrapTooltip(true, prompt);
1253         int confirm = JvOptionPane.showConfirmDialog(this, prompt,
1254                 MessageManager.getString("label.close_viewer"),
1255                 JvOptionPane.YES_NO_CANCEL_OPTION);
1256         /*
1257          * abort closure if user hits escape or Cancel
1258          */
1259         if (confirm == JvOptionPane.CANCEL_OPTION
1260                 || confirm == JvOptionPane.CLOSED_OPTION)
1261         {
1262           return;
1263         }
1264         forceClose = confirm == JvOptionPane.YES_OPTION;
1265       }
1266     }
1267     if (binding != null)
1268     {
1269       binding.closeViewer(forceClose);
1270     }
1271     setAlignmentPanel(null);
1272     _aps.clear();
1273     _alignwith.clear();
1274     _colourwith.clear();
1275     // TODO: check for memory leaks where instance isn't finalised because jmb
1276     // holds a reference to the window
1277     // jmb = null;
1278     dispose();
1279   }
1280
1281   @Override
1282   public void showHelp_actionPerformed()
1283   {
1284     try
1285     {
1286       String url = getBinding().getHelpURL();
1287       if (url != null)
1288       {
1289         BrowserLauncher.openURL(url);
1290       }
1291     } catch (IOException ex)
1292     {
1293       System.err
1294               .println("Show " + getViewerName() + " failed with: "
1295                       + ex.getMessage());
1296     }
1297   }
1298   @Override
1299   public boolean hasViewerActionsMenu()
1300   {
1301     return viewerActionMenu != null && viewerActionMenu.isEnabled()
1302             && viewerActionMenu.getItemCount() > 0
1303             && viewerActionMenu.isVisible();
1304   }
1305 }