Introducción

Como ya hemos comentado, podemos introducir código en lenguaje X++ en muchas partes del sistema. Los formularios no son una excepción.
Existen distintos ámbitos en los formularios donde podemos añadir código. Estos ámbitos son los siguientes:

• Formulario propiamente dicho
• Origen de datos del formulario
• Controles del formulario

Dependiendo de la funcionalidad que queramos implementar, escribiremos el código en un ámbito o en otro. No obstante, normalmente, se siguen las siguientes reglas:

1. Codificamos en los métodos del propio formulario, cuando queremos controlar la funcionalidad general del mismo.
2. Codificamos en los métodos del origen de datos, cuando queremos controlar la funcionalidad de los datos que aparecen en el formulario.
3. Codificamos en los controles, cuando queremos controlar la funcionalidad de alguno de los controles o elementos específicos que aparecen en el formulario.

Variables del sistema

Anteriormente se dijo que todas las variables deben ser declaradas antes de poder ser utilizadas. Sin embargo, cuando trabajamos con los formularios, algunas variables son declaradas implícitamente por el sistema.
Además de estas variables, es conveniente recordar que en cualquier momento, la variable this nos da acceso al elemento al que pertenece el método que estamos modificando.
 A continuación se describen las variables de sistema de los formularios y los elementos a los que dan acceso:

Formulario

Se trata de una variable de tipo FormRun, que recibe el nombre de element y que referencia al objeto formulario. Nos permite acceder a los métodos definidos a nivel de formulario.
La variable element se utiliza normalmente en asignaciones como la que mostramos a continuación:
Tb. Existe la variable form
notifyDate = element.design().control(Control::NotifyDate);

Tabla

Por cada uno de los orígenes de datos del formulario, disponemos de una variable llamada como éstos, que nos referencia la tabla que utilizamos en dicho origen de datos. Por ejemplo, suponiendo que el origen de datos del formulario se llamara DatosFormulario, tendríamos una variable con ese nombre que haría referencia a la tabla. En realidad, en un momento dado esta variable nos da acceso al registro activo de la tabla, de manera que podremos:
1.  Llamar a un método definido en la tabla. Por ejemplo:
DatosFormulario.setDefault(ReadWrite::Write);
2.  Hacer referencia a los campos individuales de la tabla. Por ejemplo:
number = DatosFormulario.accountNo;

Origen de datos

Tendremos también una variable llamada como el origen de datos del formulario con el sufijo “_DS” para hacer referencia a las propiedades y los métodos de dicho origen de datos. Por ejemplo, en el caso de que nuestro origen de datos se llamara DatosFormulario, tendríamos una variable llamada DatosFormulario_DS. Se trata de una variable de tipo FormDataSource que nos da la posibilidad de ejecutar directamente sus métodos. Por ejemplo:
DatosFormulario_DS.reSearch();

Consulta

Existen dos variables que nos permiten acceder a la consulta de un formulario:

1. Una variable de tipo Query llamada como el origen de datos del formulario con el sufijo “_Q” para hacer referencia a las propiedades y los métodos de la consulta (query). Por ejemplo, en nuestro caso, tendríamos una variable llamada DatosFormulario_Q. Esto nos da la posibilidad de ejecutar directamente sus métodos. Por ejemplo:

DatosFormulario_Q.levelNo(1);

1. Una variable de tipo QueryRun llamada como el origen de datos del formulario con el sufijo “_QR” para hacer referencia a las propiedades y los métodos de una instancia en ejecución de la consulta de dicho origen de datos (queryRun). Por ejemplo, en nuestro caso, tendríamos una variable llamada DatosFormulario_QR. Esto nos da la posibilidad de ejecutar directamente sus métodos. Por ejemplo:

DatosFormulario_QR.getNo(1);
Es importante señalar que en versiones anteriores de Axapta, no existían las variables declaradas implícitamente para la consulta (_Q) y para la instancia en ejecución de la consulta (_QR). Esto hace que nos podamos encontrar en muchos métodos todavía la forma tradicional de acceder a ellas desde código.
Para acceder a una consulta, debíamos hacer una declaración de variable, tras la cual podíamos utilizar la variable declarada para acceder a los métodos de dicha consulta. Por ejemplo, dentro de un origen de datos podríamos acceder a su consulta de la siguiente forma:

