Introducción
===============

Qué es el Módulo de Scripting
----------------

El Módulo de Scripting es un módulo de programación integrado completamente en gvSIG 2.

Este módulo se integró desde las versiones 2.x de gvSIG, y ha sufrido importantes mejoras en gvSIG 2.3.

Qué necesitas
----------------
Para seguir esta guía tan solo necesitas tener instalado la versión de gvSIG 2.3. El Scripting Framework o Módulo de Scripting vienen instalados por defecto.

La última versión disponible de gvSIG 2 que podrás encontrar en:
http://www.gvsig.com/es/productos/gvsig-desktop/descargas

Qué nos permite
----------------
Este módulo de programación nos dará la oportunidad programar nuestras propias herramientas y extensiones para gvSIG.

Los scripts los podremos modificar, adaptar, intercambiar y desarrollar de una manera sencilla, y lo más importante, rápida.

Una de las ventajas es que dada la facilidad del lengauaje Python, no será necesario tener conocimientos extensos de programación ni de cómo funciona al completo la arquitectura de gvSIG para poder desarrollar la herramienta que necesitemos.

Las posibilidades son infinitas, nos permitirá:
- Automatizar tareas
- Añadir funcionalidades
- Crear nuevos geoprocesos
- Personalizar gvSIG
- Creación de extensiones (Plugins)
- Uso de la API de gvSIG: tratamiento de espaciales, conexiones de datos, generación de mapas, etc.

Qué lenguaje utilizamos
----------------
El lenguaje principal en el que hemos centrado el desarrollo es Jython, aunque también se pueden ejecutar scripts en Groovy, R..

Jython es una implementación de Python realizada en Java.
Esta implementación nos permite trabajar con la API de gvSIG (aplicación realizada en Java) usando scripts utilizando la sintaxis de Python, facilitando mucho el desarrollo y ejecución de estos, solo necesitando tener instalado gvSIG para poder programar.

Esto nos da unas ventajas enormes, por un lado, Python es un lenguaje muy sencillo de aprender, por otro lado, no se necesita de una compilación previa con un IDE externo, sino que la compilación del código necesario se realiza sobre la marcha, cada vez que ejecutamos nuestro script. Esto nos permite realizar modificaciones en nuestros script e irlo probando mientras tenemos gvSIG abierto.


Cómo acceder al Módulo de Scripting
----------------
Una vez instalado gvSIG 2 ya lo podemos abrir. Para acceder a este módulo de programación lo haremos a través del menú: Herramientas – Scripting. Aquí nos encontraremos con 3 opciones:

* Scripting Launcher:
Se trata de un lanzador de scripts, una lista con accesos directos a los scripts que tenemos.
Según vayamos creando y almacenando nuestros scripts, estos pasaran a formar parte de esta lista que podremos tener abierta y accesible para ejecutar un script que necesitemos en cualquier momento con un doble click. Es muy cómodo si preparamos scripts para ejecutarlos mientras estemos trabajando, una forma rápida de tenerlos a mano.


* Scripting Composer
Es la pantalla principal de este módulo. Aquí podremos crear, ordenar y almacenar todos nuestros scripts.

Los botones principales: Nuevo, Abrir, Guardar, Guardar y Ejecutar, Cerrar.. Una vez creemos un fichero nuevo, podremos escribir nuestro código.

La ejecución del script aparecerá reflejada en la consola que se sitúa en la parte inferior,

* Jython Console
Es una consola que nos permitirá ejecutar código directamente, ejecutándose línea a línea. Nos permite consultar variables y ver cómo se van modificando.

Otra función interesante es que nos ofrecerá una ayuda de los comandos que están disponibles según el código que estemos escribiendo, o qué tipo de métodos tienen disponibles las diferentes clases de gvSIG.

Librerías de gvSIG para Scripting
----------------
Hemos creado una librería escrita en Jython denominada gvsig. Su función es inyectar métodos extra en estas clases de Java ya existentes en la API de gvSIG y ampliar mediante nuevas funciones la potencia y facilidad de uso de este módulo.

Su objetivo es el disminuir el número de líneas requeridas para realizar ciertas operaciones y hacer accesible la API de gvSIG de una manera más sencilla desde Jython.

Las librerías Java de las que se compone gvSIG están totalmente accesibles desde nuestros scripts en Jython, siendo posible sin ninguna restricción en el acceso a ellas y en la creación de extensiones de la misma forma que si las hicieramos directamente en Java.

Organización de la librería gvsig
----------------
El Módulo de Scripting viene con diversas librerías:

- gvsig: pertenecen las funciones principales de gvSIG, principalmente para el acceso y manejo de datos. Contiene funciones útiles y los métodos inyectados en las clases de gvSIG. También contiene el resto de módulos que explicamos.
- gvsig.commonsdialog: encargada de la generación de ventanas, desde a mensajes de alerta a rutas de ficheros.
- gvsig.geom: contiene todas las funciones relacionadas con las geometrías

Además, hemos incluido otras clases importantes que nos ayudarán mucho la generación de scripts:

- `gvsig.libs.formpanel.FormPanel`: Esta clase nos ayudará en la generación de script con interfaces visuales
- `gvsig.libs.gvpy`: Librería para la ejecución de geoprocesos desde Scripting
- `gvsig.libs.toolbox.ToolboxProcess`: Clase para la creación de geoprocesos que serán añadidos a la Toolbox y podrán ser utilizados desde el Modelizador.
- `gvsig.libs.load_project.load_project()`: Función para abrir un proyecto en gvSIG desde un fichero.
- etc

Es recomendable importar tan solo las librerías necesarias para la ejecución del script.

Si nuestro script contiene otras librerías propias que también hemos programado, al realizar su importación podemos forzar la recarga de estas librerías (sino los cambios no se verán reflejados) utilizando la función `reload()`. La forma correcta de hacerlo sería:

import lib
reload(lib)

Creación de un script
----------------

Para crear un script nuevo, presiona el botón de Nuevo situado arriba a la izquierda, se nos abrirá una pantalla sobre el tipo de script a crear.

En esta pantalla debemos escribir el nombre y descripción de lo que vayamos a crear. En el tipo de archivo podremos elegir qué crear. Las opciones son:

- Script: Programa con código lineal que podremos ejecutar.
- Dialog: Programa con código y una interfaz visual. (No recomendado, para scripts con interfaz visual usaremos también el tipo script)
- Project: Aún no habilitado, para futuras versiones.
- Folder: Crea una carpeta en nuestra lista de "Scripts de usuario".

Podemos elegir el lenguaje de programación que prefiramos. Los lenguajes soportados son:
ECMAScript
Python: es el lenguaje en que tenemos centrado el desarrollo
Groovy

En Save on podremos elegir en qué carpeta guardamos nuestro nuevo script. Las dos últimas cajas de texto son sobre información del Autor y Versión.

**TODO**

.. |saveandexecute| image:: images\icon-saveandexecute.png
.. |save| image:: images\icon-save.png
.. |execute| image:: images\icon-execute.png

Para ejecutar un script guardando |save| y ejecutando |execute| o directamente presionaremos el botón |saveandexecute| y veremos su ejecución por consola.
Lo primero que podemos hacer es crear una carpeta donde guardaremos nuestros scripts de este curso. Lo haremos dando a New y rellenando la tabla eligiendo el Type: Folder como sigue a continuación:

Esto generará una carpeta en nuestra lista que podremos consular ahora:

Ahora ya podemos generar nuestro script, daremos al botón New y rellenaremos todos los datos. Durante esta guía se realizarán con el lenguaje de Python, un lenguaje muy intuitivo y sencillo para aprender, pero si domináis otro lenguaje de los del listado, el código sería muy parecido. Seleccionamos en qué carpeta queremos guardar el script, en este caso sería la carpeta “Guia” que hemos creado antes.

Hacemos click en "Accept". Esto creará nuestro nuevo fichero en blanco, que aparecerá abierto para su edición. Veremos que aparece nuevo en nuestro listado de scripts de usuario dentro de la carpeta antes creada, y se abre una pestaña con el nombre del script (el asterisco indica si el script contiene cambios que no han sido guardados), debajo aparece nuestro código que por defecto trae una plantilla con la estructura básica, y debajo del todo encontramos la salida por consola.
Los scripts creados se almacenan en la carpeta de gvSIG C:\Users\*\gvSIG\plugins\org.gvsig.scripting.app.extension. De forma similar en la /home/ de Linux.
Ahora nos disponemos a escribir nuestro primer script. El ejemplo que nos viene por defecto es totalmente válido::

	from gvsig import *
	def main(*args):
	   print "hola mundo"
	   pass
	   
En primer lugar, realiza una importación de la librería que vamos a utilizar que es la librería principal gvsig, y luego define dentro de la función principal main(), el comando print que hará salir nuestro valor por consola.
En Scripting en gvSIG la función que se va a ejecutar por defecto será siempre la función main(), así que debemos de introducir todo nuestro código en esta función.
Para ejecutarlo debemos de dar sobre el disco de guardado, siempre comprobamos que se haya guardado bien mirando que ya no aparece el asterisco en la pestaña de nuestro script (indicativo de que hay cambios no salvados), y a continuación presionamos el botón de ejecutar (la rueda dentada).
Podemos comprobar que la salida por consola es de "hola mundo", siendo este el objetivo que buscábamos. Con esto hemos ejecutado nuestro primer script con éxito, que quedará almacenado en nuestra lista.
Esta estructura es la estructura básica de un script en gvSIG 2. Contiene una parte donde importa las librerías a utilizar, y una función principal def main(*args): que contendrá todo el código que se ejecutará, pero también tenemos la posibilidad de crear funciones fuera de esta.
Si abrimos ahora el Scripting Launcher, en el menú de Scripting, veremos que ya aparece nuestro script en el nuevo listado.

