/**
 * This describes what the GUI can expect the middle, text-storing layer
 * to implement. Note that "DocInterface" is currently taken by something else.
 *<p>
 * In a way, this is similar to DocInterface. But we deal a lot more with
 * pixel-specific issues in this interface.
 *<p>
 * Except we ALSO plan to support a text-based front end. So we also try to support
 * a completely line-oriented front end for display.... while at the same time
 * being forced to deal with internal formatting issues on a pixel basis.
 * (yeah, we 'could' do point-pixel conversions.. but I consider that a waste of
 *  cycles at this point)
 * <p>
 * Try to keep in mind that with this interface, we have to support basically
 * EVERY POSSIBLE ACTION THE USER WILL EVER WANT!!!
 * (SO it's probably going to grow quite a bit, down the road ;-)
 *
 * <p>
 * POINT NOTE, or how to understand coordinates<br>
 * When we expect a point, we expect it in terms of absolute pixels, mapped
 * to the "real" physical page. For example, if a "real" page is determined to be
 * 800x1200 pixels, a click on the top left is NOT -50, -50. It is (0,0)
 * <p>
 * This is on a Document-specific level. The GUI would actually call
 * an instance of class Document, with one of these functions.
 *<p>
 * Note also that there is a middle -> GUI interface, "GUIInterface"
 *
 *<p>
 * @author Philip Brown
 * @version @(#) TextInterface.java 2.2@(#)
 *
 */

import java.awt.Point;
import java.awt.Dimension;

interface TextInterface {

	/**
	 * setCursorByPoint
	 * given a pixel-based coordinate on a page, set our internal
	 * cursor pos
	 * Coordinate should be "raw", which means including margin space.
	 */
	public void setCursorByPoint(int pagenum, Point p);
	/**
	 * and a text-based equivalent
	 */
	public void setCursor(int pagenum, int row, int column);

	/**
	 * This is really for handling arrow keys
	 */
	public void adjCursor(int xval, int yval);

	/**
	 * jump cursor to end of line
	 */
	public void startOfLineCursor();
	public void endOfLineCursor();


	/**
	 * I'm not sure what we'll use the boolean for. But I'm sure
	 * we'll want something.
	 */
	// I dont want to support this yet.
	// I cant think when we'll use it.
	//public boolean addCharAt(int page, int line, int pos, int newchar);

	/**
	 * This just adds a char at the current cursor position,
	 * in current font style
	 */
	public boolean addChar(char newchar);
	/**
	 * Like addChar, but adds a whole string in the "current" font.
	 * Obviously, this is here for efficiency reasons.
	 */
	public void addString(String newchars);

	/* delChar & delCharLeft delete a char at current cursor pos.
	 * note that delCharLeft is used for backspace. That is to say,
	 * it deletes the char to the LEFT of the cursor.<br>
	 * Either function may delete line/pagebreaks.<br>
	 * Either function may delete the 'currently highlighted section',
	 * also!!!<P>
	 */
	public boolean delChar();
	public boolean delCharLeft();

	/** delWord only deletes to 'right' of cursor
	*/
	public boolean delWord(); 

	/* These two match what is in DocInterface, by design */

	/** This works at current cursor position */
	public void insertParagraphBreak() throws java.io.IOException;
	/** This works at current cursor position */
	public void insertPageBreak() throws java.io.IOException;

	public Margins getMargins(int pagenum);
	public void setGlobalMargins(Margins m);
	/** maybe some day we will support this, but in the immediate future,
	 * probably not!
	 */
	public void setMargins(int pagenum, Margins m);


	public void setPageSize(Dimension dim);
	/* note that getPageSize() is a global. Sorry, no varying page sizes
	 * in a single document!
	 */
	public Dimension getPageSize();

	/** Either change font for "next char to be inserted at cursor",
	 * or if something is highlighted, change all highlighted text.
	 * <p>
	 * This covers font name, pointsize, and bold/italic
	 * <p>
	 * @param fontindex is index into FontManager fonts.
	 */
	public void changeFont(int fontindex);

	/**
	 * hopefully, this is self-evident.
	 * I'm not sure what coordinate system we should use, though.
	 * lines, vs absolute positions?
	 * I guess we'll have to support BOTH, actualy. sigh.
	 */
	public void highlightRegion(int startpage, int startline,
				    int startchar,
				    int endpage, int endline, int endchar);
	/** Perhaps this is better to use then the above example?!
	 */
	public void highlightRegion(Point startpoint, Point endpoint);

	/** unhighlight simple turns off any highlight that may be
	 * in effect
	 */
	public void unhighlight();
	/**
	 * returns true if we are keeping track of any highlighted area.
	 */
	public boolean hasHighlight();

	/**
	 * When given data in Point format, we will give back the
	 * translation in y=linenum/x=charnum.
	 * We return in 'Point', cause I dont want to bother making up
	 * a temporary class.
	 * returnval has margins already added.
	 * <p>
	 * I'm not sure when it would be kosher to actually use this.
	 * Perhaps 
	 */
	public Dimension pointToCharpos(int pagenum, Point point);
	/**
	 * similar to pointToCharPos. Given Point.x=charpos, Point.y=linenum,
	 * convert to point.
	 * Except I don't think the GUI should ever actually USE this.
	 * But anyways, we expect margins to be included. Point
	 * should be "raw" coordinate, from visible 1/1scale page.
	 */
	public Point charposToPoint(int pagenum, Dimension point);

	/**
	 *  startpoint MUST be upper-left, and endpoint must be

	 *  lower right point of rectangle that needs redrawing.
	 */
	public void repaintRegion(int pagenum, Point startpoint,
				  Point endpoint);
	/** This version is textcursor based, instead of pixelpoint based
	 */
	public void repaintRegion(int pagenum, Dimension startpos,
				  Dimension endpos);

	public void repaintPage(int pagenum);

	/** We want to be able to support TEXT 'gui's. But to do so,
	 * we need to know whether to use alternate communication methods
	 */
	public void useTextMode(boolean yesno);
}