Some changes. En-route. Most likely broken. ;)
[squirrelmail.git] / plugins / squirrelspell / js / check_me.js
index 852ca0e..1abc4e0 100644 (file)
@@ -1,10 +1,15 @@
 /**
 /**
-   CHECK_ME.JS
-   ------------
-   This JavaScript app is the driving power of the SquirrelSpell's
-   main spellchecker window. Hope you have as much pain figuring
-   it out as it took to write. ;))
-                                                               **/
+ * check_me.js
+ * ------------
+ * This JavaScript app is the driving power of the SquirrelSpell's
+ * main spellchecker window. Hope you have as much pain figuring
+ * it out as it took to write. ;))
+ *
+ * $Id$
+ * 
+ * @author Konstantin Riabitsev <icon@duke.edu> ($Author$)
+ * @version $Date$
+ */
 
 var CurrentError=0;
 var CurrentLocation=0;
 
 var CurrentError=0;
 var CurrentLocation=0;
@@ -13,8 +18,13 @@ var CurrentLine;
 var CurrentSymbol;
 var ChangesMade=false;
 
 var CurrentSymbol;
 var ChangesMade=false;
 
+/**
+ * This function loads spellchecking errors into the form
+ * displayed to the user.
+ *
+ * @return void
+ */
 function populateSqspellForm(){
 function populateSqspellForm(){
-  // this function loads error data into the form.
   CurrentWord=Word=misses[CurrentError];
   WordLocations = locations[CurrentError].split(", ");
   CurrentLoc = WordLocations[CurrentLocation];
   CurrentWord=Word=misses[CurrentError];
   WordLocations = locations[CurrentError].split(", ");
   CurrentLoc = WordLocations[CurrentLocation];
@@ -23,7 +33,7 @@ function populateSqspellForm(){
   } else {
     CurrentLocation++;
   }
   } else {
     CurrentLocation++;
   }
-       
+  
   tmp = CurrentLoc.split(":");
   CurrentLine=parseInt(tmp[0]);
   CurrentSymbol=parseInt(tmp[1]);
   tmp = CurrentLoc.split(":");
   CurrentLine=parseInt(tmp[0]);
   CurrentSymbol=parseInt(tmp[1]);
@@ -55,7 +65,7 @@ function populateSqspellForm(){
     document.forms[0].sqspell_oruse.focus();
     document.forms[0].sqspell_oruse.select();
   }
     document.forms[0].sqspell_oruse.focus();
     document.forms[0].sqspell_oruse.select();
   }
-       
+  
   document.forms[0].sqspell_suggestion.selectedIndex=0;
   if (!document.forms[0].sqspell_oruse.value)
     document.forms[0].sqspell_oruse.value=document.forms[0].sqspell_suggestion.options[document.forms[0].sqspell_suggestion.selectedIndex].value;
   document.forms[0].sqspell_suggestion.selectedIndex=0;
   if (!document.forms[0].sqspell_oruse.value)
     document.forms[0].sqspell_oruse.value=document.forms[0].sqspell_suggestion.options[document.forms[0].sqspell_suggestion.selectedIndex].value;
@@ -64,113 +74,178 @@ function populateSqspellForm(){
   document.forms[0].sqspell_likethis.value=occursTimes;
 }
 
   document.forms[0].sqspell_likethis.value=occursTimes;
 }
 
+
+
+/**
+ * This function updates a line from the message with a new value,
+ * received from the user.
+ *
+ * @param  lLine    line number.
+ * @param  lSymbol  symbol at which the misspelled word starts.
+ * @param  lWord    misspelled word
+ * @param  lNewWord corrected word
+ * @return          void
+ */
 function updateLine(lLine, lSymbol, lWord, lNewWord){
 function updateLine(lLine, lSymbol, lWord, lNewWord){
-  // This function updates the line with new word value
   sqspell_lines[lLine] = sqspell_lines[lLine].substring(0, lSymbol) + lNewWord + sqspell_lines[lLine].substring(lSymbol+lWord.length, sqspell_lines[lLine].length);
   if (lWord.length != lNewWord.length)
     updateSymbol(lLine, lSymbol, lNewWord.length-lWord.length);
   if (!ChangesMade) ChangesMade=true;
 }
   sqspell_lines[lLine] = sqspell_lines[lLine].substring(0, lSymbol) + lNewWord + sqspell_lines[lLine].substring(lSymbol+lWord.length, sqspell_lines[lLine].length);
   if (lWord.length != lNewWord.length)
     updateSymbol(lLine, lSymbol, lNewWord.length-lWord.length);
   if (!ChangesMade) ChangesMade=true;
 }
-     
+
+/**
+ * This function is used to add a word user wishes to place in his/her
+ * user dictionary to the form field for later submission. Since there
+ * is no sane way to pass arrays between javascript and PHP, all words
+ * are concatenated into one strings and separated with a "%".
+ *
+ * @return void
+ */
 function sqspellRemember(){
 function sqspellRemember(){
-  // This function adds the word to the field in the form to be later
-  // submitted and added to the user dictionary.
   CurrentWord = misses[CurrentError] + "%";
   document.forms[0].words.value += CurrentWord;
   CurrentWord = misses[CurrentError] + "%";
   document.forms[0].words.value += CurrentWord;
+  /**
+   * Now ignore all occurances of this word.
+   */
   sqspellIgnoreAll();
 }
 
   sqspellIgnoreAll();
 }
 
