[Tutorial] Componentes DIY

Strange Eons permite crear tus propios primigenios, investigadores, monstruos...

[Tutorial] Componentes DIY

Notapor sectario el Jue Sep 01, 2011 7:12 pm

Componentes DIY
Un componente DIY es un tipo especial de componente diseñado por ti mismo usando código script. Mientras la personalización te permite adaptar un componente ya existente, DIY son componentes que no se basan en ningún componente previo. Tú decides que información proporcionas, que controles de editores para ese componente utilizas y que muestra la carta.

Preparación
Tú necesitarás revisar las bases sobre como crear un proyecto (enlace ingles) y como crear una extensión plugin, que es una extensión, que ficheros se necesitan y como empaquetarlos. También has de estar familiarizado con el concepto de claves ajustes claves y ajustes privados de un componente. Y necesitarás descargar, descomprimir e instalar lo siguiente:

Un repaso
Antes de seguir adelante, vamos a revisar algunos conceptos, comenzando con las librerías de código. Strange Eons incluye cierto número de estas librerias: código ya escrito almacenado en la carpeta "resources/libreries" (en la carpeta resources del Strange Eons). Para usar una libreria debes añadir una línea uselibrary ("nombre_de_libreria") al inicio del fichero. Con esto toda la librería añadida estará disponible para todo el código del fichero.

Todas las librerias de código tienen su documentación. Tu puedes encontrar una copia de esta documentación en el Plug-in Authoring Kit (Kit de autoría de plugins) o leerla directamente con el Strange Eons usando el plugin Script Library Documentation(plugín de librería de documentación de código). Utilizar los plug-in tiene como ventaja que siempre se te muestra la documentación de la versión de las librerías actualmente disponibles en tu copia de Strange Eons.

El segundo concepto que vamos a revisar es el concepto de ajustes o configuración. Los ajustes en Strange Eons consisten en varios pares de claves (el nombre del ajuste) y sus valores (lo que la configuración tiene como valor). Hay un único grupo común de valores que definen todos los valores por defecto que pueden ser sobreescritos (es decir se les da un nuevo valor) para modificar ese componente. En el ejemplo de Personalizar Carta Enemigo, vimos como modificar la configuración privada del componente para personalizar el texto y su imagen. Vamos a usar los ajustes privados para guardar las opciones de usuario en las características de nuestars cartas. Por ejemplo, si la carta requiere un gasto de dinero, la carta tendría su coste en el juego, y podríamos utilizar el ajuste con la clave Gold (oro).

El último concepto que tenemos que revisar es el de región. Una región es un tipo particular de configuración, que describe un área rectangular, dando la ubicación desde su esquina superior izquierda (desplazamiento x-y), junto con su anchura y su altura. El valor de la región consiste en esos cuatro números separados por comas. Por ejemplo, la región sanity-text-region describe el rectángulo en el que se muestra el texto "Cordura" (Sanity) en las cartas de investigador. Su valor para esta clave es "522,255,119,39", y podría tener la siguiente interpretación:
Imagen

Aquí la región se muestra en la recuadro púrpura. Recuerda que el primer número es la distancia a la esquina superior derecha, el segundo número es la distancia por debajo de este esquina izquierda, el tercer número es el ancho del rectángulo y el cuarto la altura. Utilizando el plug-in Mostrar Regiones (Show Regions) puedes hacer que destaquen las regiones en un componente durante su desarrollo.


Vamos a empezar
Primero de todo, nos hemos de familiarizar con los componentes DIY, entonces vamos el paquete en el que están contenidas los elementos de una extensión. Para empezar, buscamos la carpeta el Plug-in Kit. Entre otras cosas, encontraremos un archivo llamado minimal-diy.js. Abrimos este archivo con la ventana de Procesado Rápido (Quickscript) y arrastramos el fichero minimal-diy.js dentro de él. Ejecutamos el código y vemos que sucede. Podemos ver un nuevo editor, como este:

Imagen

Es un código simple que tiene toda la magia que necesitamos para crear un nuevo tipo de carta. Por supuesto, no será una carta emocionante. Pero es un comienzo. El código funciona como si fuera un código plug-in: definimos las funciones con sus nombres particulares, y Strange Eons llamará a estas funcones cuando sea necesario. Vamos a comenzar por entender lo que las funciones y como son llamadas desde Strange Eons

La anatomía del ciclo de vida de un componente DIY.
A continuación se encuentra un diagrama con el ciclo de vida de un componente DIY. El componente comienza cuando se añade el componente al Strange Eons, ya sea creando un componente nuevo, o abriendo uno ya existente que se guardará en un fichero. Vamos a verlo a través de el diagrama, comenzando por un fichero nuevo, y comentando cada paso:

(hacer click en la imagen para ampliar, y verlo más en detalle)
Imagen

create(diy)
Esta función se llama una única vez, la primera vez que el componente es creado. Tenemos dos tareas a realizar antes de que regrese. En primer lugar, el nuevo objeto DIY se le ha pasado cierto número de atributos básicos que determinarán las características básicas del componente. Sólo se puede cambiar los atributos en esta función o con onRead. Segundo, debemos establecer los valores iniciales para todas las propiedades que el usuario pueda llegar a modificar (como Name-nombre, Gender-sexo, Speed-velocidad -lo que sea apropiado para la carta).

Algunos de estos atributos serán necesarios para establecer un estilo, las plantillas anverso y reverso, y las claves. El estilo controla cuantas y de que tipo de presentaciones tendrá la carta. Para cambiarlo se ha de modificar diy.faceStyle a uno de estos valores