Ejemplo de declaración de una consulta
Query   q;
;
q = this.query();
q.levelNo(1);
Para acceder a una instancia en ejecución de una consulta, también debíamos hacer una declaración de variable. Siguiendo con el mismo ejemplo lo haríamos de la forma siguiente:

Ejemplo de declaración de instancia en ejecución de una consulta
QueryRun   qr;
;
qr = this.queryRun();
qr.getNo(1);
En ambos casos la variable this haría referencia al objeto en ejecución en ese momento, es decir, al origen de datos.

Métodos del formulario

Cuando creamos un nuevo formulario el sistema genera automáticamente un nodo de métodos.
Además de modificar los métodos creados por el sistema, el desarrollador puede añadir nuevos métodos con el propósito de añadir funcionalidad lógica al formulario.

Métodos de sistema

El nodo contiene lo que se llaman métodos virtuales, que son métodos implementados en MorphX, pero que pueden ser sobrecargados para cambiar el comportamiento por defecto de los formularios. En estos métodos la función llamada super() activa la ejecución del método implementado por MorphX.

Lista de métodos

Los formularios en MorphX tienen los siguientes métodos de sistema:

Métodos principales y su función

A continuación vamos a describir algunos de los métodos más utilizados en los formularios, que por su importancia merecen un tratamiento algo más exhaustivo.

Método ClassDeclaration

En este método se definen las variables globales del formulario. Es decir, aquéllas cuyo ámbito es el formulario en su totalidad y, por lo tanto, pueden ser utilizadas en cualquier método del formulario, de los orígenes de datos o de los controles.
Como ejemplo, veamos el método ClassDeclaration del formulario CustTable.
Ejemplo de método ClassDeclaration
class FormRun extends ObjectRun
{
  NumberSeq          numberSeq;
  CustAccount        numAllocated;
  FormStringControl  contactPerson;
  FormStringControl  contactPersonId;
}

Método Init

Se ejecuta cuando abrimos el formulario. Se utiliza, básicamente, para la inicialización de variables.
Debemos realizar una llamada al método super(), ya que éste es el encargado de crear una instancia en ejecución del formulario. Crea también el origen de datos, mediante una llamada al método Init del origen de datos.
Antes de la llamada al método super(), podemos modificar el formulario mediante los métodos de la clase FormBuild.
Tras el método super() y una vez creado el formulario, podemos inicializar variables.
Como ejemplo, tenemos el método Init del formulario CustTable.
Ejemplo de método Init
void init()
{
  super();
  contactPersonId = element.control(control::ContactPersonId);
  TaxVATNumTable::enableLookupVatNum(vatNum);
}

Método Run

Se ejecuta cuando abrimos un formulario, inmediatamente después del método Init.
La llamada al método super() hace que la ventana aparezca en la pantalla, y realiza una búsqueda en la base de datos para obtener los datos que deben mostrarse en el formulario. La consulta la realiza activando el método ExecuteQuery() del origen de datos.

Método Close

Se ejecuta cuando cerramos un formulario. La llamada a super() cierra la ventana del formulario, realiza las actualizaciones en la base de datos y activa el indicador booleano Closed. Dependiendo del estado en el cual cierre el formulario, el método Close se activa desde CloseCancel o desde CloseOK.
Como ejemplo, tenemos el método Close del formulario CustTable.
Ejemplo de método Close
void close()
{
  if (!custTable.recId && numberSeq)
    numberSeq.abort();
  super();
}

Acceso a los controles desde el código

Desde cualquier método podemos acceder a las propiedades y métodos de los controles del formulario. Para ello, necesitamos tener una referencia al control, que se puede obtener de dos formas:

1. Mediante la propiedad Autodeclaration de los controles

1. Mediante métodos de las clases de sistema

