Migrar a la API 2.0 de Xojo

A continuación encontrarás traducida al Castellano la Guía de Migración al Framework 2.0 Xojo que se encuentra disponible en el área de documentación. Puedes encontrar el documento original en este enlace

Cuando creas aplicaciones con Xojo utilizas el Framework de Xojo. Este consiste en el conjunto de clases y módulos que proporcionan cosas como las ventanas, el acceso a los archivos y más.

API 2.0 es el esfuerzo de Xojo para hacer el modo en el que escribes código resulte más fácil y rápido, sustituyendo para ello las actuales API con unas que son más intuitivas y consistentes. Este documento proporcionará una visión general sobre API 2.0 y explica como puedes migrar a ella cuando estés preparado.

Visión general

Crear variables – La palabra clave DIM es la abreviatura de “dimensión” y ha permanecido desde el lenguaje original BASIC desde 1960. Si bien te has acostumbrado a ello lo cierto es que no resulta intuitiva; de modo que la hemos sustituido por Var, la abreviatura de “variable”.

Eventos – Cuando escribes código para responder a los eventos, es importante saber cuando tendrá lugar dicho evento en relación con la ejecución de tu código. Para que tu código funcione correctamente, necesitas saber si un evento ya ha ocurrido, o bien si está ocurriendo o tendrá lugar después de que se ejecute tu código. Los Eventos en Xojo incluyen ahora el tiempo verbal para hacer que esto resulte más obvio. Por ejemplo, el evento Open se llama ahora Opening. En el caso de una ventana, esto indica que la ventana está en el proceso de abrirse pero que aun no está abierta cuando se ejecuta el código.

Añadir/Eliminar Filas – Ahora es completamente consistente el uso de listas de datos. La acción de añadir filas a los array, ListBox, un PopupMen, un ComboBox y otros se hacer ahora mediante el método AddRow. Eliminar filas se hace mediante el método RemoveRow, o en el caso de que se quieran eliminar todas las filas utilizando el método RemoveAllRows.

Uso de Índices – Todos los índices están ahora basados en 0. Los métodos que terminan con la palabra “At” indican que el primer parámetro será un índice. Por ejemplo, AddRowAt indica que se añadirá una fila en el índice proporcionado. `RemoveRowAt` elimina una fila ubicada en el índice proporcionado. El índice siempre será el primer parámetro.

Recorrer datos – Esta es una operación muy común. El modo más sencillo de hacerlo es mediante un iterador que recorre una lista de datos sin precisar que mantengas una referencia del índice para acceder al elemento en curso. Por ejemplo, cuando recorres un array, has de asegurarte de empezar en 0 y continuar hasta la última fila del array. este tipo de bucle podría ser como el mostrado en el siguiente ejemplo:

For i = 0 To students.Ubound
  If students(i) = "Sally" Then SallyCount = SallyCount + 1

Next

Con un iterador, se asume que estás recorriendo todo el array y puedes crear una variable para acceder a cada fila:

For Each name As String In students
  If name  = "Sally" Then SallyCount = SallyCount + 1
Next

Las siguientes clases o propiedades soportan ahora la iteración:

Dictionary
Arrays
RowSet
URLConnection.ResponseHeaders
OpenFileDialog.SelectedFiles

En futuras ediciones se añadirán más elementos sobre los que se podrán iterar sus contenidos.

Evitar Errores con Literales – A menudo escribimos código en el que debemos tratar con números devueltos por una función, donde cada posible valor tiene un significado diferente. Esto puede derivar en código que resulta difícil de leer dado que el propósito del valor mágico no resulta obvio de forma inmediata. Las Enumeraciones resuelven este problema al proporcionar una palabra clave con significado y obvia que sustituye al valor mágico.

Por ejemplo, en las anteriores versiones de Xojo, cuando se definía la alineación del texto para un TextField, es probable que hubieses escrito código para centrar la alineación del texto como sigue:

TextField1.Alignment = 2

No resulta evidente qué significa 2 en este caso. La sustitución para `TextField.Alignment` es `TextAlignment`. Esta propiedad es una enumeración. Como resultado, el uso de la enumeración es requerido, lo que hace que el código sea más legible:

TextField1.TextAlignment = TextAlignments.Center

Ahora también es absolutamente claro lo que el código va a hacer. De igual modo, debido a que la anterior propiedad `Alignment` es un entero, debías de utilizar un valor literal (por ejemplo 2), de modo que cualquier error (como por ejemplo teclear 22 por accidente) no sería detectado por el compilador de Xojo o en cualquier otro tipo de error a la hora de ejecutar tus app. Las enumeraciones resuelven este problema porque el único modo de asignar valores es mediante la propia enumeración.