-     
+/**
+ * This function is called when the "Change" button is pressed.
+ *
+ * @return void
+ */
 function sqspellChange(){
 function sqspellChange(){
-  // Called when pressed the "Change" button
   CurrentWord = misses[CurrentError];
   NewWord=document.forms[0].sqspell_oruse.value;
   updateLine(CurrentLine, CurrentSymbol, CurrentWord, NewWord);
   proceed();
 }
 
   CurrentWord = misses[CurrentError];
   NewWord=document.forms[0].sqspell_oruse.value;
   updateLine(CurrentLine, CurrentSymbol, CurrentWord, NewWord);
   proceed();
 }
 
+/**
+ * This function is called when the "Change All" button is pressed.
+ *
+ * @return void
+ */
 function sqspellChangeAll(){
   // Called when pressed the "Change All" button
   allLoc = locations[CurrentError].split(", ");
   if (allLoc.length==1) {
 function sqspellChangeAll(){
   // Called when pressed the "Change All" button
   allLoc = locations[CurrentError].split(", ");
   if (allLoc.length==1) {
-    // There's no need to "change all", only one occurance.
+    /**
+     * There's no need to "change all", only one occurance of this
+     * word in the whole text.
+     */
     sqspellChange();
     return;
   }
     sqspellChange();
     return;
   }
-       
+  /**
+   * Dark magic.
+   */
   NewWord=document.forms[0].sqspell_oruse.value;
   CurrentWord = misses[CurrentError];
   for (z=CurrentLocation-1; z<allLoc.length; z++){
     tmp = allLoc[z].split(":");
     lLine = parseInt(tmp[0]);  lSymbol = parseInt(tmp[1]);
     updateLine(lLine, lSymbol, CurrentWord, NewWord);
   NewWord=document.forms[0].sqspell_oruse.value;
   CurrentWord = misses[CurrentError];
   for (z=CurrentLocation-1; z<allLoc.length; z++){
     tmp = allLoc[z].split(":");
     lLine = parseInt(tmp[0]);  lSymbol = parseInt(tmp[1]);
     updateLine(lLine, lSymbol, CurrentWord, NewWord);
-    // Load it again to reflect the changes in symbol data
+    /**
+     * Load it again to reflect the changes in symbol data
+     */
     allLoc = locations[CurrentError].split(", ");
     allLoc = locations[CurrentError].split(", ");
-  }
-       
+  }       
   CurrentLocation=0;
   proceed();
 }
 
   CurrentLocation=0;
   proceed();
 }
 
+/**
+ * This function is only here for consistency. It is called when
+ * "Ignore" is pressed.
+ *
+ * @return void
+ */
 function sqspellIgnore(){
 function sqspellIgnore(){
-  // Only here for consistency. Called when pressed the "Ignore" button
   proceed();
 }
 
   proceed();
 }
 
+/**
+ * This function is called when the "Ignore All" button is pressed.
+ * 
+ * @return void
+ */
 function sqspellIgnoreAll(){
 function sqspellIgnoreAll(){
-  // Called when pressed the "Ignore All" button
   CurrentLocation=0;
   proceed();
 }
 
   CurrentLocation=0;
   proceed();
 }
 
+/**
+ * This function clears the options in a select box "sqspell_suggestions".
+ *
+ * @return void
+ */
 function clearSqspellForm(){
 function clearSqspellForm(){
-  // Clears the options in selectbox "sqspell_suggestions"
   for (i=0; i<document.forms[0].sqspell_suggestion.length; i++){
     document.forms[0].sqspell_suggestion.options[i]=null;
   }
        
   for (i=0; i<document.forms[0].sqspell_suggestion.length; i++){
     document.forms[0].sqspell_suggestion.options[i]=null;
   }
        
-  // Now, I've been instructed by the Netscape Developer docs to call
-  // history.go(0) to refresh the page after I've changed the options.
-  // However, that brings so many pains with it that I just decided not
-  // to do it. It works like it is in Netscape 4.x. If there are problems
-  // in earlier versions of Netscape, then oh well. I'm not THAT anxious
-  // to have it working on all browsers... ;)
-
+  /**
+   * Now, I've been instructed by the Netscape Developer docs to call
+   * history.go(0) to refresh the page after I've changed the options.
+   * However, that brings so many pains with it that I just decided not
+   * to do it. It works like it is in Netscape 4.x. If there are problems
+   * in earlier versions of Netscape, then oh well. I'm not THAT anxious
+   * to have it working on all browsers... ;)
+   */
   document.forms[0].sqspell_oruse.value="";
 }
 
   document.forms[0].sqspell_oruse.value="";
 }
 