"Algo de parrafada sobre atributos ": mostrar
Hay un tipo de programación que se llama Programación Orientada a Objetos. En este tipo de programación, que es la que utiliza Strange Eons, hay dos conceptos muy importantes: atributos y funciones. Pongamos un ejemplo. Vamos a suponer que tenemos un código de programación para contener información de los arboles: arbol

Los arboles puedes ser de diferentes especies: pinos, manzanos... Entonces en programación orientada a objetos tendriamos un atributo para definir que especie es el árbol. Esto se escribiría arbol.especie. De igual manera podriamos tener arbol.numeroHojas, arbol.altura y las diferentes características/atributos que componen un árbol

De forma que diy.faceStilye significa que estamos haciendo referencia al faceStile-"Estilo" del diy


FaceStyle.ONE_FACE : El componente tiene una única cara (solo delante, nada detrás)
FaceStyle.PLAIN_BACK: El componente tiene la parte trasera plana (es decir una imagen trasera fija que nosotros diremos al Strange Eons como es)
FaceStyle.SHARED_FACE : El componente tiene dos caras, pero son idénticas
FaceStyle.TWO_FACES : El componente tiene dos caras diferentes (podemos modificar ambos lados)

"Seguimos con la parrafada": mostrar
Recuperando el ejemplo del árbol. Ahora queremos crear arboles de diferentes razas. Por ejemplo pinos, abedules, manzanos... Pero nos encontramos con un problema, el de especie "manzano" es diferente a la especie "Manzano", y por supuesto tambiés es diferente a la especie "manzanos" o "Manzanos". Para evitar confusiones definimos una serie de especies por defecto: PINO, MANZANO.ABEDUL. Y permitimos únicamente las especies arbol.especie.PINO, arbol.especie.MANZANO y arbol.especie.ABEDUL.

De igual forma se usa mayúsculas para valores por defecto. Por ejemplo el atributo (caracerística) FaseStyle sólo se le permiten los valores ONE_FACE, PLAIN_BACK...


La plantilla trasera y frontal son imágenes que definen la visión base, la forma y el tamaño del componente. La plantilla trasera funciona igual que la plantilla frontal, con lo que sólo trataremos en el tutorial la plantilla frontal. Para configurar la plantilla frontal de la carta hemos de configurar diy.frontTemplateKey para tener una base para las claves principales. Al combinar los nombres bases con los diferentes sufijos, la carta DIY se compondrá de la configuración de clave y el utilizará sus valores para determinar que necesita saber para mostrar la parte frontal de la carta. Lo más importante de estos están a continuación (donde xxx es el valor asignado a diy.fronTemplateKey):

xxx-template: el fichero de recurso que contiene la imagen
xxx-dpi: si existe, la resolución de la plantilla imagen en pixels por pulgada (2.54 cm) (por defecto es 150). El tamaño físico de la carta es determinado por el tamaño de la imagen de plantilla (en pixel) dividido por este valor
xxx-expsym-region: Si existe, la región en la que se dibujará el símbolo de expansión (por defecto estará sin símbolo de expansión).

Si queremos que nuestro componente incluya una imagen de retrato, necesitamos dar un valor a diy.portraitKey. Tanto para la clave de la plantilla frontal como para trasera, esto es también una clave base a la que se añaden los sufijos. Consulta la librería de documentación para más detalles.

Un componente DIY típico tiene algunas propiedades adicionales que han de ser escogidas por el diseñador del plugin: valores que el usuario puede cambiar y afectarán a la forma de dibujarse de la carta. Por ejemplo, la carta de Investigador tiene el valor de Resistencia que es un número que indica la resistencia física del personaje. En un DIY, el valor de la Resistencia puede ser una propiedad atributo. Cada componente DIY incluye un nombre y un comentario de la propiedad. Otras propiedades necesarias pueden ser añadidas, siendo añadidas a la configuración privada de la carta. En la función de creación, damos a estas propiedades valores por defecto que deben tener cuando el usuario inicia por primera vez la edición de la carta. Por ejemplo, podríamos fijar el valor de la Resistencia a 5 con la siguiente línea:
Código: Seleccionar todo
// new investigators will start with a Stamina of 5
diy.settings.set( "Stamina", "5" );

"Los comentarios": mostrar
Para los que no tengan conocimientos de informatica. Las líneas que empiezan por "//" son comentarios. Estas líneas no son leídas cuando se ejecuta el código, y únicamente sirven para poner un comentario, normalmente con información general para leer por el programador.


"Información getter y setters": mostrar
Antes he puesto algo de información sobre los atributos. Por ejemplo en el ejemplo sobre los componentes arbol, teniamos el atributo arbol.especie que podía tener diferentes valores (como PINO, ABEDUL).

La forma "correcta" de dar un valor a un atributo es con un setter. Se trata de un pequeño código que da el valor a una propiedad. Siguiendo nuestro ejemplo podríamos crear el código arbol.setteings.set("Especie","PINO") Esta código informaría la especie de nuestro árbol como PINO. La intención de hacer esto es centralizar todo tratamiento. Si queremos asegurarnos que los valores de especie son unos determinados sólo tendriamos que añadir la comprovación dentro del código del setter.


