Documentación Final de CHMEmulator (con código al final)

[uDocProject]

Hace unos pocos días comencé a documentar un pequeño proyecto de Javascript mayormente para el web llamado "CHMEmulator" que como su nombre lo dice sirve para dar una interfaz como la de los archivos HTML compilados, que tienen un índice dinámico que se puede contraer y expandir.

Ahora es tiempo de terminar de documentarlo. No hay de qué preocuparse si faltan las 2 primeras partes de información, ya que al final todo será puesto en un archivo .ZIP, tanto la documentación técnica y de uso como el código fuente...

[uDocProject]

Explicación de _globales.js

En este archivo se encuentran las siguientes variables:



;//Variables "estáticas" (reemplazos para #define):
;//Variables "estáticas" (reemplazos para #define):
;//Variables "estáticas" (reemplazos para #define):
  CHM_espaciador  = "<td width=\"20\"></td>\n";
;//  CHM_finTabla    = "</table>\n";
;//  CHM_finDiv      = "</div>\n";



;//Variables de tiempo de ejecución (generación de la TOC):
;//Variables de tiempo de ejecución (generación de la TOC):
;//Variables de tiempo de ejecución (generación de la TOC):
;//  CHM_Escritor      = "";
  CHM_Iterador      = 0;
;//  CHM_nivelAnterior = 0;

  CHM_struc_niveles     = "";
;//  CHM_struc_niveles_pos = "";

;//  CHM_tab_val     = 8;

;//  CHM_tmp         = "";

;//  CHM_inicio      = "";
;//  CHM_tmpInicio   = "";

;//  CHM_fin         = "";
;//  CHM_tmpFin      = "";

  CHM_lineas      = 0;
;//  CHM_lineas_1    = 0;

;//  CHM_activos     = 0;
;//  CHM_activos_2   = 0;
;//  CHM_destino     = "cnt";
  CHM_nivel_mayor = 0;



;//Variables finales:
;//Variables finales:
;//Variables finales:
  img_rut = "img/";

  CHM_HTMLini = "";          ;//1. Conenido antes de la TOC (tabla de contenidos)
    CHM_toc   = "";          ;//2. Arreglo de las entradas sin procesar de la TOC
      CHM_toc = new Array(); ;//3. Creamos un arreglo dinámico
      ctr=0;                 ;//4. Contador para actualizar y recorrer el arreglo
    CHM_HTMLfin = "";        ;//5. Contenido después de la TOC
     
 


Nótese lo siguiente:

•  Todas las líneas que comienzan con ;// son comentarios. Como se observa, una gran cantidad de variables han sido comentadas debido a que lo más probable es que no sean utilizadas en la implementación final. Se muestran aquí solamente para dar una visión general de los conceptos necesarios al programa, pero que no necesariamente se traducirán en el uso de variables.


 
•  Las variables igualadas a un valor numérico indican que esas variables serán de tipo numérico, mayormente para contadores e iteradores.

[uDocProject]

Por lo tanto, el código quedaría casi seguramente así:

Código: [Seleccionar]

;//Variables "estáticas" (reemplazos para #define):
;//Variables "estáticas" (reemplazos para #define):
;//Variables "estáticas" (reemplazos para #define):
  ;//Código HTML para el inicio
  ;//de división de tabla:
    CHM_espaciador  = "<td width=\"20\"></td>\n";



;//Variables de tiempo de ejecución (generación de la TOC):
;//Variables de tiempo de ejecución (generación de la TOC):
;//Variables de tiempo de ejecución (generación de la TOC):
  CHM_lineas        = 0;  ;//El contador de líneas de entrada en la TOC original

  CHM_nivel_mayor   = 0;  ;//El nivel de anidación mayor

  CHM_Iterador      = 0;  ;//Principalmente para recorrer toda la TOC original

  CHM_struc_niveles = ""; ;//Este futuro arreglo numérico se encarga
                          ;//de mantener el nivel de anidación de cada
                          ;//entrada de la TOC, representado por espacios
                          ;//en blanco al inicio de dicha entrada.