+/**
+ * This function goes on to the next error, or finishes nicely if
+ * no more errors are available.
+ *
+ * @return void
+ */
 function proceed(){
 function proceed(){
-  // Goes on to the next error if any, or finishes.
   if (!CurrentLocation) CurrentError++;
   if (misses[CurrentError]){
     clearSqspellForm();
     populateSqspellForm();
   } else {
     if (ChangesMade || document.forms[0].words.value){
   if (!CurrentLocation) CurrentError++;
   if (misses[CurrentError]){
     clearSqspellForm();
     populateSqspellForm();
   } else {
     if (ChangesMade || document.forms[0].words.value){
-      if (confirm("SpellCheck complete. Commit Changes?"))
+      if (confirm(ui_completed))
        sqspellCommitChanges();
        sqspellCommitChanges();
-       else self.close();
+      else self.close();
     } else {
     } else {
-      confirm ("No changes were made.");
+      confirm (ui_nochange);
       self.close();
     }
   }
 }
 
       self.close();
     }
   }
 }
 
+/**
+ * This function updates the symbol locations after there have been
+ * word length changes in the lines. Otherwise SquirrelSpell barfs all
+ * over your message... ;)
+ *
+ * @param  lLine      line number on which the error occurs
+ * @param  lSymbol    symbol number at which error occurs
+ * @param  difference the difference in length between the old word
+ *                    and the new word. Can be negative or positive.
+ * @return            void
+ */
 function updateSymbol(lLine, lSymbol, difference){
 function updateSymbol(lLine, lSymbol, difference){
-  // Now, I will admit that this is not the best way to do stuff,
-  // However that's the solution I've come up with.
-  // This function updates the symbol locations after there have been
-  // word length changes in the lines. Otherwise SquirrelSpell barfs all
-  // over your message... ;)
-  //
-  // If you are wondering why I didn't use two-dimensional arrays instead,
-  // well, sometimes there will be a long line with an error close to the
-  // end of it, so the coordinates would be something like 2,98 and 
-  // some Javascript implementations will create 98 empty members of an 
-  // array just to have a filled number 98. This is too resource-wasteful 
-  // and I have decided to go with the below solution instead. It takes 
-  // a little more processing, but it saves a lot on memory.
+  /** 
+   * Now, I will admit that this is not the best way to do stuff,
+   * However that's the solution I've come up with.
+   *
+   * If you are wondering why I didn't use two-dimensional arrays instead,
+   * well, sometimes there will be a long line with an error close to the
+   * end of it, so the coordinates would be something like 2,98 and 
+   * some Javascript implementations will create 98 empty members of an 
+   * array just to have a filled number 98. This is too resource-wasteful 
+   * and I have decided to go with the below solution instead. It takes 
+   * a little more processing, but it saves a lot on memory.
+   *
+   * It just looks heinous. In real life it's really nice and sane. ;)
+   */
        
   for (i=0; i<misses.length; i++){
     if(locations[i].indexOf(lLine + ":") >= 0){
        
   for (i=0; i<misses.length; i++){
     if(locations[i].indexOf(lLine + ":") >= 0){
@@ -190,32 +265,36 @@ function updateSymbol(lLine, lSymbol, difference){
   }
 }
 
   }
 }
 
+/**
+ * This function writes the changes back into the compose form.
+ *
+ * @return void
+ */
 function sqspellCommitChanges(){
 function sqspellCommitChanges(){
-  // Write the changes back into the compose form
-  if (navigator.appName.indexOf("Microsoft")==0){
-    // MSIE doesn't have array.shift()
-    newSubject = sqspell_lines[0];
-    newBody = "";
-    for (i=1; i<sqspell_lines.length; i++){
-      if (i!=1) newBody+="\r\n";
-      newBody += sqspell_lines[i];
-    }
-  } else {
-    newSubject = sqspell_lines.shift();
-    newBody = sqspell_lines.join("\n");
+  newSubject = sqspell_lines[0];
+  newBody = "";
+  for (i=1; i<sqspell_lines.length; i++){
+    if (i!=1) newBody+="\r\n";
+    newBody += sqspell_lines[i];
   }
   }
-
+  
   opener.document.forms[0].subject.value=newSubject;
   opener.document.forms[0].body.value=newBody;
   opener.document.forms[0].subject.value=newSubject;
   opener.document.forms[0].body.value=newBody;
-       
-  // See if any words were added to the dictionary.
+  
+  /**
+   * See if any words were added to the dictionary.
+   */
   if (document.forms[0].words.value){
   if (document.forms[0].words.value){
-    // yeppers
-    document.forms[0].sqspell_line_area.value="Now saving your personal dictionary... Please wait.";
-    // pass focus to the parent so we can do background save.
+    /**
+     * Yeppers.
+     */
+    document.forms[0].sqspell_line_area.value=ui_wait;
+    /**
+     * pass focus to the parent so we can do background save.
+     */
     window.opener.focus();
     document.forms[0].submit();
   } else {
     window.opener.focus();
     document.forms[0].submit();
   } else {
-     self.close();
+    self.close();
   }
 }
   }
 }