Tenga cuidado de escoger el nombre estandard de Strange Eons que necesite tu carta. Todo lo que tenga al menos una letra mayúscula debe ser necesario para tu crta. A partir de Strange Eons 2.00.5, el sistema de código te permite acceder a las claves de configuración (settings keys) como si fueran unas variables escribiendo, $ seguido del nombre de la clave (también se tiene que utilizar _ en lugar de - porque los guiones no están permitidos en nombres de variables) Así que lo anterior también puede ser escrito de forma más fácil de la forma siguiente:
Código: Seleccionar todo
 $Stamina = "5";

y tendrá el mismo efecto. Las cartas DIY tienen acceso a sus claves de configuración privados con esta sintaxis, mietnras que otros códigos tendrán que acceder a su la configuración con los settings.

Ten en cuenta que los nombres estandard DIY y los comentarios de propiedades no están informados de esta manera, ya que son parte de las propiedades del objeto DIY y no son configuración privado: ellos son accesibles directamente como diy.name y diy.comments.

createInterface( diy, editor )
Esta función llama al contructor que usará la interfase del componente, y mostrará la interfase de usuario que controlará los ajustes correspondientes. Esto se hace usando el objeto Bindings ("Enlaces"), de la librería básica uibindings. Un objeto Bindings convierte lo editado por el usuario en controles de edición y las propiedades privadas son almacenadas en propiedades que pueden ser editadas (Se creará automáticamente los listeners y vinculará cada uno de ellos a los controles de usuario).

La secuencia básica de eventos para crear la interfaces de usuario es la siguiente:
  1. Crea el contenedor que contendrá y mostrará los controles de la interfaces de usuario (ver el documento de biblioteca uilayout)
  2. Cre un objeto Bindings nuevo que traducirá entre los controles y las propiedades de configuración privadas (ver el documento librería uibindings)
  3. Crear una o más interfaces de control de usuario (ver el documento de la librería uicontrols)
  4. Se añaden los controles al contenedor
  5. Añade los controles al objeto Bindings, y para cada uno de ellos se dice al objeto Bindings: (1)Cual es la clave para la propiedad editada por el control, y (2) que parte de la carta ha de refrescarse cuando la propiedad varía.
  6. Indicar al objeto diy que control de campo text, si es que hay, será usado para infomar el nombre del componente. Esto se hace llamando a diy.setNameField(nameField); (recuerde que el nombre del componente es una propiedad especial, y no es tratada mediante los Bindings)
  7. Llama a la función addToEditor del componente para añadir el componente a la ventana del editor como una nueva pestaña
  8. Llamar a la función bind del objeto Bindints para crear e instalar el "código de unión" que une los controles y la configuración privada.

Cuando la ventana del editor finalmente se ha abierto, el enlace puede se usado para copiar e inicilizar los valores de las propiedades de la configuración privada del componente.

createFrontPainter( diy, sheet ), createBackPainter( diy, sheet )
Estas funciones son llamadas para proporcionarnos la posibilidad de hacer los cambios antes que la carta sea dibujada. Observa quecreateBackPainter sólo se llama si la carta tiene el estilo FaseStyle.TWO_FACES . El uso más comun de esta función es crear las cajas de texto. Una marca de caja de exito es usada cuando se dibuja una carta por el Stranjgfe Eons (txto con etiquetas). Ver la libreríapara tener más detalles sobre el objeto MarkupBox

paintFront( g, diy, sheet ), paintBack( g, diy, sheet )
Estas funciones son llamadas cuando la carta tiene cara que ha de ser dibujada. Ten en cuenta que paintBack será llamada si sólo si usamos el estilo FaceStyle.TWO_FACES. El parametro g es un objeto de contexto para graficos Graphics2D que puede ser usado para pintar la carta. El contexto gráfico puede ser en una escala de 1 a un 1pixel de la imagen de plantilla, independientemente de la resolución con la que se está dibujando la carta. El parametro sheet ("hoja") es una instancia de DIYSheet que es el responsable de gestionar la cara/superficie de la carta que va a dibujar. Ofrece algunas funciones auxiliares que simplifican algunas de las tareas más comunes relacionadas con el dibujar de la carta, como por ejemplo:

Código: Seleccionar todo
// clip, scale, translate, and paint the current portrait image
sheet.paintPortrait( g );

// paint the template image defined by this faces's template key
sheet.paintTemplateImage( g );


Una vez que hemos dibujado el retrato (si existe) y la plantilla de la imagen, el procedimiento básico es el de "hacer algo" con cada una de las propiedades del componente. Ese "algo" dependerá de lo que la superficie de la carta tenga que hacer. Una acción típica consiste en dibujar el texto a partir de las propiedades, lo que podría ser algo como:

Código: Seleccionar todo
// set text mark-up text to draw from the special-ability private setting (property)
abilityBox.markupText = $SpecialAbility;
// draw in the region defined by the setting blah-card-ability-text-region
abilityBox.draw( g, diy.settings.getRegion( "blah-card-ability-text" ) );


Después de que esta función acabe, Strange Eons ejecutará el controlador de eventos de la carta (si hay uno definido) y pintará el símbolo de expansión (si una expansión ha sido seleccionada y la clave de símbolo de expansión está definida en la plantilla).

onClear( diy )
Esta función es llamada cuando el usuario lanza el comando Clear ("Borrar"/"Limpiar"). El nombre del componente y los comentarios añadidos automáticamente serán borrados automáticamente. Tendrás que añadir el código para limpiar el resto de tus propiedades. Por ejemplo:

function onClear( diy ) {
// reset card to a "clear" state; what
// that means is up to you
$Strength = "1";
$Wits = "1";
$Gold = "0";
$SpecialAbility = "";
}



Regarding onRead and onWrite (Respecto a OnRead y onWrite)
Estas funciones permiten hacer acciones especiales cuando la carta es leída/cargada desde un fichero, o cuando es grabada en un fichero. No lo necesitamos para nuestro ejemplo, pero voy a describir la para que puedas usarla. Hay dos usos principales para estas funciones. En primer lugar, puedes utilizarlas para actualizar tus viejos ficheros cuando liberas una nueva versión del plug-in. Por ejemplo, si añades una nueva propiedad en la nueva versión de plug-in, los archivos antiguos guardados no tendrán esa propiedad. El nuevo plug-in OnRead debería de detectar eso, y dar un valor a la propiedad que les falta con un valor adecuado. La propiedad DIY.cardVersion puede ser utilizada para determinar que características han de ser actualizadas. La libera de documentación DIY describe como hacer estos tipos de cambios.

La segunda razón para usar estas funciones es para guardar datos en un fichero que no pueden ser representados como texto. Esta es una característica avanzada, así que no te preocupes si no entiendes el resto del parágrafo. Los valores de configuración siempre se guardan como cadenas de texto. Aunque muchos tipos de datos se pueden convertir con facilidad desde y hacia texto, algunos tipos de datos no son fácilmente convertibles. Por ejemplo, el sistema DIY proporciona un manejo estandard para la imagen de un retrato, pero ¿que sucede si lo que deseas es proporcionar una imagen para ser usada por el usuario? El objeto de entrada stream ("flujo"/"chorro") (pasado por onRead) y el objeto de salida stream (pasado por onWrite) te permiten leer y escribir estos datos como parte del fichero a guardar. Puedes leer y escribir tipos primitivos de datos java (readInt, writeInt, etc) y objetos implementados por la interfase Serializable. A partir de la versión 2.1 alpha, puedes leer y escribir imágenes usando readImage y write Image, respectivamente.

Ok. Vamos a hacer algo
Ahora que sabemos cuales son las partes básicas de un componente DIY, y como funcionan, vamos a intentar hacer algo. Para simplificar las cosas, nos restringiremos a los gráficos y las fuentes de texto que ya proporciona Strange Eons. De esta forma podemos centrarnos en crear los DIY. Para nuestro proyecto, vamos a suponer que queremos tomar el ejemplo "Plot" proporcionado por el tipo de carta "Miscellaneous Large", y crear una carta dedicada para ello:
Imagen

El ejemplo Miscellaneous Large crea esta carta con un sólo bloque de texto, pero queremos crear una carta con áreas específicas para el fondo, efectos, y el foil (¿papel? ¿hoja?), y crear una división específica para el título.

Para comenzar, creamos un nuevo proyecto y añadimos una tarea plug-im vacia. Partiendo del plugín vacio, obtendremos una mayor compresión de como van encajando todas las piezas. Entonces, cuando uses algunas de las tareas más automáticazas más tarde, no te preocuparás por los misteriosos ficheros que estarás modificando.

Dentro de la carpeta task (tareas), creamos una nueva carpeta llamada resources (recursos) y luego creamos una nueva carpeta dentro llamada plotexample. Aquí es donde vamos a poner nuestro scripts. Si tuviéramos algunas imágenes propias u otro tipo de recursos, también los pondríamos aquí.

En la carpeta plotexample, hacer botón derecho y escoger Nuevo | Plugin Script. Llamarlo extension.js (el .js ya está por defecto, y no ha de escribirse). Esto creará un nuevo esqueleto de script (código) que incluirá las definiciones de las funciones usadas por el plugin. Regresaremos a este fichero en un momento.

Desde que empezamos un plugín a partir de cero, tendremos que crear un archivo root ("raíz") que será utilizado por Strange Eons cuando se carga el plugin. Este fichero le dice que clase o código ha de utilizar para iniciar al plugin. Haga botón derecho en la carpeta task ("tareas") y escoge New | Plug-in. Esto creará la carpeta raíz e inmediatamente abrirá el editor de la raíz. En el editor de la raíz, hacer click en la fichero código extension.js (la única opción, dado que es el único script/código), y entonces hacer lick en Update ("Actualizar"). Asegúrate de no cambiar el nombre del fichero raíz, o el plug-in no funcionara.

Ahora estamos listos para editar el código del script. Hacer doble click en la extensión.js para abrirla. Esto es un código plug-in de proposito general. Vamos a cambiarlo un poco para adaptarlo a nuestro objetivo. Primero vamos a crear una extensión, necesitamos incluir la librería extension, añadiendo la linea uselibrary("extension") al inicio del código. En segundo lugar, no necesitaremos las funciones run (ejecutarse), hide (ocultar), isShowing y unload, así que borramos esas funciones. A continuación, rellenamos los valores para getName y getDescription para describir nuestro plug-in. Finalmente, lo más importante que nuestro código necesita es decirle al Strane Eons que queremos un nuevo tipo de carta. Para ello añadimos la linea GameData.parseEditors("plotexample/plot.classmap"); al final del fichero. Esto dice al Strange Eons que ha de crear un nuevo componente disponible con las descripciones que hay en el fichero plot.classmap (vamos a hacerlo en un momento). El resultado es lo siguiente (he borrado los comentarios para hacerlo más breve):

Código: Seleccionar todo
uselibrary( "extension" );

function getName() {
    return "Plot Cards";
}

