src/jalview/viewmodel/ViewportRanges.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.viewmodel;
  22
  23 import jalview.datamodel.AlignmentI;
  24 import jalview.datamodel.HiddenColumns;
  25
  26 /**
  27  * Supplies and updates viewport properties relating to position such as: start
  28  * and end residues and sequences; ideally will serve hidden columns/rows too.
  29  * Intention also to support calculations for positioning, scrolling etc. such
  30  * as finding the middle of the viewport, checking for scrolls off screen
  31  */
  32 public class ViewportRanges extends ViewportProperties
  33 {
  34   public static final String STARTRES = "startres";
  35
  36   public static final String ENDRES = "endres";
  37
  38   public static final String STARTSEQ = "startseq";
  39
  40   public static final String ENDSEQ = "endseq";
  41
  42   public static final String STARTRESANDSEQ = "startresandseq";
  43
  44   private boolean wrappedMode = false;
  45
  46   // start residue of viewport
  47   private int startRes;
  48
  49   // end residue of viewport
  50   private int endRes;
  51
  52   // start sequence of viewport
  53   private int startSeq;
  54
  55   // end sequence of viewport
  56   private int endSeq;
  57
  58   // alignment
  59   private AlignmentI al;
  60
  61   /**
  62    * Constructor
  63    *
  64    * @param alignment
  65    *          the viewport's alignment
  66    */
  67   public ViewportRanges(AlignmentI alignment)
  68   {
  69     // initial values of viewport settings
  70     this.startRes = 0;
  71     this.endRes = alignment.getWidth() - 1;
  72     this.startSeq = 0;
  73     this.endSeq = alignment.getHeight() - 1;
  74     this.al = alignment;
  75   }
  76
  77   /**
  78    * Get alignment width in cols, including hidden cols
  79    */
  80   public int getAbsoluteAlignmentWidth()
  81   {
  82     return al.getWidth();
  83   }
  84
  85   /**
  86    * Get alignment height in rows, including hidden rows
  87    */
  88   public int getAbsoluteAlignmentHeight()
  89   {
  90     return al.getHeight() + al.getHiddenSequences().getSize();
  91   }
  92
  93   /**
  94    * Get alignment width in cols, excluding hidden cols
  95    */
  96   public int getVisibleAlignmentWidth()
  97   {
  98     return al.getWidth() - al.getHiddenColumns().getSize();
  99   }
 100
 101   /**
 102    * Get alignment height in rows, excluding hidden rows
 103    */
 104   public int getVisibleAlignmentHeight()
 105   {
 106     return al.getHeight();
 107   }
 108
 109   /**
 110    * Set first residue visible in the viewport, and retain the current width.
 111    * Fires a property change event.
 112    *
 113    * @param res
 114    *          residue position
 115    */
 116   public void setStartRes(int res)
 117   {
 118     int width = getViewportWidth();
 119     setStartEndRes(res, res + width - 1);
 120   }
 121
 122   /**
 123    * Set start and end residues at the same time. This method only fires one
 124    * event for the two changes, and should be used in preference to separate
 125    * calls to setStartRes and setEndRes.
 126    *
 127    * @param start
 128    *          the start residue
 129    * @param end
 130    *          the end residue
 131    */
 132   public void setStartEndRes(int start, int end)
 133   {
 134     int[] oldvalues = updateStartEndRes(start, end);
 135     int oldstartres = oldvalues[0];
 136     int oldendres = oldvalues[1];
 137
 138     changeSupport.firePropertyChange(STARTRES, oldstartres, startRes);
 139     if (oldstartres == startRes)
 140     {
 141       // event won't be fired if start positions are same
 142       // fire an event for the end positions in case they changed
 143       changeSupport.firePropertyChange(ENDRES, oldendres, endRes);
 144     }
 145   }
 146
 147   /**
 148    * Update start and end residue values, adjusting for width constraints if
 149    * necessary
 150    *
 151    * @param start
 152    *          start residue
 153    * @param end
 154    *          end residue
 155    * @return array containing old start and end residue values
 156    */
 157   private int[] updateStartEndRes(int start, int end)
 158   {
 159     int oldstartres = this.startRes;
 160
 161     /*
 162      * if not wrapped, don't leave white space at the right margin
 163      */
 164     int lastColumn = getVisibleAlignmentWidth() - 1;
 165     if (!wrappedMode && (start > lastColumn))
 166     {
 167       startRes = Math.max(lastColumn, 0);
 168     }
 169     else if (start < 0)
 170     {
 171       startRes = 0;
 172     }
 173     else
 174     {
 175       startRes = start;
 176     }
 177
 178     int oldendres = this.endRes;
 179     if (end < 0)
 180     {
 181       endRes = 0;
 182     }
 183     else if (!wrappedMode && (end > lastColumn))
 184     {
 185       endRes = Math.max(lastColumn, 0);
 186     }
 187     else
 188     {
 189       endRes = end;
 190     }
 191     return new int[] { oldstartres, oldendres };
 192   }
 193
 194   /**
 195    * Set the first sequence visible in the viewport, maintaining the height. If
 196    * the viewport would extend past the last sequence, sets the viewport so it
 197    * sits at the bottom of the alignment. Fires a property change event.
 198    *
 199    * @param seq
 200    *          sequence position
 201    */
 202   public void setStartSeq(int seq)
 203   {
 204     int startseq = seq;
 205     int height = getViewportHeight();
 206     if (startseq + height - 1 > getVisibleAlignmentHeight() - 1)
 207     {
 208       startseq = getVisibleAlignmentHeight() - height;
 209     }
 210     setStartEndSeq(startseq, startseq + height - 1);
 211   }
 212
 213   /**
 214    * Set start and end sequences at the same time. The viewport height may
 215    * change. This method only fires one event for the two changes, and should be
 216    * used in preference to separate calls to setStartSeq and setEndSeq.
 217    *
 218    * @param start
 219    *          the start sequence
 220    * @param end
 221    *          the end sequence
 222    */
 223   public void setStartEndSeq(int start, int end)
 224   {
 225     int[] oldvalues = updateStartEndSeq(start, end);
 226     int oldstartseq = oldvalues[0];
 227     int oldendseq = oldvalues[1];
 228
 229     changeSupport.firePropertyChange(STARTSEQ, oldstartseq, startSeq);
 230     if (oldstartseq == startSeq)
 231     {
 232       // event won't be fired if start positions are the same
 233       // fire in case the end positions changed
 234       changeSupport.firePropertyChange(ENDSEQ, oldendseq, endSeq);
 235     }
 236   }
 237
 238   /**
 239    * Update start and end sequence values, adjusting for height constraints if
 240    * necessary
 241    *
 242    * @param start
 243    *          start sequence
 244    * @param end
 245    *          end sequence
 246    * @return array containing old start and end sequence values
 247    */
 248   private int[] updateStartEndSeq(int start, int end)
 249   {
 250     int oldstartseq = this.startSeq;
 251     int visibleHeight = getVisibleAlignmentHeight();
 252     if (start > visibleHeight - 1)
 253     {
 254       startSeq = Math.max(visibleHeight - 1, 0);
 255     }
 256     else if (start < 0)
 257     {
 258       startSeq = 0;
 259     }
 260     else
 261     {
 262       startSeq = start;
 263     }
 264
 265     int oldendseq = this.endSeq;
 266     if (end >= visibleHeight)
 267     {
 268       endSeq = Math.max(visibleHeight - 1, 0);
 269     }
 270     else if (end < 0)
 271     {
 272       endSeq = 0;
 273     }
 274     else
 275     {
 276       endSeq = end;
 277     }
 278     return new int[] { oldstartseq, oldendseq };
 279   }
 280
 281   /**
 282    * Set the last sequence visible in the viewport. Fires a property change
 283    * event.
 284    *
 285    * @param seq
 286    *          sequence position
 287    */
 288   public void setEndSeq(int seq)
 289   {
 290     int height = getViewportHeight();
 291     setStartEndSeq(seq - height + 1, seq);
 292   }
 293
 294   /**
 295    * Set start residue and start sequence together (fires single event)
 296    *
 297    * @param res
 298    *          the start residue
 299    * @param seq
 300    *          the start sequence
 301    */
 302   public void setStartResAndSeq(int res, int seq)
 303   {
 304     int width = getViewportWidth();
 305     int[] oldresvalues = updateStartEndRes(res, res + width - 1);
 306
 307     int startseq = seq;
 308     int height = getViewportHeight();
 309     if (startseq + height - 1 > getVisibleAlignmentHeight() - 1)
 310     {
 311       startseq = getVisibleAlignmentHeight() - height;
 312     }
 313     int[] oldseqvalues = updateStartEndSeq(startseq, startseq + height - 1);
 314
 315     int[] old = new int[] { oldresvalues[0], oldseqvalues[0] };
 316     int[] newresseq = new int[] { startRes, startSeq };
 317     changeSupport.firePropertyChange(STARTRESANDSEQ, old, newresseq);
 318   }
 319
 320   /**
 321    * Get start residue of viewport
 322    */
 323   public int getStartRes()
 324   {
 325     return startRes;
 326   }
 327
 328   /**
 329    * Get end residue of viewport
 330    */
 331   public int getEndRes()
 332   {
 333     return endRes;
 334   }
 335
 336   /**
 337    * Get start sequence of viewport
 338    */
 339   public int getStartSeq()
 340   {
 341     return startSeq;
 342   }
 343
 344   /**
 345    * Get end sequence of viewport
 346    */
 347   public int getEndSeq()
 348   {
 349     return endSeq;
 350   }
 351
 352   /**
 353    * Set viewport width in residues, without changing startRes. Use in
 354    * preference to calculating endRes from the width, to avoid out by one
 355    * errors! Fires a property change event.
 356    *
 357    * @param w
 358    *          width in residues
 359    */
 360   public void setViewportWidth(int w)
 361   {
 362     setStartEndRes(startRes, startRes + w - 1);
 363   }
 364
 365   /**
 366    * Set viewport height in residues, without changing startSeq. Use in
 367    * preference to calculating endSeq from the height, to avoid out by one
 368    * errors! Fires a property change event.
 369    *
 370    * @param h
 371    *          height in sequences
 372    */
 373   public void setViewportHeight(int h)
 374   {
 375     setStartEndSeq(startSeq, startSeq + h - 1);
 376   }
 377
 378   /**
 379    * Set viewport horizontal start position and width. Use in preference to
 380    * calculating endRes from the width, to avoid out by one errors! Fires a
 381    * property change event.
 382    *
 383    * @param start
 384    *          start residue
 385    * @param w
 386    *          width in residues
 387    */
 388   public void setViewportStartAndWidth(int start, int w)
 389   {
 390     int vpstart = start;
 391     if (vpstart < 0)
 392     {
 393       vpstart = 0;
 394     }
 395
 396     /*
 397      * if not wrapped, don't leave white space at the right margin
 398      */
 399     if (!wrappedMode)
 400     {
 401       if ((w <= getVisibleAlignmentWidth())
 402               && (vpstart + w - 1 > getVisibleAlignmentWidth() - 1))
 403       {
 404         vpstart = getVisibleAlignmentWidth() - w;
 405       }
 406
 407     }
 408     setStartEndRes(vpstart, vpstart + w - 1);
 409   }
 410
 411   /**
 412    * Set viewport vertical start position and height. Use in preference to
 413    * calculating endSeq from the height, to avoid out by one errors! Fires a
 414    * property change event.
 415    *
 416    * @param start
 417    *          start sequence
 418    * @param h
 419    *          height in sequences
 420    */
 421   public void setViewportStartAndHeight(int start, int h)
 422   {
 423     int vpstart = start;
 424     if (vpstart < 0)
 425     {
 426       vpstart = 0;
 427     }
 428     else if ((h <= getVisibleAlignmentHeight())
 429             && (vpstart + h - 1 > getVisibleAlignmentHeight() - 1))
 430     // viewport height is less than the full alignment and we are running off
 431     // the bottom
 432     {
 433       vpstart = getVisibleAlignmentHeight() - h;
 434     }
 435     setStartEndSeq(vpstart, vpstart + h - 1);
 436   }
 437
 438   /**
 439    * Get width of viewport in residues
 440    *
 441    * @return width of viewport
 442    */
 443   public int getViewportWidth()
 444   {
 445     return (endRes - startRes + 1);
 446   }
 447
 448   /**
 449    * Get height of viewport in residues
 450    *
 451    * @return height of viewport
 452    */
 453   public int getViewportHeight()
 454   {
 455     return (endSeq - startSeq + 1);
 456   }
 457
 458   /**
 459    * Scroll the viewport range vertically. Fires a property change event.
 460    *
 461    * @param up
 462    *          true if scrolling up, false if down
 463    *
 464    * @return true if the scroll is valid
 465    */
 466   public boolean scrollUp(boolean up)
 467   {
 468     /*
 469      * if in unwrapped mode, scroll up or down one sequence row;
 470      * if in wrapped mode, scroll by one visible width of columns
 471      */
 472     if (up)
 473     {
 474       if (wrappedMode)
 475       {
 476         pageUp();
 477       }
 478       else
 479       {
 480         if (startSeq < 1)
 481         {
 482           return false;
 483         }
 484         setStartSeq(startSeq - 1);
 485       }
 486     }
 487     else
 488     {
 489       if (wrappedMode)
 490       {
 491         pageDown();
 492       }
 493       else
 494       {
 495         if (endSeq >= getVisibleAlignmentHeight() - 1)
 496         {
 497           return false;
 498         }
 499         setStartSeq(startSeq + 1);
 500       }
 501     }
 502     return true;
 503   }
 504
 505   /**
 506    * Scroll the viewport range horizontally. Fires a property change event.
 507    *
 508    * @param right
 509    *          true if scrolling right, false if left
 510    *
 511    * @return true if the scroll is valid
 512    */
 513   public boolean scrollRight(boolean right)
 514   {
 515     if (!right)
 516     {
 517       if (startRes < 1)
 518       {
 519         return false;
 520       }
 521
 522       setStartRes(startRes - 1);
 523     }
 524     else
 525     {
 526       if (endRes >= getVisibleAlignmentWidth() - 1)
 527       {
 528         return false;
 529       }
 530
 531       setStartRes(startRes + 1);
 532     }
 533
 534     return true;
 535   }
 536
 537   /**
 538    * Scroll a wrapped alignment so that the specified residue is in the first
 539    * repeat of the wrapped view. Fires a property change event. Answers true if
 540    * the startRes changed, else false.
 541    *
 542    * @param res
 543    *          residue position to scroll to
 544    * @return
 545    */
 546   public boolean scrollToWrappedVisible(int res)
 547   {
 548     int oldStartRes = startRes;
 549     int width = getViewportWidth();
 550
 551     if (res >= oldStartRes && res < oldStartRes + width)
 552     {
 553       return false;
 554     }
 555
 556     boolean up = res < oldStartRes;
 557     int widthsToScroll = Math.abs((res - oldStartRes) / width);
 558     if (up)
 559     {
 560       widthsToScroll++;
 561     }
 562
 563     int residuesToScroll = width * widthsToScroll;
 564     int newStartRes = up ? oldStartRes - residuesToScroll : oldStartRes
 565             + residuesToScroll;
 566     if (newStartRes < 0)
 567     {
 568       newStartRes = 0;
 569     }
 570
 571     setStartRes(newStartRes);
 572
 573     return true;
 574   }
 575
 576   /**
 577    * Scroll so that (x,y) is visible. Fires a property change event.
 578    *
 579    * @param x
 580    *          x position in alignment
 581    * @param y
 582    *          y position in alignment
 583    */
 584   public void scrollToVisible(int x, int y)
 585   {
 586     while (y < startSeq)
 587     {
 588       scrollUp(true);
 589     }
 590     while (y > endSeq)
 591     {
 592       scrollUp(false);
 593     }
 594
 595     HiddenColumns hidden = al.getHiddenColumns();
 596     while (x < hidden.adjustForHiddenColumns(startRes))
 597     {
 598       if (!scrollRight(false))
 599       {
 600         break;
 601       }
 602     }
 603     while (x > hidden.adjustForHiddenColumns(endRes))
 604     {
 605       if (!scrollRight(true))
 606       {
 607         break;
 608       }
 609     }
 610   }
 611
 612   /**
 613    * Adjust sequence position for page up. Fires a property change event.
 614    */
 615   public void pageUp()
 616   {
 617     if (wrappedMode)
 618     {
 619       setStartRes(Math.max(0, getStartRes() - getViewportWidth()));
 620     }
 621     else
 622     {
 623       setViewportStartAndHeight(startSeq - (endSeq - startSeq),
 624               getViewportHeight());
 625     }
 626   }
 627
 628   /**
 629    * Adjust sequence position for page down. Fires a property change event.
 630    */
 631   public void pageDown()
 632   {
 633     if (wrappedMode)
 634     {
 635       /*
 636        * if height is more than width (i.e. not all sequences fit on screen),
 637        * increase page down to height
 638        */
 639       int newStart = getStartRes()
 640               + Math.max(getViewportHeight(), getViewportWidth());
 641
 642       /*
 643        * don't page down beyond end of alignment, or if not all
 644        * sequences fit in the visible height
 645        */
 646       if (newStart < getVisibleAlignmentWidth())
 647       {
 648         setStartRes(newStart);
 649       }
 650     }
 651     else
 652     {
 653       setViewportStartAndHeight(endSeq, getViewportHeight());
 654     }
 655   }
 656
 657   public void setWrappedMode(boolean wrapped)
 658   {
 659     wrappedMode = wrapped;
 660   }
 661
 662   public boolean isWrappedMode()
 663   {
 664     return wrappedMode;
 665   }
 666
 667   /**
 668    * Answers the vertical scroll position (0..) to set, given the visible column
 669    * that is at top left.
 670    *
 671    * <pre>
 672    * Example:
 673    *    viewport width 40 columns (0-39, 40-79, 80-119...)
 674    *    column 0 returns scroll position 0
 675    *    columns 1-40 return scroll position 1
 676    *    columns 41-80 return scroll position 2
 677    *    etc
 678    * </pre>
 679    *
 680    * @param topLeftColumn
 681    *          (0..)
 682    * @return
 683    */
 684   public int getWrappedScrollPosition(final int topLeftColumn)
 685   {
 686     int w = getViewportWidth();
 687
 688     /*
 689      * visible whole widths
 690      */
 691     int scroll = topLeftColumn / w;
 692
 693     /*
 694      * add 1 for a part width if there is one
 695      */
 696     scroll += topLeftColumn % w > 0 ? 1 : 0;
 697
 698     return scroll;
 699   }
 700
 701   /**
 702    * Answers the maximum wrapped vertical scroll value, given the column
 703    * position (0..) to show at top left of the visible region.
 704    *
 705    * @param topLeftColumn
 706    * @return
 707    */
 708   public int getWrappedMaxScroll(int topLeftColumn)
 709   {
 710     int scrollPosition = getWrappedScrollPosition(topLeftColumn);
 711
 712     /*
 713      * how many more widths could be drawn after this one?
 714      */
 715     int columnsRemaining = getVisibleAlignmentWidth() - topLeftColumn;
 716     int width = getViewportWidth();
 717     int widthsRemaining = columnsRemaining / width
 718             + (columnsRemaining % width > 0 ? 1 : 0) - 1;
 719     int maxScroll = scrollPosition + widthsRemaining;
 720
 721     return maxScroll;
 722   }
 723 }