Si nos envían un script, o queremos enviar el nuestro a un compañero, tenemos que irnos a la carpeta donde se encuentran almacenados estos:
C:\Users\NombreUsuario\gvSIG\plugins\org.gvsig.scripting.app.extension\scripts
En esta carpeta podemos copiar o pegar los scripts, fijándonos en copiar ambos archivos .py y .inf



Nueva integración con el API de gvSIG
---------------

Primero quería recordar que el Módulo de Scripting en gvSIG está centrado en su desarrollo en Jython, el cual nos permite mezclar código Java y código Python, usando la sintaxis de Python. 

Esto nos da unas ventajas enormes, por un lado, Python es un lenguaje muy sencillo de aprender para cualquiera que se anime, por otro lado, no se necesita de una compilación previa con un IDE externo, sino que la compilación del código necesario se realiza sobre la marcha, cada vez que ejecutamos nuestro script. Esto nos permite realizar modificaciones en nuestros script e irlo probando mientras tenemos gvSIG abierto.

Tenemos otras opciones a la hora de crear scripts como Groovy, pero ahora mismo hemos centrado el desarrollo en la parte de Jython por su facilidad y potencia. Si eres desarrollador Java, puedes programar de la misma forma desde Jython, solo cambiará la sintaxis del lenguaje, incluso puedes evitar usar las librerías que hemos desarrollado.

¿Qué hemos hecho?
+++++++++++++++++++

Para la nueva versión de gvSIG 2.3 hemos realizado cambios importantes en la integración de las librerías de Python con la API de gvSIG. En esta nueva integración, hemos seguido otra aproximación completamente diferente a la optada en las versiones anteriores. 

En vez de reescribir las clases que ya tiene gvSIG implementadas en su API, lo que se ha hecho es inyectar métodos extra en estas clases de Java ya existentes en gvSIG. A raiz de esto, incluso hemos añadido métodos directamente en la API de gvSIG dada su utilidad.


¿Por qué hemos hecho esto?
+++++++++++++++++++
De esta forma disminuimos mucho el esfuerzo requerido para mantener estas librerías, a la vez que aumentamos mucho la compatibilidad con gvSIG.

Uno de los fallos ocurridos en la versión anterior era la complicación de tener que trabajar a la vez con objetos Java y objetos Python, llevando a una incompatibilidad entre ellos y dificultad innecesaria en su desarrollo.

Además añadimos métodos y funciones nuevas, que disminuyen mucho el número de líneas requeridas para realizar ciertas operaciones. Siempre buscando facilitar al usuario el desarrollo de aplicaciones.

¿Qué implicaciones tiene?
+++++++++++++++++++
Que de esta forma, vamos a estar siempre trabajando con las clases de Java que vienen en gvSIG, y no trabajando en una mezcla entre librerías Python y Java que hacían referencia a lo mismo. 

Siempre recordar, que debido a que trabajamos con Jython, podremos crear clases que contengan caracteristicas de los dos mundos Python y Java. Podemos importar librerías de Python, librerías Jython que mezclen Java y Python, y librerías Java que ya disponga gvSIG o externas que añadamos o creemos.


¿A qué parte de las librerías afecta esta implementación?
+++++++++++++++++++
Principalmente a las clases que hacen referencia al tratamiento de datos. Hemos querido seguir simplificando esta parte para animar a los usuarios más nóveles interesados en generar geoprocesos nuevos o tratamiento de datos para poder hacerlo de una forma rápida y sencilla.

De la misma forma, hemos creado funciones que facilitarán la creación de objetos tales como capa, o el acceso a los ya cargados.

Además, hemos desarrollado algunas librerías extras realizadas en Jython como es FormPanel, que nos ayudará a generar scripts con interfaz gráfica.

¿Qué ventajas tiene?
+++++++++++++++++++
Facilitar mucho la comunicación entre nuestros scripts y la API de gvSIG. De esta forma queremos animar tanto a nuevos desarrolladores facilitando todas las operaciones típicas de tratamiento de datos, como a desarrolladores avanzados, asegurandonos la compatibilidad entre diferentes extensiones desarrolladas con Jython y gvSIG.

Dado que hay muchos cambios en las librerías y en herramientas, os animamos a que nos informéis de errores que detectéis en estas herramientas de Scripting.