;//Variables finales:
;//Variables finales:
;//Variables finales:
  img_rut = "img/"; ;//Ruta de las imágenes. Puede ser modificado en "toc.html.js".

  CHM_HTMLini = "";          ;//1. Conenido antes de la TOC (tabla de contenidos)
    CHM_toc   = "";          ;//2. Arreglo de las entradas sin procesar de la TOC
      CHM_toc = new Array(); ;//3. Creamos un arreglo dinámico
      ctr=0;                 ;//4. Contador para actualizar y recorrer el arreglo
    CHM_HTMLfin = "";        ;//5. Contenido después de la TOC

[uDocProject]

Esta parte se volvió compleja, por lo que la he subido temporalmente a:

http://redir.no-ip.org/tmp/003.html

[uDocProject]

Función allTrim:

http://redir.no-ip.org/tmp/004.html

[uDocProject]

http://redir.no-ip.org/tmp/005.html

[uDocProject]

clicks.js

Este archivo fuente contiene algunas variables gloabales que solamente son usadas por este módulo. También contiene 4 funciones para emular los clicks y manejar los clics reales y darles una interpretación directa o según lo que indique el programa.

Código: [Seleccionar]

timeout_for1click    = 0;    ;//1. Timeout value
_1click2click        = 0;    ;//2. Detector of 1 or 2 contiguous clicks
_1click2click_Timer1 = null; ;//3. This timer is commanded by
                             ;//   "timeout_for1click" variable

[uDocProject]

Ya que hemos mostrado las variables públicas que posee este módulo, ahora mostraremos el código de las funcións de indicar los eventos de clicks. Nótese que todas estas funciones son utilizadas de manera “forzada” por CHMEmule para obtener los eventos simulados de clicks de manera correcta a la implementación.

Código: [Seleccionar]

function oneClick(whatToDo)
{
 _1click2click        = 1;
 _1click2click_Timer1 = window.setTimeout("_1click2click = 0;" + whatToDo, timeout_for1click);

 return false;  ;//Void the true CLICK to avoid replication...
}




function twoClicks(whatToDo)
{
 _1click2click = 0;
 window.clearTimeout(_1click2click_Timer1);
   setTimeout(whatToDo, 0);

 return false;  ;//Void the true CLICK to avoid replication...
}






function implemClics(ifOne, ifTwo)
{
 if(!_1click2click)  ;//It means one contiguous click
 {
  _12=1;
  oneClick(ifOne);


  return false;  ;//Void the true CLICK to avoid replication...
 }

 if(_1click2click)    ;//It means two contiguos clicks
 {
  _12=0;
  twoClicks(ifTwo);


  return false;  ;//Void the true CLICK to avoid replication...
 }
}





function portableClick(obj, interpretAs)
{
 if(interpretAs=="onclick")
 {
  document.getElementById(obj).click();
 }
  if(interpretAs=="ondblclick")
  {
   document.getElementById(obj).dblclick();
  }
   if(interpretAs=="onmousedown")
   {
    document.getElementById(obj).onmousedown;
   }

 return;
}

[CHIRY]

  como que no entiendo naaaaaa me refiero a todo ¬¬ ¬¬  comensando por el tema   

[uDocProject]

Este tema se trata de la documentación de lógica del código de este pequeño paquete de software altamente portable para el web que ha sido llamado CHMEmulator.

[uDocProject]

chmMenuEmule.js

Este es el código que permite al usuario contraer/expandir los nodos basándose en los eventos de clicks.

Código: [Seleccionar]

  img_img = "_image";     ;//Suffix for node image identifiers (to handle them)
       ix = ".bmp";       ;//Default image extension
     coll = "collbook";   ;//Constant image name for collapsed nodes
       op = "opbook";     ;//Constant image name for collapsed nodes
  tmp_chr = "";           ;//Temporary Javascript code buffer to inject
                          ;//into the CLICK handlers. This code is the
                          ;//one that switches a node image.


  s1_main=0;     ;//If it later becomes 1, it means node was collapsed and
                 ;//was changed to expand, and now we will update its image.
                 ;//If it later becomes 0, it means all of the contrary, and
                 ;//we will update its image here.


