src/com/googlecode/lanterna/TerminalPosition.java

   1 /*
   2  * This file is part of lanterna (http://code.google.com/p/lanterna/).
   3  *
   4  * lanterna is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published by
   6  * the Free Software Foundation, either version 3 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public License
  15  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Copyright (C) 2010-2015 Martin
  18  */
  19 package com.googlecode.lanterna;
  20
  21 /**
  22  * A 2-d position in 'terminal space'. Please note that the coordinates are 0-indexed, meaning 0x0 is the top left
  23  * corner of the terminal. This object is immutable so you cannot change it after it has been created. Instead, you
  24  * can easily create modified 'clones' by using the 'with' methods.
  25  *
  26  * @author Martin
  27  */
  28 public class TerminalPosition {
  29
  30     /**
  31      * Constant for the top-left corner (0x0)
  32      */
  33     public static final TerminalPosition TOP_LEFT_CORNER = new TerminalPosition(0, 0);
  34     /**
  35      * Constant for the 1x1 position (one offset in both directions from top-left)
  36      */
  37     public static final TerminalPosition OFFSET_1x1 = new TerminalPosition(1, 1);
  38
  39     private final int row;
  40     private final int column;
  41
  42     /**
  43      * Creates a new TerminalPosition object, which represents a location on the screen. There is no check to verify
  44      * that the position you specified is within the size of the current terminal and you can specify negative positions
  45      * as well.
  46      *
  47      * @param column Column of the location, or the "x" coordinate, zero indexed (the first column is 0)
  48      * @param row Row of the location, or the "y" coordinate, zero indexed (the first row is 0)
  49      */
  50     public TerminalPosition(int column, int row) {
  51         this.row = row;
  52         this.column = column;
  53     }
  54
  55     /**
  56      * Returns the index of the column this position is representing, zero indexed (the first column has index 0).
  57      * @return Index of the column this position has
  58      */
  59     public int getColumn() {
  60         return column;
  61     }
  62
  63     /**
  64      * Returns the index of the row this position is representing, zero indexed (the first row has index 0)
  65      * @return Index of the row this position has
  66      */
  67     public int getRow() {
  68         return row;
  69     }
  70
  71     /**
  72      * Creates a new TerminalPosition object representing a position with the same column index as this but with a
  73      * supplied row index.
  74      * @param row Index of the row for the new position
  75      * @return A TerminalPosition object with the same column as this but with a specified row index
  76      */
  77     public TerminalPosition withRow(int row) {
  78         if(row == 0 && this.column == 0) {
  79             return TOP_LEFT_CORNER;
  80         }
  81         return new TerminalPosition(this.column, row);
  82     }
  83
  84     /**
  85      * Creates a new TerminalPosition object representing a position with the same row index as this but with a
  86      * supplied column index.
  87      * @param column Index of the column for the new position
  88      * @return A TerminalPosition object with the same row as this but with a specified column index
  89      */
  90     public TerminalPosition withColumn(int column) {
  91         if(column == 0 && this.row == 0) {
  92             return TOP_LEFT_CORNER;
  93         }
  94         return new TerminalPosition(column, this.row);
  95     }
  96
  97     /**
  98      * Creates a new TerminalPosition object representing a position on the same row, but with a column offset by a
  99      * supplied value. Calling this method with delta 0 will return this, calling it with a positive delta will return
 100      * a terminal position <i>delta</i> number of columns to the right and for negative numbers the same to the left.
 101      * @param delta Column offset
 102      * @return New terminal position based off this one but with an applied offset
 103      */
 104     public TerminalPosition withRelativeColumn(int delta) {
 105         if(delta == 0) {
 106             return this;
 107         }
 108         return withColumn(column + delta);
 109     }
 110
 111     /**
 112      * Creates a new TerminalPosition object representing a position on the same column, but with a row offset by a
 113      * supplied value. Calling this method with delta 0 will return this, calling it with a positive delta will return
 114      * a terminal position <i>delta</i> number of rows to the down and for negative numbers the same up.
 115      * @param delta Row offset
 116      * @return New terminal position based off this one but with an applied offset
 117      */
 118     public TerminalPosition withRelativeRow(int delta) {
 119         if(delta == 0) {
 120             return this;
 121         }
 122         return withRow(row + delta);
 123     }
 124
 125     /**
 126      * Creates a new TerminalPosition object that is 'translated' by an amount of rows and columns specified by another
 127      * TerminalPosition. Same as calling
 128      * <code>withRelativeRow(translate.getRow()).withRelativeColumn(translate.getColumn())</code>
 129      * @param translate How many columns and rows to translate
 130      * @return New TerminalPosition that is the result of the original with added translation
 131      */
 132     public TerminalPosition withRelative(TerminalPosition translate) {
 133         return withRelative(translate.getColumn(), translate.getRow());
 134     }
 135
 136     /**
 137      * Creates a new TerminalPosition object that is 'translated' by an amount of rows and columns specified by the two
 138      * parameters. Same as calling
 139      * <code>withRelativeRow(deltaRow).withRelativeColumn(deltaColumn)</code>
 140      * @param deltaColumn How many columns to move from the current position in the new TerminalPosition
 141      * @param deltaRow How many rows to move from the current position in the new TerminalPosition
 142      * @return New TerminalPosition that is the result of the original position with added translation
 143      */
 144     public TerminalPosition withRelative(int deltaColumn, int deltaRow) {
 145         return withRelativeRow(deltaRow).withRelativeColumn(deltaColumn);
 146     }
 147
 148     @Override
 149     public String toString() {
 150         return "[" + column + ":" + row + "]";
 151     }
 152
 153     @Override
 154     public int hashCode() {
 155         int hash = 3;
 156         hash = 23 * hash + this.row;
 157         hash = 23 * hash + this.column;
 158         return hash;
 159     }
 160
 161     public boolean equals(int columnIndex, int rowIndex) {
 162         return this.column == columnIndex &&
 163                 this.row == rowIndex;
 164     }
 165
 166     @Override
 167     public boolean equals(Object obj) {
 168         if (obj == null) {
 169             return false;
 170         }
 171         if (getClass() != obj.getClass()) {
 172             return false;
 173         }
 174         final TerminalPosition other = (TerminalPosition) obj;
 175         return this.row == other.row && this.column == other.column;
 176     }
 177 }