Las enumeraciones también son fáciles de autocompletar tal y como ocurre en casi todos los casos, el nombre de la enumeración es la forma plural del nombre de la propiedad con la que está asociada. Por ejemplo, la propiedad TextAlignment es una enumeración de tipo TextAlignments.

Gestionar Errores – En el pasado, muchas de las funciones de Xojo devolvían códigos de error cuando una función no tenía éxito. Si bien los errores son generalmente la excepción y no la regla, las buenas prácticas en el diseño de software indica que tu código ha de estar preparado para esta posibilidad. Tomemos este ejemplo (escrito tal y como se habría escrito con anterioridad a la API 2.0) que conecta una base de datos para encontrar un registro, actualizarlo y devolver un estado:

If db.connect Then
  Dim rs As RecordSet
rs = db.SQLSelect("SELECT ShipStatus WHERE TrackingNumber = " + TrackingNumber)
rs.edit
If db.Error Then
MsgBox("The record cannot be updated due to an error.")
Else
Dim today As New Date
rs.Field("LastChecked").StringValue = Today.SQLDate
rs.Update
End If
Return rs.Field("ShipStatus").StringValue
rs.close
Else
MsgBox("Database Error: " + db.ErrorMessage)
End If

Observa las instrucciones If requeridas para hacer la comprobación de errores. Con la API 2.0, prácticamente toda la comprobación de errores se realiza con excepciones. Esto hace que el código resulte más limpio dado que toda la comprobación de erroes se hace en un lugar.

Try
  db.connect
  Var rs As RowSet
  rs = db.SQLSelect("SELECT ShipStatus WHERE TrackingNumber = " + TrackingNumber)
  rs.EditRow
  rs.Column("LastChecked").StringValue = DateTime.Now.ToString
  rs.SaveRow
  Return rs.Column("ShipStatus").StringValue
rs.close
Catch error As DatabaseException
MessageBox("Database Error: " + error.Message)
End Try

Es más limpio, fácil de leer, toda la gestión de errores está en un lugar yn es un 25% menos de código. Con la API 2.0, prácticamente todo que solía devolver un código de error tiene un método en la API 2.0 que lanza una excepción. Pon tu código en una estructura Try…Catch como la que hemos visto anteriormente y así lograrás limpiar tu código un poco más.

Actualizar tu interfaz de usuario desde un Thread – Cuando tienes que realizar un proceso pesado que ha de ejecutarse, pero no quieres que tu aplicación sea inusable mientras que lo hace, entonces has de poner ese código en un Thread. Si dicha operación pesada ha sido iniciada por el usuario, resulta una buena práctica proporcionar al usuario algo de retroalimentación como pueda ser mediante el uso de un ProgressBar o un ProgressWheel. En las anteriores versiones de Xojo, la actualización de estos controles desde el evento Run de un Thread resultaba complicado porque (por razones demasiado complejas para discutir aquí), los hilos no pueden utilizarse para manipular directamente ninguna parte de la interfaz de usuario de tus aplicaciones.

Este proceso, sin embargo, se ha simplificado sobremanera en la API 2.0. Aún no puedes actualizar los controles de tu interfaz de usuario desde el evento Run de un Thread, pero puedes actualizarlos desde el nuevo evento Thread.UserInterfaceUpdate. Para lanzar este evento, sólo has de llamar a Thread.AddUserInterfaceUpdate desde el código en tu evento Thread.Run(como por ejemplo en un bucle) pasándole el dato que necesites para actualizar los controles de tu interfaz de usuario. Por ejemplo, si estás actualizando una ProgressBar, quizá quieras pasar un número entre el 1 y el 100 representando el porcentaje de la operación compleja que ya se ha completado. Esto provocará que se ejcute el evento Thread.UserInterfaceUpdate y reciba la información pasada. Desde este evento puedes actualizar entonces tu interfaz de usuario. Puedes ver un ejemplo de esto en la documentación de Thread.UserInterfaceUpdate

Mejoras

También hay una serie de mejoras “bajo el capot” para las clases. Por ejemplo:

FolderItem – En macOS, se ha reescrito desde cero la clase FolderItem utilizando la última y mejor de las API de Mac para asegurar la compatibilidad tanto ahora como en futuras versiones de macOS.

