src/jexer/teditor/Fragment.java

   1 /*
   2  * Jexer - Java Text User Interface
   3  *
   4  * The MIT License (MIT)
   5  *
   6  * Copyright (C) 2017 Kevin Lamonte
   7  *
   8  * Permission is hereby granted, free of charge, to any person obtaining a
   9  * copy of this software and associated documentation files (the "Software"),
  10  * to deal in the Software without restriction, including without limitation
  11  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  12  * and/or sell copies of the Software, and to permit persons to whom the
  13  * Software is furnished to do so, subject to the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included in
  16  * all copies or substantial portions of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  21  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  23  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  24  * DEALINGS IN THE SOFTWARE.
  25  *
  26  * @author Kevin Lamonte [kevin.lamonte@gmail.com]
  27  * @version 1
  28  */
  29 package jexer.teditor;
  30
  31 /**
  32  * A Fragment is the root "item" to be operated upon by the editor.  Each
  33  * Fragment is a "piece of the stream" that will be rendered.
  34  *
  35  * Fragments are organized as a doubly-linked list.  The have operations for
  36  * traversing the list, splitting a Fragment into two, and joining two
  37  * Fragments into one.
  38  */
  39 public interface Fragment {
  40
  41     /**
  42      * Get the number of graphical cells represented by this text.  Note that
  43      * a Unicode grapheme cluster can take any number of pixels, but this
  44      * editor is intended to be used with a fixed-width font.  So this count
  45      * returns the number of fixed-width cells, NOT the number of grapheme
  46      * clusters.
  47      *
  48      * @return the number of fixed-width cells this fragment's text will
  49      * render to
  50      */
  51     public int getCellCount();
  52
  53     /**
  54      * Get the next Fragment in the list, or null if this Fragment is the
  55      * last node.
  56      *
  57      * @return the next Fragment, or null
  58      */
  59     public Fragment next();
  60
  61     /**
  62      * Set the next Fragment in the list.  Note that this performs no sanity
  63      * checking or modifications on fragment; this function can break
  64      * connectivity in the list.
  65      *
  66      * @param fragment the next Fragment, or null
  67      */
  68     public void setNext(final Fragment fragment);
  69
  70     /**
  71      * Get the previous Fragment in the list, or null if this Fragment is the
  72      * first node.
  73      *
  74      * @return the previous Fragment, or null
  75      */
  76     public Fragment prev();
  77
  78     /**
  79      * Set the previous Fragment in the list.  Note that this performs no
  80      * sanity checking or modifications on fragment; this function can break
  81      * connectivity in the list.
  82      *
  83      * @param fragment the previous Fragment, or null
  84      */
  85     public void setPrev(final Fragment fragment);
  86
  87     /**
  88      * See if this Fragment can be joined with the next Fragment in list.
  89      *
  90      * @return true if the join was possible, false otherwise
  91      */
  92     public boolean isNextJoinable();
  93
  94     /**
  95      * Join this Fragment with the next Fragment in list.
  96      *
  97      * @return true if the join was successful, false otherwise
  98      */
  99     public boolean joinNext();
 100
 101     /**
 102      * See if this Fragment can be joined with the previous Fragment in list.
 103      *
 104      * @return true if the join was possible, false otherwise
 105      */
 106     public boolean isPrevJoinable();
 107
 108     /**
 109      * Join this Fragment with the previous Fragment in list.
 110      *
 111      * @return true if the join was successful, false otherwise
 112      */
 113     public boolean joinPrev();
 114
 115     /**
 116      * Split this Fragment into two.  'this' Fragment will contain length
 117      * cells, 'this.next()' will contain (getCellCount() - length) cells.
 118      *
 119      * @param length the number of cells to leave in this Fragment
 120      * @throws IndexOutOfBoundsException if length is negative, or 0, greater
 121      * than (getCellCount() - 1)
 122      */
 123     public void split(final int length);
 124
 125     /**
 126      * Insert a new Fragment at a position, splitting the contents of this
 127      * Fragment into two around it.  'this' Fragment will contain the cells
 128      * between 0 and index, 'this.next()' will be the inserted fragment, and
 129      * 'this.next().next()' will contain the cells between 'index' and
 130      * getCellCount() - 1.
 131      *
 132      * @param index the number of cells to leave in this Fragment
 133      * @param fragment the Fragment to insert
 134      * @throws IndexOutOfBoundsException if length is negative, or 0, greater
 135      * than (getCellCount() - 1)
 136      */
 137     public void split(final int index, Fragment fragment);
 138
 139     /**
 140      * Insert a new Fragment before this one.
 141      *
 142      * @param fragment the Fragment to insert
 143      */
 144     public void insert(Fragment fragment);
 145
 146     /**
 147      * Append a new Fragment at the end of this one.
 148      *
 149      * @param fragment the Fragment to append
 150      */
 151     public void append(Fragment fragment);
 152
 153     /**
 154      * Delete this Fragment from the list, and return its next().
 155      *
 156      * @return this Fragment's next(), or null if it was at the end of the
 157      * list
 158      */
 159     public Fragment deleteGetNext();
 160
 161     /**
 162      * Delete this Fragment from the list, and return its prev().
 163      *
 164      * @return this Fragment's next(), or null if it was at the beginning of
 165      * the list
 166      */
 167     public Fragment deleteGetPrev();
 168
 169     /**
 170      * Get the anchor position.
 171      *
 172      * @return the anchor number
 173      */
 174     public int getAnchor();
 175
 176     /**
 177      * Set the anchor position.
 178      *
 179      * @param x the new anchor number
 180      */
 181     public void setAnchor(final int x);
 182
 183 }