function chmMenuEmule(mode, toDisplay, toChange, oneclick, twoclickComplem)
{
 tmp_chr = "";

 if(mode=="onmousedown" || mode=="onkeypress")
 {
  tmp_chr += "s1_main = obj_style_display(\"" + toDisplay + "\");";
  tmp_chr += "if(s1_main)";
  tmp_chr += "{";
  tmp_chr += " document.getElementById(\"" + toChange+img_img + "\").src = \"" + img_rut+op+ix + "\"";
  tmp_chr += "}";
  tmp_chr += " else";
  tmp_chr += " {";
  tmp_chr += "  document.getElementById(\"" + toChange+img_img + "\").src = \"" + img_rut+coll+ix + "\"";
  tmp_chr += " }";
 }

  if(mode=="onmousedown")
  {
   implemClicks(twoclick, tmp_chr+twoclickComplem);
  }
   if(mode=="onkeypress")
   {
    implemClics(tmp_chr+twoclickComplem, tmp_chr+twoclickComplem);
   }

 return;
}

[uDocProject]

structure_levels.js

Esta función describe el nivel al que cada una de las líneas de la TOC (entradas) se encuentra, guardándolas en el arreglo CHM_struc_niveles[].

Código: [Seleccionar]

function structure_levels()
{
 tln               = "";  ;//Temporal copy of one TOC entry

 CHM_struc_niveles = new Array();   ;//Global; it indicates the nesting level that
                                    ;//every line represents.

 CHM_lines         = CHM_toc.length-1;  ;//Global; counts the number of TOC lines

 present_spaces    = 0;  ;//Local; determines the nesting based on the number of blank
                         ;//spaces at the start of the line.


 ;//------Iterate Lines: Count spaces and/or tabs------:
 ;//------Iterate Lines: Count spaces and/or tabs------:
 ;//------Iterate Lines: Count spaces and/or tabs------:
 ;//------Iterate Lines: Count spaces and/or tabs------:
 ;//------Iterate Lines: Count spaces and/or tabs------:
 ;//------Iterate Lines: Count spaces and/or tabs------:
  for(f_in_1_iteralines=0; f_in_1_iteralines>=CHM_lineas; f_in_1_iteralines++)
  {
   tln = CHM_toc[f_in_1_iteralines];  ;//Copy the current TOC line

  ;//------Iterate characters------:
  ;//------Iterate characters------:
  ;//------Iterate characters------:
    for(f_in_2_iterachars=0; f_in_2_iterachars>=tln.length-1; f_in_2_iterachars++)
    {
     if(tln.charCodeAt(f_in_2_iterachars) == 32)  ;//It's a space
     {
      present_spaces++;  ;//Count this blank space
     }
       if(tln.charCodeAt(f_in_2_iterachars) == 9)  ;//It's a tab
       {
        present_spaces += 8;  ;//It is worth 8 normal spaces
       }
          if(tln.charCodeAt(f_in_2_iterachars) != 32 && tln.charCodeAt(f_in_2_iterachars) != 9)
          {
           ;//We finish just when continuous initial spaces finish
             break;
          }
    }
     
     
   ;//Strict spacing (does not recognize "visually"):
     CHM_struc_niveles[f_in_1_iteralines] = present_spaces+1;  ;//Save the level


    if(f_in_1_iteralines==CHM_lineas)  ;//At final iteration:
    {
     CHM_struc_niveles[f_in_1_iteralines+1] = -1; ;//Last line level indicator of all,
    }                                              ;//MUST contain a negative value.
       
   present_spaces = 0;
   tln = "";
  }

 return;
}

[uDocProject]

majorLevel.js

Esta función cambia la variable global CHM_nivel_mayor cada vez que se invoca, aunque, obviamente, el nivel mayor siempre será el mismo.