Todos los controles de un formulario tienen una propiedad llamada Autodeclaration. Por defecto, esta propiedad está desactivada, pero si la activamos, el sistema crea de modo automático una variable con el mismo nombre del control que nos da acceso a todas sus propiedades y métodos. Esta propiedad es una novedad de la versión 2.0 de Axapta, por lo tanto nos encontraremos que en muchas ocasiones no se hace uso de ella y se utilizan las clases de sistema para hacer referencia a los controles. Sin embargo, es recomendable hacer uso de las propiedades de los elementos de la aplicación, ya que nos ahorran código innecesario.
Para crear una referencia a un control de un formulario mediante el segundo método debemos seguir los siguientes pasos:

1. Declarar una variable de tipo control
2. Inicializar la referencia
La variable de referencia debe ser declarada en el método ClassDeclaration del formulario. El tipo de datos de la variable depende del tipo de control al que queramos hacer referencia. Por ejemplo, para hacer referencia a un campo de texto, deberemos crear una variable de tipo FormStringControl, para hacer referencia a un botón, la variable será de tipo FormButtonControl, etc. Estas clases pueden encontrarse en la documentación del  sistema en el Árbol de Objetos de la Aplicación.
Ejemplo
FormButtonControl  button;
La inicialización de las variables debe hacerse en el método Init, haciendo uso de los métodos de la clase de sistema FormRun.
Suponiendo que en nuestro formulario tuviéramos un control de tipo botón llamado ButtonName, tendríamos el siguiente ejemplo, donde se asignaría dicho botón a la variable button:
Ejemplo
button = element.design().control(Control::ButtonName);
Una vez inicializada la variable, podemos cambiar las propiedades del control en cualquier momento utilizando sus propios métodos. A continuación mostramos un ejemplo de esto:
Ejemplo
button.enabled(false);
A continuación presentamos un ejemplo, donde podemos observar la asignación de controles de un formulario a variables previamente declaradas.
Ejemplo de declaración de controles
class FormRun extends ObjectRun
{
  FormCheckBoxControl  includeAll;
  FormStringControl    interestNote;
  FormDateControl      interestDate;
}

void init()
{
  super();
  includeAll = element.control(control::ShowOpen);
  interestNote = element.control(control::InterestNote);
  interestDate = element.control(control::InterestDate);
}
Por otra parte, si sabemos que no vamos a necesitar hacer referencia al control más de una vez, podemos eliminar la variable y cambiar la propiedad de dicho control en una sola sentencia.
Ejemplo
element.design().control(Control::ButtonName).enabled(false);

Métodos del origen de datos

Cuando creamos un nuevo formulario debemos definir un origen de datos, que nos da acceso a la información almacenada en la base de datos.
Al definir un origen de datos, se crea automáticamente un nodo de métodos.

Métodos de sistema

Lista de métodos

Los orígenes de datos en los formularios tienen los siguientes métodos de sistema:

Métodos de validación

Como hemos visto en la lista anterior, los orígenes de datos tienen sus propios métodos de validación. Estos métodos son los siguientes:

ValidateDelete

Este método se ejecuta justo antes de que un registro vaya a ser borrado. La llamada al método super() invoca al método ValidateDelete de la tabla asociada.
Utilizamos este método cuando queremos añadir nuestras propias comprobaciones de validación antes del borrado de los registros de la base de datos.

ValidateWrite

Este método se ejecuta justo antes de que un registro vaya a ser escrito o actualizado. La llamada al método super() invoca al método ValidateWrite de la tabla asociada.
También utilizamos este método cuando queremos añadir nuestras propias comprobaciones de validación antes de la actualización o escritura de los registros en la base de datos.
Como podemos apreciar, existe un paralelismo entre los métodos de la tabla y los métodos del origen de datos de un formulario. En realidad, los métodos de validación del origen de datos llaman a los de la tabla asociada. A partir de esto podemos llegar a la conclusión de que introduciremos los métodos de validación en un sitio o en otro dependiendo de nuestro objetivo.
Supongamos que tenemos varios formularios que trabajan con los mismos datos. Cada uno de ellos tendrá su propio origen de datos, pero todos esos orígenes de datos tendrán asociada la misma tabla. Si nosotros queremos validar el borrado o la escritura de los registros en todos los formularios, será más conveniente hacer la comprobación directamente en los métodos de validación de la tabla, ya que solo tendríamos que escribir el código una vez. Esta validación sería efectiva en todos los orígenes de datos que tuvieran dicha tabla asociada.
Por el contrario, vamos a considerar que en un formulario específico necesitamos realizar una validación especial cuando queremos insertar un registro. Esta comprobación será más conveniente hacerla sobre los métodos de validación del origen de datos de dicho formulario. No sería válido hacerlo en los métodos de la tabla, porque de esta forma estaríamos forzando a todos los formularios a realizar esta validación.
A continuación, vamos a ver cual es la secuencia de ejecución de métodos cuando intentamos escribir o actualizar un registro desde un formulario. Podemos verlo de manera gráfica en el siguiente esquema:

Figura 8. Escritura de un registro. Secuencia de ejecución de métodos.
La secuencia de ejecución sería la siguiente:

1. ­­Se ejecutaría el método ValidateWrite del origen de datos del formulario. Este a su vez llamaría al método ValidateWrite de la tabla asociada.
2. Se ejecutaría le método Write del origen de datos del formulario.
3. Se llamaría al método Insert o al método Update de la tabla asociada al formulario, dependiendo de si la operación a realizar en una inserción o una actualización de registro.

Métodos principales y su función

A continuación vamos a describir algunos de los métodos más utilizados en los orígenes de datos de los formularios, que por su importancia merecen un tratamiento algo más exhaustivo.

Método Init

Se ejecuta cuando abrimos un formulario.
La llamada al método super() crea la consulta para cargar los datos en el formulario. Tras esta llamada deben añadirse, en caso de que sea necesario, las sentencias de modificación de la consulta.
Como ejemplo, presentamos el método Init del origen de datos del formulario CustTrans.
Ejemplo de método Init
void init()
{
  super();
  dataSource = this.query().dataSourceNo(1);
  criteriaOpen = dataSource.addRange(fieldnum(CustTrans,open));
}

Método ExecuteQuery

El método ExecuteQuery se ejecuta cuando abrimos un formulario para ver sus datos.
La llamada al método super() ejecuta la consulta generada por el método Init y muestra los registros. Si deseamos modificar los criterios de selección, debemos insertar las sentencias correspondientes antes de la llamada a super().
Como ejemplo, presentamos el método ExecuteQuery del origen de datos del formulario CustTrans.
Ejemplo de método ExecuteQuery
void executeQuery()
{
  switch (includeAll.value())
  {
    case (1) :
    {
      criteriaOpen.value('1');
      break;
    }
    case (0) :
    {
      criteriaOpen.value('0..1');
      break;
    }
  }
  super();
}
En este ejemplo, vemos que el método puede servirnos para establecer dos criterios distintos de selección en la consulta antes de la llamada al método super().

Método Active

Se ejecuta cada vez que cambia el registro activo. Esto sucede cuando pasamos de un registro a otro y también cuando pasamos de un formulario a otro.
La llamada a super() hace que el nuevo registro pase a ser el registro actual. Como ejemplo, presentamos el método Active del origen de datos del formulario Unit.
Ejemplo de método Active
int active()
{
  int ret;
  ;
  ret = super();
  Unit_Unit.allowEdit(!Unit.recId);
  return ret;
}

Método LinkActive

El método LinkActive se ejecuta cuando el usuario cambia de registro en un formulario que tiene su origen de datos enlazado con otro origen de datos. Este método solo es utilizado cuando se ha establecido un enlace entre dos orígenes de datos, poniendo la propiedad LinkType a valor Yes en el origen de datos.
La llamada al método super() activa el método ExecuteQuery del origen de datos enlazado con el origen de datos principal.
Como ejemplo, presentamos el método LinkActive del origen de datos SalesLine del formulario SalesTable.
Ejemplo de método LinkActive
void linkActive()
{
  super();
  if (!salesLine)
    element.setCaptionText();
}

Método Reread

La llamada al método super() vuelve a leer el registro actual de la base de datos. El sistema no activa este método de forma automática.

Método Research