function getDescription() {
    return "A DIY Example that adds plot cards.";
}

function getVersion() {
    return 1;
}

function run() {
    println( "Plug-in activated" );
}

GameData.parseEditors( "plotexample/plot.classmap" );


Guarda el fichero de código, entonces haz botón derecho en la carpeta plotexample y escoge New | Class Map. Nombralo plot.classmap (una vez más, la extensión no se ha de poner ya que es proporcionada). Lea los comentarios que hay en la parte superior del fichero para hacerse una idea de como funciona class maps, entonces cambia la última línea del fichero:

Código: Seleccionar todo
DIY Plot Card Example = diy:plotexample/plot-card.js


Guarda el archivo. Ahora hemos creado la infraestructura básica que el plug-in necesita para añadir un nuevo tipo de componente. Todo lo que necesitamos es el código que crea y controla la carta. Si lees los comentarios en el fichero class map, podrás adivinar que vamos a crear otro código en la carpeta plotexample, esta vez llamado plot-card.js. Para crearlo, escogemos New | DIY Component Script e introducimos el nombre de código deseado. Hacemos doble click para abrirlo:

Escribiendo el DIY Script (código DIY)
El código base creado por Strange Eons ya es un componente DIY funcional. Es muy similar a los ejemplos minimal-diy.js vistos antes. Intenta ejecutarlo. Hay dos maneras de hacer, o bien haces botón derecho sobre el fichero código en la vista del proyecto, o botón derecho en el editor de código abierto. Escoge Run (Ejecutar). si haces botón derecho en el editor abierto del código, de forma automática grabará el fichero antes de ejecutarlo. Cierra la carta creada al ejecutar el código.

Vamos a ver que cosas hace este código base. En el editor de código, selecciona todo el texto (Ctrl+A), y lo borramos. Copiamos y pegamos el siguiente código, que sólo incluye la librería diy y todas las funciones que deben ser escrita:

uselibrary( "diy" );

function create( diy ) {
}

function createInterface( diy, editor ) {
}

function createFrontPainter( diy, sheet ) {
}

function paintFront( g, diy, sheet ) {
}

function createBackPainter( diy, sheet ) {
}

function paintBack( g, diy, sheet ) {
}

function onClear( diy ) {
}

function onRead( diy, ois ) {
}

function onWrite( diy, oos ) {
}

testDIYScript();


La última línea, testDIYScript(); es una llamada a una función especial que permite verificar si el componente DIY que hemos escrito sin tener que crear un paquete y arrancar una copia del Strange Eons cada vez que queramos validarlo. Es importante recordar comentarlo o borrarlo cuando estemos haciendo pruebas. No queremos esto se ejecute cuando el plug-in esté acabado.

Al igual que el código base, podemos ejecutar este código haciendo botón derecho en el editor. Intentalo. No te sorprendas, nuestra carta no es más que un recuadro negro, y el único control que tenemos sobre ella es editar los comentaros (uno de las dos "propiedades" incorporadas).

Vamos a ver si podemos escribir el código necesario para obtener un fondo para la carta Miscellaneous Large. Primero, tendremos que configurar el objeto DIY para crear los atributos básicos. Escoge Toolbox|Script Library Documentarios y haz click en la entrada diy. Busca hasta encontrar la descripción de la función create(). Leelá una vez (es un poco larga ya que describe las diferentes propiedades para crear una carta)

Podemos escoger un par de propiedades DIY. Vamos a configurar la versión 1, le daremos el nombre PlotExample.seext, porque así se va a llamar nuestra extensión final. Para empezar, vamos a definir la presentación de una de las cartas con la que vamos a trabajar. Ahora sólo necesitamos la clave para informar la plantilla frontal y podremos usarlo. Abrimos la carpeta donde guardamos nuestra copía descomprimida de los recursos de Strange Eons,. En la carpeta principal de resources (recursos), buscamos el fichero card-layout.txt y encontramos las claves para la carta Miscellaneous Large. Hay dos conjuntos de claves, una para determinar la orientación vertical y otra para la orientación horizontal. Vamos a utilizar la versión vertical. Leyendo la librería de documentarión DIY, vemos que queremos usar el nombre de la clave que da nombre a la imagen que usaremos, más el sufijo -template. Acabaremos creando la siguiente función:

function create( diy ) {
diy.cardVersion = 1;
diy.extensionName = "PlotExample.seext";
diy.faceStyle = FaceStyle.ONE_FACE;
diy.frontTemplateKey = "lg-misc-front-sheet";
}


Si queremos usar nuestra propia imagen para la carta, tendremos que añadir las claves apropiadas para la configuración del programa y poner la imagen que queremos usar junto al resto de archivos de nuestra extensión. Para las pruebas, vamos a empaquetar una versión ficticia que incluye las imágenes que deseamos utilizar y ejecutar Strange Eons con el. A continuación, las imágenes serán visibles en nuestro código como si trabajásemos con él. (alternativametne, podríamos crear un paquete y usarlo para validar nuestro proyecto). Para definir las claves que necesitamos, añadiremos el siguiente código de inicio a nuestro código de prueba:

Código: Seleccionar todo
Patch.temporary(
    "our-card-type-front-template", "ourextension/front.png",
    "our-card-type-front-expsym-region", "32,32,15,15"
    // etc.
);

// Note that, alternatively, we could use $ notation instead:

$our_card_type_front_template = "ourextension/front.png";
$our_card_type_front_expsym_region = "32,32,15,15";


