/*
 * Created on 2004-7-27
 */
package mvc143;
import java.util.List;
/** 
 * This interface provides the methods for overall control of a Boggle Game.
 * For CSE143, the concrete Controller classes must be located in 
 * boggle.controller.BoggleController.java
 * <br />
 * The constructor must take NO parameters.
 * The constructor must create the Model and View.
 * </br>
 * The class must have a main method which simply creates an instance of
 * the Controller.  After that, once the View is in execution, things
 * should run on their own.  There are no defined command-line arguments for main.
 * <br />IMPORTANT NOTE #1! :
 * Many of the methods are simply "pass-throughs" to the Model.  Don't keep 
 * duplicate information in both modules.  For example: what characters are
 * on the board; how many rows and columns there are, etc. all are part of 
 * the Model, even though this Controller interface has methods which allow the Controller
 * to be queried for them.  Before implementing any Controller methods, it
 * is recommended that you be thoroughly familiar with what is in the other
 * two modules to avoid duplication.
 * <br />
 * The necessary resource files (if any), like dictionary and boards, 
 * are recommended to be located in the directory of the controller.
 * <br />
 * IMPORTANT NOTE #2 :
 * You must define these two public static fields to specify the author and a brief description.
 * as follows:<br />
 *	public static final String author = " ... ";<br />
 *  public static final String description = " ... ";
 * <br />
  "authors" should identify the authors in some fashion, but pseudonyms or
  nicknames are acceptable.  "description" should give a brief description
  of the module, especially if there are any unexpected or unique features 
  about it.  The information in both fields may be visible to the general
  public, indefinitely into the future, so do not place any information here
  which you do not wish to be publicly available.
 * @author xm
 *
 */
public interface IBoggleController {

 
 /**
  * This method will add the letter specified by row and col to the proposal string.
  * It will check if the position is valid or not before adding.
  * @param row the row from which the letter comes.
  * @param col the column from which the letter comes.
  * @return true, if the letter is successfully added;
  *         false, otherwise .
  */
 public boolean addToProposal(int row, int col);
 
 /**
  * Remove the last character in the proposed word.
  * @return true, if succeessful,
  *		   false, if not successful, or of the remove operation
  *is not suported by the implemention.
  */
 public boolean removeLetterFromProposal();
 
 /**
  * When the user submits the proposed word,
  * this method will check if the word is valid or not. 
  * The score will be updated then.
  * @return -1 means the word was invalid.  All other return values should
  * indicate success, but no meaning is defined for them.
  */
 public int submitProposal();
 
 /**
  *The current word proposal will be cleared.
  */
 public void newProposal();
 
  /**
  * Determine if the current word proposal is empty or not, i.e., whether
  * any letters have been added to it. 
  * It may or may not be useful in your implementation, but keep it for someone's need.
  *@return true if the proposal is empty
  *        false otherwise
  */
 public boolean isNewProposal(); 


 /**
  * Get the number of columns in the board.
  * @return the cols of the boggle board
  */
 public int getBoardCols();
 
 /**
  * get the number of rows in the board.
  * @return the rows of the boggle board
  */
 public int getBoardRows();
 
 /**
  * return the character at the position specified by row and col.  (Implement
  * this by asking the model for the information).
  * @param row an integer specifying the row in the board
  * @param col an integer specifying the col in the board
  * @return the character, or
  *         -1, if the position is not valid
  */
 public int getLetterInBoard(int row, int col);
 
 
 
 /**
  * Set the time duration of one game.  If no time is ever set, then the
  * default of three minutes (as specified by official Boggle rules)
  * should be used.
  * @param gametime the long type integer to specify the duration in milliseconds.
  */
 public void setGameTime(long gametime);
 
 /**
  * Get the total time duration of a game in milliseconds.
  * @return a long type integer to specify the time duration of one game.
  */
 public long getGameTime();
 
 /**
  * Get the remaining left in the current game.
  * @return the time remained for one game in milliseconds, if a game is in
  * progress; return 0 if no game is in progress.
  */
 public long getMillisRemaining();
 /**
  * Start the timer, if the timer is stopped 
  * (create a new timer and start it, if there wasn't already a timer)
  */
 public void startTimer();
 /**
  * Start a new game, with a new internally generated board.
  * Starting a game may involve inititalizing or reinitializing
  * various other parameters and features of the board.
  */
 public void startGame();
 
 /**
  * Start a new game, intializing the board from the file given. 
  * Starting a new game may also involve inititalizing or reinitializing
  * various other parameters and features of the game.
  * If the fileID is null or the file read fails, leave the board unchanged,
  * supposing we have already have one. 
  *@param fileID the location of the board to use.
  */
 public void startGame(String fileID);
 
 /**
  * End the current running game.
  *
  */
 public void endGame();
 
 
 /**
  * This method will tell if the game is ended or not.
  * Typically when the time is up, the game should be ended by controller 
  * automatically;
  * everything will be stopped and waiting for start again
  * @return return true, if the game is still running
  *                false, if a game is not in progress.
  */
 public boolean isRunning();
 /**
  * Get the score for the current game.
  * @return the current score
  */
 public int getScore();
 
 /**
  * Return a message which this components wants to be visible to the user.
  * It is strongly encouraged that this message contain the current status
  * of the proposal (for example, the proposal itself; a message indicating
  * rejection or acceptance if the proposal was recently submitted, etc.)
  * For example, the View might choose to periodically display the message. 
  * @return a string containing the status message
  */
 public String getStatus();
 


  /**
   * Get the words history from the Model.  
   * The idea of "history" is to let the model keep track of all the words 
   * the user has already got correct in the current game.
   * @return a list of history information; if there is no history or a history
   * is simly not implemented, should return empty List; should not return null.
   * 
   */
  public List getWordsHistory();
 
 
 
 /**
   * Load a dictionary from a resource (file). 
   * @param fileID a string to specify the place to load the resource from.
   * @return true if succeed
   *         false if not succeed or no file specified
   */
  public boolean loadDictionary(String fileID);

  /**
   * Add new words to dictionary without changing what
   * was already there.
   *  Matching of words from
   * the dictionary is supposed to be case-insensitive.  Although this
   * method is not responsible for matching, it may wish to convert all words
   * to upper case before storing them.
   * @param words an array of strings to store in the dictionary
   */
  public void addToDictionary(String[] words);


 
 /** Terminate the application.  Among other things,
  * call the terminate methods of the Model and the View so that they can
  * perform any required clean-up.
  *
  */
 public void terminateApplication();
}