La llamada al método super() refresca la recuperación de registros de la base de datos, definida por la consulta que se genera automáticamente en el método Init. Corresponde a una llamada al método ExecuteQuery con la excepción de que se mantienen ciertas cosas, como los filtros, el orden de los registros, etc.
El sistema no activa este método de forma automática.
Para comprender bien el funcionamiento del método Research, vamos a ver las diferencias existentes entre dicho método y el método ExecuteQuery.
 Si queremos refrescar el contenido del formulario con los registros que han sido insertados desde un método al cual hemos llamado, debemos utilizar el método Research.
Por el contrario, si queremos cambiar la consulta para mostrar otros registros, quizás basados en un filtro modificado, debemos utilizar el método ExecuteQuery.

Método Refresh

La llamada al método super() actualiza la pantalla, refrescando el contenido del registro activo sin leerlo desde el disco.
El sistema no activa este método de forma automática. Nosotros podemos utilizarlo, por ejemplo, si necesitamos actualizar los datos dentro de una operación más compleja.

Método Write

El método Write se ejecuta cuando el usuario introduce un nuevo registro o actualiza uno ya existente. Este método es el equivalente a los métodos Insert y Update de las tablas, realizando una u otra operación dependiendo de que exista ya el registro sobre el que vamos a escribir o no.
La llamada al método super() activa el método ValidateWrite, y en el caso de que éste devuelva verdadero, gestiona la acción de escritura sobre la base de datos. Como ejemplo, presentamos el método Write del origen de datos del formulario LedgerJournalTable.
Ejemplo de método Write
void write()
{
  super();
  if (newJournalNum)
  {
    ledgerJournal.usedVoucher();
    ledgerJournal = null;
    newJournalNum = false;
  }
}

Método Delete

El método Delete se ejecuta cuando el usuario borra un registro en el origen de datos.
La llamada al método super() activa el método ValidateDelete y en el caso de que éste devuelva verdadero, gestiona la acción de borrado sobre la base de datos, realizando una llamada al método Delete de la tabla.
Como ejemplo, presentamos el método Delete del origen de datos del formulario LedgerJournalTable.
Ejemplo de método Delete
void delete()
{
  this.returnJournalNum();
  super();
}
Es muy importante destacar que en un formulario los orígenes de datos enlazados son tratados como un único origen de datos. Es decir, las operaciones de selección, actualización y creación de registros desde el formulario se realizan sobre todas las tablas enlazadas. El método Init se ejecuta también en todos los orígenes de datos. Por otro lado, los métodos de notificación (como el método Active) se ejecutan también en todos los orígenes de datos.

Acceso y modificación de las consultas en los formularios

Todos los formularios con un origen de datos tienen una consulta activa, generada automáticamente en el método Init de dicho origen de datos. Como hemos visto anteriormente, existe una variable de sistema que nos da acceso a dicha consulta.
En algunos casos es necesario modificar la consulta mediante programación. Vamos a ver mediante un ejemplo, cómo modificar en tiempo de ejecución los criterios de selección de la consulta de un formulario. El ejemplo corresponde al formulario CustTrans.
En primer lugar, se declaran en el método ClassDeclaration del formulario las variables que consideremos necesarias. Los tipos de datos de estas variables corresponderán a clases de sistema. Así, por ejemplo, la clase QueryBuildDataSource nos da acceso al origen de datos de una consulta y la clase QueryBuildRange  nos da acceso al rango de selección de registros. La información acerca de los métodos de estas clases puede encontrarse en la documentación del sistema, dentro del Arbol de Objetos de la Aplicación.
Ejemplo
class FormRun extends ObjectRun
{
  QueryBuildDateSource  dataSource;
  QueryBuildRange       criteriaOpen;
}