Una vez satisfecho con los resultados, podemos mover el código al fichero de nuestra extensión principal o crear las configuración por separado o crear un fichero de configuración por separado y cargar el archivo usando una línea como GameData.parseSettings("plotexample/card-layout.txt"). Echa un vistazo a los otros ejemplos en el Plug-in Kit para ver como se hace esto. Por ahora, regresemos al problema que estamos tratando. El código de nuestra función fija la clave correcta para obtener la imagen que queremos, pero si se ejecuta no se preocupes si no pasa nada. Strange Eons no puede mostrar en estos momento la imagen. Esto está así a propósito, porque muchas veces queremos pintar alguna cosa debajo de la imagen de la plantilla. Por ejemplo, si tenemos un tipo de carta que tiene un retrato, normalmente querremos pintar el retrato, y luego pintar la imagen de la plantilla (que contará con la correspondiente área de transparencia) Tal yc omo vimos anteriormente, la función paintFront es llamada cuando llega el momento de pintar la carta. Editamos la función de la siguiente manera para pintar la plantilla, e intentamos ejecutar el código:

Código: Seleccionar todo
function paintFront( g, diy, sheet ) {
    sheet.paintTemplateImage( g );
}


La otra tarea que tenemos que realizar es informar los valores iniciales en las distintas propiedades que el usuario podrá modificar. En esta carta de ejemplo dará la bienvenida al usuario cuando cree una nueva carta. Para ello, primero necesitamos decidir que propiedades serán y que tipo de control tendrá el usuario sobre ellas. Por ejemplo, el usuario puede poner cualquier valor que quiera, o si sus decisiones estarán restringidas a una lista fija de opciones. Para este tipo de carta, la respuesta es simple. Vamos a añadir la opción de que el usuario introduzca el nombre, el resumen, los efectos y el texto de ambiente (El nombre reemplazará el título "Plot"). Para todo esto, el usuario deberá de poder introducir el texto que desee, pero el nombre deberá estar en una única línea.

Todas las cartas DIY contienen un nombre y comentarios, así que no necesitas hacer nada especial para añadirlos. Podemos acceder a ellos usando diy.name y diy.comment respectivamente. Cualquier propiedad adicional que se defina requerirá más trabajo. Podríamos crear código variable para nuestras propiedades, pero el problema surge cuando queremos salvar el componente y lo abra de nuevo más tarde. cuando abrimos el fichero, el código no continuará donde lo haya dejado, sino que intentará ejecutarse desde principio. Así que todas las propiedades que se almacenan en variables de código se perderán. Tenemos que escribir las funciones onWrite y onRead que darán valor a las variables, pero esto puede ser complicado y difícil de mantener. En su lugar, vamos a guardar nuestras propiedades en las configuración privada del componente, para que sean guardados y recuperadas automáticamente para nosotros. Para hacerlo más fácil, Strange Eons nos proporciona la notación $ en los ficheros de código. Cuando una variable empieza por $, su valor es asignado a la configuración con el mismo nombre (pero sin el $). El único truco es que las variables de JavaScript no pueden tener guión (-), así que puedes usar el guión bajo (_) en su lugar. Por ejemplo, $sanity_text="Brains!" establece el valor de la clave del configuración sanity-text a Brains!. Para hacerlo más fácil, cuando ejecutemos el código DIY Strange Eons cambiaremos automáticamente la configuración privada del componente a esta notación.

Así para el almacenamiento de las propiedades de la carta. Todo lo que tenemos que hacer ahora es decidir como llamarlos. Para evitar conflictos con los nombres de las claves existentes, te sugiero que comiencen con el mayúscula y con mayúscula las atributos formados por la concatenación de más de una palabra ($JustLikeThis). Aquí etá el código para inicializar los campos del ejemplo usado en la carta Miscellaneous Large, salvo que demos a la carta un título que no sea "Plot" y dejaremos los comentarios en blanco para tener el código más breve.

Código: Seleccionar todo
function create( diy ) {
    diy.cardVersion = 1;
    diy.extensionName = "PlotExample.seext";
    diy.faceStyle = FaceStyle.ONE_FACE;
    diy.frontTemplateKey = "lg-misc-front-sheet";
   
    diy.name = "Shaping Young Minds";
    diy.comment = "";
    $Summary = "Cultists have converted a popular and influential "
        + "professor to their cause.";
    $Effects = "Clue tokens may not be gained by any means at any Miskatonic "
        + "U. location. If the terror level reaches 4, immediately open a "
        + "gate at the Science Building as if a gate burst had occurred there.";
    $Foil = "Instead of having an encounter at the Administration Building, "
        + "you may make a <b>Will< >(-2)</b> check to see the Dean. If you "
        + "pass, discard 5 Clue tokens to convince him that the professor is "
        + "dangerously insane and should be hospitalized. If no gate is open "
        + "on the Science Building, seal it using a token from the doom track.";
}


Mientras estamos en ello, también podemos escribir nuestra función onClear. Esta se llama cuando el usuario escoge Edit | Clear (Editar|Borrar), y se informan todos los atributos del componente a su valor neutro. Los atributos permites que cualquier texto sea limpiado con texto en blanco, pero si quieres que un atributo sea limpiado con un valor determinado, puedes escoger establecer el dicho valor. El nombre del componente y los comentarios pueden ser blanqueados por nosotros, así que esta es nuestra implementación de onClear

