/**
 *
 * This is the INITIAL DRAFT. Massive revisions are expected, as we
 * work out what we "really" need, later.
 *
 * This Interface describes all functions that the middle layer Document
 * can expect the front-end GUI to implement.<br>
 * This is transitioning to a model where the GUI layer is a lot dumber
 * than the original stuff. Really, the part referenced by this Interface,
 * is not much more than an intelligent printer.
 * Its the other part of the GUI, not covered by this interface,
 * that will probably be the "interesting" bit.
 * <P>
 * The GUI layer is expected to handle display of pages to a user.
 * There may be multiple pages on display (eg side-by-side view)
 * <P>
 * This Interface is called when a change to the actual words/layout in
 * memory has occurred, and the user presumably now wants to see that
 * change.
 *<p>
 * @author Philip Brown
 * @version GUIInterface.java 2.2
 *
 */


interface GUIInterface {
	/**
	 * Note: drawLineAt could also be called
	 * redrawLineAt().
	 * There may be old data there.
	 * And I'm not really sure how best to handle line spacing
	 * issues.
	 * PLUS: I'm not 100% sure how we should best handle actual DRAWING!
	 * Should the GUI interate though each chunk in DocLine, or
	 * should it pass a Graphics back to DocLine, and say
	 * "start drawing 'here'" ?
	 * I suspect we should do the second one, but that sounds like
	 * it would work somewhat slowly!
	 *
	 */
	/* I'm not entirely sure whether the Document should 100% manage
	 * position of things on a pixel-by-pixel basis.
	 * If it does... then there might as
	 * well be a trivial Canvas widget attached to each document.
	 * I dunno.
	 * So thats why there are two drawLineAt() functions listed here.
	 * We should also probably somehow handle zoom. Ugh.
	 */
	//public void drawLineAt(int pagenum, int linenum, DocLine line);
	//public void drawLineAt(int pagenum, int ypixstart, int xpixstart);

	// ORRR.. perhaps we need this instead.
	// This allows the front-end to reselect the font, to handle
	// scaling issues.
	/** drawString is an entry point by the Document, to draw a
	 * particular string somewheres. Unfortunately, this does not
	 * yet address the issue of erasing old data.
	 */
	public void drawString(String str, int page, int xpos, int ypos,
			       int fontindex);

	/* Graphical mode*/
	public void clearPixels(int pagenum, int xstart, int ystart,
				int xend, int yend);

	/* Text mode*/
	public void clearText(int pagenum, int columnstart, int rowstart,
			      int columnend,int rowend);

	/**
	 *'Margins' handles top, bottom, left, right basic margin
	 */
	public void setPageMargins(int pagenum, Margins newmargins);

	/**
	 * This is so that we can have a continuously updated
	 * "Whats the current font" toolbar display. I don't know why usrs
	 * like this, but they seem to. So here it is.
	 * We should probably have a call in the document to turn off
	 * actually updating this.
	 * @param fontindex is index into FontManager cache
	 */
	public void notifyFontChange(int fontindex);

	/** This should be called when and if line spacing, or paragraph
	 * indent has changed, on a particular page.
	 * That way, if the GUI layer is keeping a cache of those things,
	 * it can ask for updates.
	 */
	public void notifyFormatChange(int pagenum);

	/* This is if the contents of a page have changed.
	 * This does NOT mean "Change your current page now"
	 */
	public void notifyPageChange(int pagenum);

	/**
	 * Im not really sure how best to work this
	 * So this is really just a placeholder. Feel free to just
	 * implement this as 'print("we dont do this yet")'
	 *
	 * Contrariwise, maybe this is actually best handled
	 * by a redraw of the affected lines, and the GUI layer has no idea
	 * about drawing highlights.
	 * In other words, this function may never be used.
	 */
	public void highlightArea(int pagestart, int linestart, int charstart,
			     int pageend, int lineend, int charend);

	/* We dont know if the "GUI" will be textbased, or graphics.
	 * Therefore, both these interfaces need to be supported, and
	 * GUI needs to set TextInterface.useTextMode(true), if
	 * it is going to be text-based.
	 */
	/** we do not use Point with this, because it is a muchcalled
	 * routine, and we cant afford the GC costs
	 * Note also that showCursor may be called multiple times
	 * without intervening hideCursor() calls.
	 */
	public void showCursor(int pagenum, int x, int y);
	/* This "TCursor" is "text-mode-cursor, and may go away in v2*/
	public void showTCursor(int pagenum, int column, int row);

	/* Since there is a wide flexibility of how a GUI could choose to
	 * implement the cursor, I dont think there's a point in
	 * passing back the location (which would need TWO methods)
	 */
	public void hideCursor();
}