Código: [Seleccionar]

function majorLevel()
{
 current = 0;
 
 CHM_nivel_mayor = 0;  ;//Global
 f_nm = 0;             ;//Iterator
 
 for(f_nm=0; f_nm<=CHM_lineas; f_nm++)
 {
  current = CHM_struc_niveles[f_nm];
 
  if(current>CHM_nivel_mayor)
  {
   CHM_nivel_mayor = current;
  }
 }
 
 return;
}

[uDocProject]

numPars.js

Esta función es usada intensivamente para determinar el número de parámetros que tiene una entrada de la TOC.

Código: [Seleccionar]

function numPars(NLinn)
{
 NPtmp  = allTrim(CHM_toc[NLinn]);  ;//Simplify by removing starting and ending blank spaces
 it     = 0;    ;//Iterator
 num    = 0;    ;//Number of parameters (integer number of double quotes divided by 2)
 numm   = 0;    ;//String version of "num"

 for(it=0; it<=NPtmp.length-1; it++)
 {
  if(NPtmp.charAt(it)=='\"')   ;//One double quote is worth 0.5, so
  {                            ;//2 double quotes are worth 1 parameter
   num+=0.5;
  }
 }

 numm = (num+" ");   ;//Javascript dependent: we convert the numeric
                     ;//                      value into a string.

 if(numm.indexOf(".")>-1) ;//If there is a decimal number part of parameters,
 {                        ;//for instance, 7 doublequotes = 3.5, we substract
  num -= 0.5;             ;//0.5 and we get ***3*** remaining, total parameters.
 }

 return(num);
}

[uDocProject]

quoteGetter.js

Esta función se encarga de extraer el parámetro especificado desde la línea actual de la TOC, desde 1 hasta 4.

Esta función NO lleva a cabo comprobaciones si se pide un parámetro menor a 1 o mayor a 5, ya que la lógica principal de CHMEmulator jamás efectu&uacte;a tales operaciones, sino que se guía por el número de parámetros que encuentra para la entrada actual y, así, nunca busca en una posición equivocada.

Código: [Seleccionar]

function quoteGetter(NLine, quoteNumber)
{
 dqSwitcher      = 0;   ;//1. Flag to switch from start of parameter
                        ;//   (first/odd doublequote found) to end of
                        ;//   parameter (second/even doublequote found).
 it1             = 0;   ;//2. Iterator
 tmp             = allTrim(CHM_toc[NLine]); ;//3. Temporary TOC line copy
 lng1            = tmp.length-1;            ;//4. Line length
 qnx             = quoteNumber;             ;//5. Detected through the 0.5
                                            ;//   doublequote pair method
 dqCounter       = 0;                       ;//6. Doublequote counter
 toRet           = "";                      ;//7. Resultant substring, gathered
                                            ;//   character by character



 for(it1=0; it1<=lng1; it1++)
 {
  ;//It means that in fact we have finished founding
  ;//and gathering the parameter number (practically
  ;//in parallel, or very tightly):
    if(dqCounter>=qnx)
    {
     break;
    }

  if(tmp.charAt(it1)=='\"')   ;//If char IS doublequote
  {
     if(dqSwitcher)      ;//Ending doublequote
     {
      dqSwitcher=0;    ;//Switch to start
      dqCounter+=0.5;  ;//Add one quote, or 0.5 parameter
     }
      else              ;//Starting doublequote
      {
       dqSwitcher=1;    ;//Switch to end
       dqCounter+=0.5;  ;//Add one quote, or 0.5 parameter
      }

   continue;
  }
   else
   {
    ;//If char is NOT doublequote, we will
    ;//limit ourselves to gather one character
    ;//from the parameter:
    ;//It means that we are at the start of
    ;//the specified parameter, and, while we don't
    ;//find any other doublequote for ending, we will
    ;//keep getting content from this parameter.
      if(dqCounter==qnx-0.5)
      {
       toRet += tmp.charAt(it1);
      }
   }
  }

 return(toRet);
}