Código: Seleccionar todo
function onClear( diy ) {
    $Summary = "";
    $Effects = "";
    $Foil = "";
}


Ahora que tenemos los elementos básicos en su lugar, vamos a construir la interfaz de usuario. Los desarrolladores avanzados pueden construir una interfaz "a mano" usando los objetos Swing, pero Strange Eons proporciona una serie de bibliotecas para hacerlo más fácil. Dado que muchas veces se utilizan las mismas bibliotecas, vamos a incluirlas en la parte superior del archivo:
Código: Seleccionar todo
uselibrary( "diy" );
uselibrary( "ui" );


¿Recuerdas que los ochos pasos que enumeramos más arriba para la creación de la interfaz? Vamos a realizarlos uno a uno.
  1. Crear un contenedor para diseñar los controladores
    La librería uilayout proporciona varios tipos de contenedores. Un contenedor se utiliza para agrupar los controles y controlar la forma en que se muestran al usuario. Vamos a utilizar el tipo más fléxible de los contenedores, una cuadrícula. (Para usar el contenedor Grid en versión del Strange Eons 2.1 o anterior, debemos tener instalada ui-grid.selibrary. A partir de la versión 2.1, esta biblioteca está incluida). Vamos a empezar a crear una Grid <cuadrícula/red/parrilla> y usarla como variable.
    Código: Seleccionar todo
    var container = new Grid( "fillx" );


    El texto "fillx" hará que la cadena ocupe toda el espacio disponible.
  2. Crear un nuevo objeto Bindings
    <Bind se traduce como atar, enlazar, ligar...
    <Enlaza los controles de un componente, con el estado de un componente. Si aumento es tipo de letra de 9 a 10 -control de componente- debo de aumentar el tamaño del texto afectado -es decir su estado>

    Se utiliza in objeto Bindings para construir y gestionar la relación entre los controles de interfaz y el estado del componente. Este objeto responderá a las modificaciones que haga el usuario en los controles y actualizará sus atributos (ámbito privado) para que coincidas. Vamos a añadir esta línea para crear nuestro objeto Bindings.
    Código: Seleccionar todo
    var bindings = new Bindings( editor, diy );

  3. Crear los controles de la interfaz de usuario
    La biblioteca uicontrols define una serie de funciones auxiliares para crear los tipos más comunes de controles. Podemos utilizarlos para crear listas desplegables, campos de texto, casillas de verificación o checkbox y mucho más. Vamos a utilizar un campo de texto para almacenar el nombre, y el áreas de texto (campos de texto con más de una línea) para lo demás:
    Código: Seleccionar todo
    var nameField = textField( "", 30 );
    var summaryField = textArea( "", 4, 30, true );
    var effectField = textArea( "", 7, 30, true );
    var foilField = textArea( "", 7, 30, true );

  4. Agregamos los controles al contenedor
    El objeto contenedor se utiliza para organizar los controles en grupos. Determina si los controles van a aparecer en la pestaña Editor, en que orden aparecerán, su tamaño y así sucesivamente. Puedes agregar controles a un diseño utilizando los métodos add <añadir> o place <lugar>. Las diferencias es que usando place, también proporcionas un texto que da pistas sobre como debe ser el control. Las pistas o sugerencias dependen del tipo de contenedor. Aquí está el texto que utilizaremos:
    Código: Seleccionar todo
    container.place(
        "Title", "split", nameField, "growx, wrap",
        "Summary:", "wrap",
        summaryField, "gap i, growx, wrap",
        "Effects:", "wrap",
        effectField, "gap i, growx, wrap",
        "Foil:", "wrap",
        foilField, "gap i, growx, wrap"
    );
    container.setTitle( "Plot" );


    Habrás observado que el primer "control" que hemos añadido tiene el texto "Title" <Título>. Dondequiera que añadas un control a un contenedor puedes asignarle un texto, y ese texto se convertirá en la etiqueta del control (es decir, un swing.JLabel) para tí. Para un diseño Grid, wrap es la sugerencia es colocarlos controles formando una fila uno después de otro. El growx hace que se permita ampliar el control y que ocupe todo el espacio disponible. gap i indica que el control está relacionado con el control que está sobre él. Proporcionar un título al contenedor hará que aparezca un borde con el título alrededor suyo (Consulta la documentación de la biblioteca uilayout para más información)
  5. Añadimos los controladores al objeto Binding
    Para crear una unión entre un atributo y un control, necesitamos proporcionar tres cosas: el nombre de la clave privada que será usada para almacenar el atributo, el control, y un array con las imágenes que se han de volver a cargar cuando se modifique el atributo. Hay que recordar que con la notación $, si queremos escribir una variable llamada $Effects en realidad modificaremos la configuración de las claves de Effects, por lo que para relacionarlos hemos de darles un nombre. El control es exactamente el formulario/control que utilizaremos para editar el campo que estamos enlazando. El vector de imágnes es un vector de enteros, y que normalmente tendrá uno de los siguientes valores:
    [0] Cuando este atributo cambia, vuelve a dibujar la cara frontal del componente
    [1] Cuando este atributo cambia, vuelve a dibujar la cara trasera del componente
    [0,1] Cuando este atributo cambia, vuelve a dibujar ambas del componente

    Todos nuestros atributos aparecen en la cara frontal, así que:

    bindings.add( "Summary", summaryField, [0] );
    bindings.add( "Effects", effectField, [0] );
    bindings.add( "Foil", foilField, [0] )

  6. Comunicarle al DIY que los campos de texto (si existen) fijan el nombre de un atributo