URLConnection – La nueva clase URLConnection (que forma parte de la API 2.0 pero que ya se había incluido en Xojo 2019r1), sustituye a la clase HTTPSocket, y proporciona soporte para HTTP 1.1 y posterior. También utiliza ahora la implementación subyacente del sistema operativo. Esto significa que, a medida que se actualice el sistema operativo, las apps que utilicen URLConnection también mejorarán automáticamente. En el caso de que el usuario tenga configurado un proxy, tu aplicación tomará ventaja de ello automáticamente.

SQL Más Seguro y Fácil – Los nuevos métodos Database.SelectSQL y Database.ExecuteSQL incorporan soporte para las instrucciones preprocesadas (PreparedStatements), sin necesidad de que debas de utilizar las clases PreparedSQLStatement.

Hacer la Transición

Proyectos Actuales – Puede hacer la transición a la API 2.0 a su gusto. Aunque muchas de las funciones que usen tus proyectos están acualmente deprecadas, estas no desaparecerán pronto. El primer paso es asegurarte de que tu proyecto funciona “tal cual” en 2019r2 antes de hacer cualquier cambio. Si es así, entonces estás listo para hacer la transición a la API 2.0.

Nuevos proyectos – Los nuevos proyectos sólo mostrarán elementos compatibles con la API 2.0. esto significa que sólo verás eventos compatibles con la API 2.0 en el cuadro de diálogo de New Event Handler, también verás sólo métodos y propiedades compatibles con la API 2.0 en el auto completado y sólo verás items compatibles con la API 2.0 cuando navegues por la Referencia del Lenguaje. Puedes ir directamente a un elemento deprecado en la Referencia del Lenguaje escribiendo su nombre completo en el campo de Buscar. Por ejemplo, al escribir FolderItem.Item te llevará al método Item incluso si ahora está deprecado. Estos items deprecados seguirán disponibles tanto en el framework como en la Referencia del Lenguaje durante muchos años para darte una buena cantidad de tiempo en la cual puedas realizar la transición.

Auto Completado – El rpimer lugar donde advertirás la API 2.0 es cuando utilices el Auto Completado. Los proyectos creados con versiones anteriores a Xojo 2019r2 aun mostrarán los métodos, propiedades y otros elementos que hayan sido deprecados junto con sus sustituciones en la API 2.0. Los proyectos creados en 2019r2 o posteriores no lo harán.

Sustituir Eventos – Como se ha mencionado anteriormente, se han renombrado muchos de los eventos para que resulte más claro cuando tiene lugar la ejecución de tu código. Puedes sustituir dichos eventos con sus nuevos equivalente haciendo doble clic sobre el nombre del anterior evento en el Navegador y seleccionando la opción Replace Event With… en el menú contextual. Opcionalmente, puedes convertir estos eventos abriendo el cuadro de diálogo `Add Event Handler`. Las nuevas versiones de los eventos se mostrarán en negrita. Selecciona uno y haz clic en el botón Convert para convertir un antiguo evento a su nuevo equivalente.

Encontrar elementos a Actualizar – Xojo no te dirá qué clases, propiedades y métodos utilizados deberían de sustituirse por sus correspondencias en la API 2.0 hasta que se lo pidas. Para ello, puedes hacer clic en el botón Analyze Item en la barra de herramientas del Editor de Código. Esto resultará en un listado de elementos en dicha clase o módulo que deberían de actualizarse. Si quieres un listado correspondiente a todo el proyecto, selecciona Project > Anlyze Project. En función del tamaño de tu proyecto, el listado de cosas que necesiten actualizarse puede ser bastante largo. No te dejes impresionar por esto. Tu proyecto continuará funcionando “tal cual”, de modo que puedes tomarte tu tiempo y actualizar tu proyecto a medida que necesites o quieras hacerlo.

Cuando estés listo para empezar – Una vez hayas decidido que estás preparado para hacer la transición de parte o el total de tu proyecto, y comenzar a utilizar los nuevos nombres de eventos, no habrá vuelta atrás; de modo que asegúrate de que realmente estás listo. Si un proyecto sin modificar funciona bien en 2019r2 (o posterior), entonces no hay probablemente ninfuna razón para volver a una versión anterior. Puedes continuar utilizando 2019r2 o posterior y actualizar entonces tu poyecto a la API 2.0 al ritmo que tenga sentido para ti. Una función, una clase o quizá todo el proyecto a la vez. Depende de ti. No hay ninguna prisa dado que las partes que estás sustituyendo continuarán funcionando durante muchos años.

Los pequeños detalles – Para más información y aspectos específicos sobre la transición consulta la página sobre la Guía de la API 2.0 en el área de documentación de Xojo.