Actualizado el 14-01-2007
versión para imprimir
Esquema de un plugin: hkp register
El código de los plugins se estructura dentro de funciones.
Las funciones se definen en la forma usual:
function nombre (parametro1, parametro2 ...)
{
código a ejecutar
}
Como mínimo, cada Plugin debe tener dos funciones: function hkp_Main y function hkp_Register.
Opcionalmente puedes incluir otras funciones que serán llamadas al ejecutarse hkp_main.
hkp_Register
hkp_Register suministra a html-kit la información que necesita acerca del plugin (nombre, autor, versión, lugar en la barra de herramientas etc) y sobre como ha de ejecutarlo (si necesita tener o no un documento abierto, si actúa sobre todo el texto del documento o sobre texto seleccionado, etc).
Si nuestro plugin está escrito en hks, solo necesitamos incluir la declaración de la función hkp_Register, no la llamada a la función misma. Como quizas podamos ver mas adelante, si escribimos el plugin en otro lenguaje, por ejemplo PHP, debemos incluir no solamente la declaración de la función, sino también la llamada a su ejecución.
Bien, como hemos dicho, al declarar las funciones debemos indicar el número de parámetros que pueden tomar. En el caso de hks_register indicamos siempre dos: (pDataIn, pDataOut), que es la forma de decir que el plugin debe escribir y recibir información.
Los datos mínimos para registrar un plugin en HTML-kit son:
hkp_DataAdd( pDataOut, "NAME", "Button1" ); hkp_DataAdd( pDataOut, "SECTION", "MyPlugins" );
La funcion interna hkp_DataAdd sirve para mandar información a HTML-kit, y admite tres parámetros.
* El primer parámetro debe ser pDataOut (indicamos al editor que deseamos escribir datos).
** El segundo parámetro identifica el tipo de dato que vamos a enviar; en este caso, el nombre del plugin ("NAME") y su lugar en la barra de herramientas ("SECTION").
*** Y el tercer parámetro es la información en si. Advierte como tratándose de cadenas de carácteres, necesitan ir entrecomilladas.
Por tanto vemos que esas dos lineas del plugin informan a HTML-Kit que debe recibir la siguiente informacion sobre el plugin: nombre (button1) y seccion donde ubicarlo (MyPlugins).
Un plugin sencillo constará de un único botón, con una o mas opciones en un menu desplegable. Pero podemos escribir plugins mas complejos, que consten de varios botones. Por ello en la funcion register debemos incluir también información sobre la identidad del botón que estamos registrando.
La función hkp_DataSetGlobalSuffix sirve justo para eso:
function hkp_Register(pDataIn, pDataOut) { hkp_DataSetGlobalSuffix( "_1" hkp_DataAdd( pDataOut, "NAME", "Button1" ); hkp_DataAdd( pDataOut, "SECTION", "MyPlugins" ); hkp_DataSetGlobalSuffix( "" ); }
Esto es una muestra de la función hkp_register, donde vemos que toda la información se encierra entre dos llamadas a hkp_DataSetGlobalSuffix( "" );. La primera establece el valor del sufijo identificador en 1; la segunda resetea el valor a 0.
Si nuestro plugin tuviera varios botones, se vería algo asi como:
hkp_DataSetGlobalSuffix( "_1" ); /* Required Information */ hkp_DataAdd( pDataOut, "NAME", "Primer Boton" ); hkp_DataAdd( pDataOut, "SECTION", "Tools" ); ... hkp_DataSetGlobalSuffix( "" ); hkp_DataSetGlobalSuffix( "_2" ); /* Required Information */ hkp_DataAdd( pDataOut, "NAME", "Segundo botón" ); hkp_DataAdd( pDataOut, "SECTION", "Tools" ); ... hkp_DataSetGlobalSuffix( "" ); hkp_DataSetGlobalSuffix( "_3" ); /* Required Information */ hkp_DataAdd( pDataOut, "NAME", "Tercer botón" ); hkp_DataAdd( pDataOut, "SECTION", "Tools" ); hkp_DataSetGlobalSuffix( "" );
Un ejemplo real
Esta es la function register de un plugin típico:
function hkp_Register(pDataIn, pDataOut) { var sIcon1 = "AAABAAEAEBAQAAAAAAAoAQAAFgAAACgAAAAQAAAAIAAAAAEABAAAAAAAwAAAAAAAAAAAAA" "AAAAAAAAAAAAAAAAAAAACAAACAAAAAgIAAgAAAAIAAgACAgAAAwMDAAICAgAAAAP8AAP8A" "AAD//wD/AAAA/wD/AP//AAD///8AAAAAAAAAAAAEAABABAQAAAQAAEAEBAAABEQAQAQERA" "AEAEBERAQAQAQAQEAEBABABEQAQAQERAAAAAAAAAAAAAAAAAAAAAAAAAQAQAAAAAAAQAAA" "AAAAAAQAAEAAAAAAAEAABAAAAAAABAQAQAAAAAAAAEQAAAAAAAAAAAAAAAD//wAAva8AAL" "2vAACNowAAtC0AALWtAACNowAA//8AAP//AADt/wAA3/8AAL3/AADe/wAA638AAPz/AAD/" "/wAA" ; // esto es el icono codificado. hkp_DataSetGlobalSuffix("_1"); // un solo botón hkp_DataAdd(pDataOut, "NAME", "ToPHPPrint"); // nombre del plugin hkp_DataAdd(pDataOut, "SECTION", "Tools"); // seccion en la actions bar hkp_DataAdd(pDataOut, "HINT", "Converts the selected text into PHP print(\"...\") statements."); // tooltip que aparecera si pones el cursor sobre el boton hkp_DataAddInt(pDataOut, "MODE_SHOW_STATUS", 0); // sin barra de progreso hkp_DataAddInt(pDataOut, "MODE_IN_TEXT_SELECTED", 1); // usa texto seleccionado hkp_DataAdd(pDataOut, "MODE_ICON", "1"); // con icono hkp_DataAdd(pDataOut, "ICON_SMALL", sIcon1); // apunta al icono hkp_DataSetGlobalSuffix(""); }