Registro en sectarios.org: Enviame un correo a marcoa.ramirez arroba gmail.com
Leyendo... Ratas en las paredes
Avatar de Usuario
sectario
Cordura 0 Mitos Cthulhu 25
 
Mensajes: 9637
Registrado: Lun Oct 22, 2007 8:54 pm
Ubicación: Observando los Mi-go de Montserrat.

Re: [Tutorial] Componentes DIY

Notapor keron el Mar Sep 13, 2011 8:13 pm

¡Animo! Que ya queda un poquito menos.
Avatar de Usuario
keron
Cordura 60
Cordura 60
 
Mensajes: 77
Registrado: Vie Jul 01, 2011 11:35 am

Re: [Tutorial] Componentes DIY

Notapor sectario el Mié Sep 14, 2011 7:33 am

Se nota que se me ha acabado la jornada intensiva, y tengo ahora menos tiempo libre :lol:

Bueno, otro poquito.
Registro en sectarios.org: Enviame un correo a marcoa.ramirez arroba gmail.com
Leyendo... Ratas en las paredes
Avatar de Usuario
sectario
Cordura 0 Mitos Cthulhu 25
 
Mensajes: 9637
Registrado: Lun Oct 22, 2007 8:54 pm
Ubicación: Observando los Mi-go de Montserrat.

Re: [Tutorial] Componentes DIY

Notapor sectario el Jue Sep 15, 2011 4:00 pm

Bueno, otra entrega. Esto parece ya un coleccionable por fascículos
Registro en sectarios.org: Enviame un correo a marcoa.ramirez arroba gmail.com
Leyendo... Ratas en las paredes
Avatar de Usuario
sectario
Cordura 0 Mitos Cthulhu 25
 
Mensajes: 9637
Registrado: Lun Oct 22, 2007 8:54 pm
Ubicación: Observando los Mi-go de Montserrat.

Re: [Tutorial] Componentes DIY

Notapor keron el Jue Sep 15, 2011 6:03 pm

Sip :lol:
Avatar de Usuario
keron
Cordura 60
Cordura 60
 
Mensajes: 77
Registrado: Vie Jul 01, 2011 11:35 am

Re: [Tutorial] Componentes DIY

Notapor sectario el Vie Sep 23, 2011 4:13 pm

Otro entrega
Registro en sectarios.org: Enviame un correo a marcoa.ramirez arroba gmail.com
Leyendo... Ratas en las paredes
Avatar de Usuario
sectario
Cordura 0 Mitos Cthulhu 25
 
Mensajes: 9637
Registrado: Lun Oct 22, 2007 8:54 pm
Ubicación: Observando los Mi-go de Montserrat.

Re: [Tutorial] Componentes DIY

Notapor sectario el Dom Sep 25, 2011 10:02 pm

Pasito a pasito. Cuando esté acabado, algún día espero, borrare estos comentarios tontos sobre las actualizaciones :D
Registro en sectarios.org: Enviame un correo a marcoa.ramirez arroba gmail.com
Leyendo... Ratas en las paredes
Avatar de Usuario
sectario
Cordura 0 Mitos Cthulhu 25
 
Mensajes: 9637
Registrado: Lun Oct 22, 2007 8:54 pm
Ubicación: Observando los Mi-go de Montserrat.

Re: [Tutorial] Componentes DIY

Notapor sectario el Dom Oct 02, 2011 10:14 am

Un nuevo domingo... una nueva entrada. Creo que he llegado a la mitad del tutorial.
Registro en sectarios.org: Enviame un correo a marcoa.ramirez arroba gmail.com
Leyendo... Ratas en las paredes
Avatar de Usuario
sectario
Cordura 0 Mitos Cthulhu 25
 
Mensajes: 9637
Registrado: Lun Oct 22, 2007 8:54 pm
Ubicación: Observando los Mi-go de Montserrat.

Re: [Tutorial] Componentes DIY

Notapor keron el Lun Oct 03, 2011 12:12 pm

Ya va quedando menos. Ha ver si luego me entero de como se crean cuando lo tengas terminado, porque parece dificultad ULTRA HARD. :roll:
Avatar de Usuario
keron
Cordura 60
Cordura 60
 
Mensajes: 77
Registrado: Vie Jul 01, 2011 11:35 am

Re: [Tutorial] Componentes DIY

Notapor sectario el Vie Oct 21, 2011 6:42 pm

bueno, otra entrega.
keron escribió:Ya va quedando menos. Ha ver si luego me entero de como se crean cuando lo tengas terminado, porque parece dificultad ULTRA HARD. :roll:


Pues sí, yo más o menos lo voy siguiendo. Tampoco mucho, :lol: . Pero alguien que no tenga conocimientos de informática (java o programación orientada a objetos) creo que le puede ser bastante complicado. Y supongo que mi traducción deja bastante que desear. :oops:
Registro en sectarios.org: Enviame un correo a marcoa.ramirez arroba gmail.com
Leyendo... Ratas en las paredes
Avatar de Usuario
sectario
Cordura 0 Mitos Cthulhu 25
 
Mensajes: 9637
Registrado: Lun Oct 22, 2007 8:54 pm
Ubicación: Observando los Mi-go de Montserrat.

Siguiente

Volver a Strange Eons - Crea tus propios primigenios

¿Quién está conectado?

Usuarios navegando por este Foro: No hay usuarios registrados visitando el Foro y 1 invitado