A continuación deben inicializarse las variables de referencia. Para ello debe añadirse código al método del origen de datos. Las sentencias correspondientes deben insertarse después de la llamada al método super(), ya que éste es el encargado de crear la consulta. Hacer esto es equivalente a inicializar dichas variables antes de la llamada al método super() en el método Run.
Ejemplo
void init()
{
  super();
  dataSource = CustTrans_Q.dataSourceNo(1);
  criteriaOpen = dataSource.addRange(fieldnum(CustTrans,open));
}
Una vez inicializadas las variables, podremos modificar el rango de selección de registros. Esto se realiza antes de la llamada al método super() del método ExecuteQuery.
Ejemplo
void executeQuery()
{
  criteriaOpen.value('0..1');
  super();
}
Como ya mencionamos anteriormente, en versiones más antiguas de Axapta, no existían las variables declaradas implícitamente para las consultas. En ese caso habría que acceder a la consulta mediante métodos de las clases de sistema, tal y como muestra el ejemplo:
Ejemplo
void init()
{
  super();
  dataSource = this.query().dataSourceNo(1);
  criteriaOpen = dataSource.addRange(fieldnum(CustTrans,open));
}
Como podemos apreciar, sustituiríamos la variable CustTrans_Q por this.query(), donde this haría referencia al origen de datos del formulario y query() sería el método que nos devuelve la consulta de dicho origen de datos.

Métodos en los controles

En MorphX, además de introducir código en el propio formulario y en el origen de datos, podemos introducir código en los controles de dicho formulario.
Trataremos de codificar lo menos posible en los controles, dado que el código que introduzcamos en estos métodos no podrá ser utilizado para otros elementos. Todos aquellos procesos generales que queramos realizar con el formulario deberemos codificarlos en los métodos del propio formulario o en los del origen de datos. Únicamente codificaremos en los controles, cuando queramos controlar su funcionalidad.
La lista de métodos de los controles es interminable, dado que existen muchos tipos de controles y cada uno de ellos tiene sus propios métodos. Podemos obtener una lista completa de los métodos en la Guía del desarrollador de Axapta.
Únicamente vamos a destacar por su importancia dos métodos:

Método Clicked

Este método existe en los controles de tipo CheckBox, Button, CommandButton y MenuItemButton. Se ejecuta cuando el usuario “pincha” sobre el control correspondiente.
En los botones de tipo MenuItemButton, la llamada al método super() ejecuta el menú item correspondiente. En el caso de los botones CommandButton, se ejecuta el comando asociado al botón. En los botones de tipo Button, la llamada a super() no realiza ninguna acción.

Método Lookup

Este método existe en los controles de tipo StringEdit, IntEdit, RealEdit y DateEdit. Se ejecuta cuando el usuario pulsa el botón de lookup.

Normalmente se añade código a este método cuando el desarrollador desea que se abra una ventana de búsqueda distinta de la ventana estándar.

Secuencia de ejecución de métodos

Cuando realizamos acciones sobre un formulario, ejecutamos los métodos del propio formulario y los de su origen de datos. La ejecución de estos métodos sigue una secuencia determinada, que nos va a condicionar el funcionamiento del sistema. Por lo tanto, es muy importante conocer esa secuencia, ya que esto nos permitirá poder determinar qué método debemos codificar para obtener los resultados esperados.
Por ejemplo, veamos en el siguiente esquema qué métodos se ejecutan cuando abrimos un formulario:

Figura 9. Apertura de un formulario. Secuencia de ejecución de métodos.
La secuencia de ejecución de métodos es la siguiente:

1.  Método constructor New.
2.  Método Init del formulario.
3.  Método Init del origen de datos del formulario.
4.  Método Run del formulario.
5.  Método ExecuteQuery del origen de datos del formulario.
6.  Método NextField del formulario.
A continuación, vamos a ver la secuencia de ejecución que tiene lugar cuando cerramos un formulario. Podemos apreciarla en el siguiente esquema:

Figura 10. Cierre de un formulario. Secuencia de ejecución de métodos.
La secuencia de ejecución de métodos es la siguiente:

1.  Método CloseCancel del formulario.
2.  Método CanClose del formulario.
3.  Método Close del formulario.
Por último, vamos a ver qué métodos se ejecutan cuando salimos de un control de un formulario:

Figura 11. El usuario sale de un control. Secuencia de ejecución de métodos.
La secuencia de ejecución de métodos es la siguiente:

1.  Método Leave del control.
2.  Método Validate del control.
3.  Método Modified del control.
4.  Método Validate del origen de datos del formulario.
5.  Método ValidateField de la tabla.
6.  Método Modified del origen de datos del formulario.

Volver