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). The
 296    * event supplies a pair of old values and a pair of new values: [old start
 297    * residue, old start sequence] and [new start residue, new start sequence]
 298    *
 299    * @param res
 300    *          the start residue
 301    * @param seq
 302    *          the start sequence
 303    */
 304   public void setStartResAndSeq(int res, int seq)
 305   {
 306     int width = getViewportWidth();
 307     int[] oldresvalues = updateStartEndRes(res, res + width - 1);
 308
 309     int startseq = seq;
 310     int height = getViewportHeight();
 311     if (startseq + height - 1 > getVisibleAlignmentHeight() - 1)
 312     {
 313       startseq = getVisibleAlignmentHeight() - height;
 314     }
 315     int[] oldseqvalues = updateStartEndSeq(startseq, startseq + height - 1);
 316
 317     int[] old = new int[] { oldresvalues[0], oldseqvalues[0] };
 318     int[] newresseq = new int[] { startRes, startSeq };
 319     changeSupport.firePropertyChange(STARTRESANDSEQ, old, newresseq);
 320   }
 321
 322   /**
 323    * Get start residue of viewport
 324    */
 325   public int getStartRes()
 326   {
 327     return startRes;
 328   }
 329
 330   /**
 331    * Get end residue of viewport
 332    */
 333   public int getEndRes()
 334   {
 335     return endRes;
 336   }
 337
 338   /**
 339    * Get start sequence of viewport
 340    */
 341   public int getStartSeq()
 342   {
 343     return startSeq;
 344   }
 345
 346   /**
 347    * Get end sequence of viewport
 348    */
 349   public int getEndSeq()
 350   {
 351     return endSeq;
 352   }
 353
 354   /**
 355    * Set viewport width in residues, without changing startRes. Use in
 356    * preference to calculating endRes from the width, to avoid out by one
 357    * errors! Fires a property change event.
 358    *
 359    * @param w
 360    *          width in residues
 361    */
 362   public void setViewportWidth(int w)
 363   {
 364     setStartEndRes(startRes, startRes + w - 1);
 365   }
 366
 367   /**
 368    * Set viewport height in residues, without changing startSeq. Use in
 369    * preference to calculating endSeq from the height, to avoid out by one
 370    * errors! Fires a property change event.
 371    *
 372    * @param h
 373    *          height in sequences
 374    */
 375   public void setViewportHeight(int h)
 376   {
 377     setStartEndSeq(startSeq, startSeq + h - 1);
 378   }
 379
 380   /**
 381    * Set viewport horizontal start position and width. Use in preference to
 382    * calculating endRes from the width, to avoid out by one errors! Fires a
 383    * property change event.
 384    *
 385    * @param start
 386    *          start residue
 387    * @param w
 388    *          width in residues
 389    */
 390   public void setViewportStartAndWidth(int start, int w)
 391   {
 392     int vpstart = start;
 393     if (vpstart < 0)
 394     {
 395       vpstart = 0;
 396     }
 397
 398     /*
 399      * if not wrapped, don't leave white space at the right margin
 400      */
 401     if (!wrappedMode)
 402     {
 403       if ((w <= getVisibleAlignmentWidth())
 404               && (vpstart + w - 1 > getVisibleAlignmentWidth() - 1))
 405       {
 406         vpstart = getVisibleAlignmentWidth() - w;
 407       }
 408
 409     }
 410     setStartEndRes(vpstart, vpstart + w - 1);
 411   }
 412
 413   /**
 414    * Set viewport vertical start position and height. Use in preference to
 415    * calculating endSeq from the height, to avoid out by one errors! Fires a
 416    * property change event.
 417    *
 418    * @param start
 419    *          start sequence
 420    * @param h
 421    *          height in sequences
 422    */
 423   public void setViewportStartAndHeight(int start, int h)
 424   {
 425     int vpstart = start;
 426     if (vpstart < 0)
 427     {
 428       vpstart = 0;
 429     }
 430     else if ((h <= getVisibleAlignmentHeight())
 431             && (vpstart + h - 1 > getVisibleAlignmentHeight() - 1))
 432     // viewport height is less than the full alignment and we are running off
 433     // the bottom
 434     {
 435       vpstart = getVisibleAlignmentHeight() - h;
 436     }
 437     setStartEndSeq(vpstart, vpstart + h - 1);
 438   }
 439
 440   /**
 441    * Get width of viewport in residues
 442    *
 443    * @return width of viewport
 444    */
 445   public int getViewportWidth()
 446   {
 447     return (endRes - startRes + 1);
 448   }
 449
 450   /**
 451    * Get height of viewport in residues
 452    *
 453    * @return height of viewport
 454    */
 455   public int getViewportHeight()
 456   {
 457     return (endSeq - startSeq + 1);
 458   }
 459
 460   /**
 461    * Scroll the viewport range vertically. Fires a property change event.
 462    *
 463    * @param up
 464    *          true if scrolling up, false if down
 465    *
 466    * @return true if the scroll is valid
 467    */
 468   public boolean scrollUp(boolean up)
 469   {
 470     /*
 471      * if in unwrapped mode, scroll up or down one sequence row;
 472      * if in wrapped mode, scroll by one visible width of columns
 473      */
 474     if (up)
 475     {
 476       if (wrappedMode)
 477       {
 478         pageUp();
 479       }
 480       else
 481       {
 482         if (startSeq < 1)
 483         {
 484           return false;
 485         }
 486         setStartSeq(startSeq - 1);
 487       }
 488     }
 489     else
 490     {
 491       if (wrappedMode)
 492       {
 493         pageDown();
 494       }
 495       else
 496       {
 497         if (endSeq >= getVisibleAlignmentHeight() - 1)
 498         {
 499           return false;
 500         }
 501         setStartSeq(startSeq + 1);
 502       }
 503     }
 504     return true;
 505   }
 506
 507   /**
 508    * Scroll the viewport range horizontally. Fires a property change event.
 509    *
 510    * @param right
 511    *          true if scrolling right, false if left
 512    *
 513    * @return true if the scroll is valid
 514    */
 515   public boolean scrollRight(boolean right)
 516   {
 517     if (!right)
 518     {
 519       if (startRes < 1)
 520       {
 521         return false;
 522       }
 523
 524       setStartRes(startRes - 1);
 525     }
 526     else
 527     {
 528       if (endRes >= getVisibleAlignmentWidth() - 1)
 529       {
 530         return false;
 531       }
 532
 533       setStartRes(startRes + 1);
 534     }
 535
 536     return true;
 537   }
 538
 539   /**
 540    * Scroll a wrapped alignment so that the specified residue is in the first
 541    * repeat of the wrapped view. Fires a property change event. Answers true if
 542    * the startRes changed, else false.
 543    *
 544    * @param res
 545    *          residue position to scroll to
 546    * @return
 547    */
 548   public boolean scrollToWrappedVisible(int res)
 549   {
 550     int oldStartRes = startRes;
 551     int width = getViewportWidth();
 552
 553     if (res >= oldStartRes && res < oldStartRes + width)
 554     {
 555       return false;
 556     }
 557
 558     boolean up = res < oldStartRes;
 559     int widthsToScroll = Math.abs((res - oldStartRes) / width);
 560     if (up)
 561     {
 562       widthsToScroll++;
 563     }
 564
 565     int residuesToScroll = width * widthsToScroll;
 566     int newStartRes = up ? oldStartRes - residuesToScroll : oldStartRes
 567             + residuesToScroll;
 568     if (newStartRes < 0)
 569     {
 570       newStartRes = 0;
 571     }
 572
 573     setStartRes(newStartRes);
 574
 575     return true;
 576   }
 577
 578   /**
 579    * Scroll so that (x,y) is visible. Fires a property change event.
 580    *
 581    * @param x
 582    *          x position in alignment
 583    * @param y
 584    *          y position in alignment
 585    */
 586   public void scrollToVisible(int x, int y)
 587   {
 588     while (y < startSeq)
 589     {
 590       scrollUp(true);
 591     }
 592     while (y > endSeq)
 593     {
 594       scrollUp(false);
 595     }
 596
 597     HiddenColumns hidden = al.getHiddenColumns();
 598     while (x < hidden.adjustForHiddenColumns(startRes))
 599     {
 600       if (!scrollRight(false))
 601       {
 602         break;
 603       }
 604     }
 605     while (x > hidden.adjustForHiddenColumns(endRes))
 606     {
 607       if (!scrollRight(true))
 608       {
 609         break;
 610       }
 611     }
 612   }
 613
 614   /**
 615    * Adjust sequence position for page up. Fires a property change event.
 616    */
 617   public void pageUp()
 618   {
 619     if (wrappedMode)
 620     {
 621       setStartRes(Math.max(0, getStartRes() - getViewportWidth()));
 622     }
 623     else
 624     {
 625       setViewportStartAndHeight(startSeq - (endSeq - startSeq),
 626               getViewportHeight());
 627     }
 628   }
 629
 630   /**
 631    * Adjust sequence position for page down. Fires a property change event.
 632    */
 633   public void pageDown()
 634   {
 635     if (wrappedMode)
 636     {
 637       /*
 638        * if height is more than width (i.e. not all sequences fit on screen),
 639        * increase page down to height
 640        */
 641       int newStart = getStartRes()
 642               + Math.max(getViewportHeight(), getViewportWidth());
 643
 644       /*
 645        * don't page down beyond end of alignment, or if not all
 646        * sequences fit in the visible height
 647        */
 648       if (newStart < getVisibleAlignmentWidth())
 649       {
 650         setStartRes(newStart);
 651       }
 652     }
 653     else
 654     {
 655       setViewportStartAndHeight(endSeq, getViewportHeight());
 656     }
 657   }
 658
 659   public void setWrappedMode(boolean wrapped)
 660   {
 661     wrappedMode = wrapped;
 662   }
 663
 664   public boolean isWrappedMode()
 665   {
 666     return wrappedMode;
 667   }
 668
 669   /**
 670    * Answers the vertical scroll position (0..) to set, given the visible column
 671    * that is at top left.
 672    *
 673    * <pre>
 674    * Example:
 675    *    viewport width 40 columns (0-39, 40-79, 80-119...)
 676    *    column 0 returns scroll position 0
 677    *    columns 1-40 return scroll position 1
 678    *    columns 41-80 return scroll position 2
 679    *    etc
 680    * </pre>
 681    *
 682    * @param topLeftColumn
 683    *          (0..)
 684    * @return
 685    */
 686   public int getWrappedScrollPosition(final int topLeftColumn)
 687   {
 688     int w = getViewportWidth();
 689
 690     /*
 691      * visible whole widths
 692      */
 693     int scroll = topLeftColumn / w;
 694
 695     /*
 696      * add 1 for a part width if there is one
 697      */
 698     scroll += topLeftColumn % w > 0 ? 1 : 0;
 699
 700     return scroll;
 701   }
 702
 703   /**
 704    * Answers the maximum wrapped vertical scroll value, given the column
 705    * position (0..) to show at top left of the visible region.
 706    *
 707    * @param topLeftColumn
 708    * @return
 709    */
 710   public int getWrappedMaxScroll(int topLeftColumn)
 711   {
 712     int scrollPosition = getWrappedScrollPosition(topLeftColumn);
 713
 714     /*
 715      * how many more widths could be drawn after this one?
 716      */
 717     int columnsRemaining = getVisibleAlignmentWidth() - topLeftColumn;
 718     int width = getViewportWidth();
 719     int widthsRemaining = columnsRemaining / width
 720             + (columnsRemaining % width > 0 ? 1 : 0) - 1;
 721     int maxScroll = scrollPosition + widthsRemaining;
 722
 723     return maxScroll;
 724   }
 725 }