Seguimos brindando explicaciones sobre las colas de efectos de jQuery y en este caso vamos a aprender a detener colas de efectos, algo que más tarde o más temprano vamos a necesitar cuando hagamos scripts interactivos que incluyan funciones de efectos.

Este es el cuarto capítulo del Manual de jQuery dedicado al tratamiento de colas en jQuery, cuya serie empezamos con el artículo Colas de efectos en jQuery.

Comenzaremos no obstante, explicando el último uso que nos queda por revisar del método queue().

.queue( [ nombreCola ], arrayFunciones )

En éste uso del método queue() enviamos dos parámetros:

• El primer parámetro opcional con el nombre de la cola (por defecto si no se indica nada se entiende la cola "fx" que es la predeterminada.
• El segundo parámetro es un array de funciones que se cargarán en la cola. Las funciones que pudiera haber en la cola se descartarán y se encolarán las nuevas funciones que se indican en el Array, cuya ejecución también será secuencialmente, tal como estén ordenadas en el array.

Un ejemplo de código donde hacemos este uso del método queue() es el que se puede ver a continuación:

$("#elemento").queue([function(){
   $(this).hide("slow");
   $(this).show("slow");
}]);

Como se puede comprobar, invocamos queue() indicando sólo un parámetro de tipo array, con lo cual estaremos modificando la cola predeterminada para asignarle las funciones del array. En este caso en el array hay una sola función que se ejecutará como siguiente paso de la cola.

Método stop([ limpiarCola ], [ saltarAlFinal ])

El método stop() sirve para detener la animación actual en la cola de efectos, pero atención, con stop() en principio sólo detenemos el efecto actual de la cola de efectos, por lo que los siguientes pasos de la cola, si es que había, seguirán ejecutándose. Podemos enviarle dos parámetros, ambos boleanos y opcionales:

• El parámetro limpiarCola sirve para eliminar todas las funciones que pudieran haber en la cola de efectos todavía por ejecutar. Si indicamos true, esas funciones se retirarían de la cola de efectos y por tanto no se ejecutarían más. Si no indicamos nada o se indica un false, ocurrirá que sólo se detenga el efecto o función actual y automáticamente se continuará con la siguiente función que pudiera haber encolada.
• El segundo parámetro, saltarAlFinal, sirve para que se detenga el efecto de animación actual, pero que se coloque directamente el valor final al que tendía ese efecto. Por defecto, este parámetro toma el valor false, que indica que la animación se para y se queda donde se había detenido. Por ejemplo en el caso false, si estamos ocultando una capa por medio de un efecto animado y hacemos un stop() la capa quedaría ocultada a medias. Sin embargo, si indicamos true en este parámetro, al hacer stop(), aunque no se haya terminado la animación para ocultar la capa, ésta se ocultaría del todo repentinamente.

Podemos ver varios ejemplos:

$("#elemento").stop();

Esto terminaría con el efecto que se está ejecutando en la cola, pero continuaría con los siguientes efectos que pudiera haber encolados.

$("#elemento").stop(true);

Terminaría con el efecto que se esté realizando y limpiaría la cola, con lo que no se ejecutarían otras funciones que pudiera haber.

$("#elemento").stop(false, true);

Terminaría el efecto actual pero saltaría en la animación para mostrar directamente el estado al que se llegaría si el efecto huviese continuado hasta el final. Luego continuaría automáticamente con la siguiente función de la cola.

Ejercicio con queue() y stop()

Ahora vamos a realizar un ejercicio completo con los métodos jQuery que acabamos de explicar. Se trata de hacer una animación, compuesta por varias funciones quese insertarán en la cola y varias pruebas de uso del método stop().

Si lo deseamos, puede ser una buena idea ver antes de continuar el ejercicio que vamos a realizar.

Comenzamos mostrando el código HTML de los elementos de este ejemplo:

<button id="botoncomenzar">Comenzar animación</button>
<br>
<button id="botonparar" class="botondetener">Pasar a la siguiente etapa de la animación</button>
<br>
<button id="botonpararllegar" class="botondetener">Pasar a la siguiente etapa, pero llegar hasta el final de donde se planeaba la animación</button>
<br>
<button id="botonparartodo" class="botondetener">Parar todo!</button>
<div id="micapa">Hola a todos!!!</div>

Como se puede ver, hay 4 botones. El primero servirá para poner en marcha la animación y los otros 3 para parar las funciones de la cola de efectos, de diversos modos, para que podamos practicar. Luego tenemos un elemento DIV con la capa que pretendemos animar.

El primero de los tres botones siempre permanece visible, pero los otros en principio no se muestran en la página, gracias a este CSS:

button.botondetener{
   display: none;
}

Ahora vamos a ver cada una de las funciones que cargaremos como eventos click, a ejecutar en cada uno de los botones. Comenzaremos con el botón que produce la animación en una cola de efectos.

$("#botoncomenzar").click(function(){
   capa = $("#micapa");
   capa.queue(function(continua){
      $("button.botondetener").show(500);
      continua();
   });
   //2 animaciones que tardan mucho
   capa.animate({"left": "0px"}, 5000);
   capa.animate({"left": "200px"}, 5000);
   capa.queue(function(continua){
      $("button.botondetener").hide(500);
      continua();
   });
});

Como vemos, tenemos una serie de funciones que se van a encolar. Como primer paso de la animación se hace una instrucción para que se muestren los botones que no estaban visibles.

Luego hacemos dos efectos animados, a los que les ponemos una duración de 5 segundos cada uno, lo suficiente para que nos de tiempo a detener la animación antes que estos efectos se lleguen a completar.

Ahora veamos los distintos eventos click para los botones que pararán la animación, con varios comportamientos ligeramente distintos.

$("#botonparar").click(function(){
   $("#micapa").stop();
});

Con esta función conseguiremos que se pare el paso actual de la animación, pero se continuará con el siguiente paso que haya en la cola de efectos.

$("#botonpararllegar").click(function(){
   $("#micapa").stop(false, true);
});

Con esta función hacemos que se detenga el paso actual de la animación, pero llevamos el elemento al lugar donde hubiera llegado si la animación hubiese continuado hasta el final. Luego continúa con los siguientes efectos encolados.

$("#botonparartodo").click(function(){
   $("#micapa").queue([]);
   $("#micapa").stop();
   
   //Esto mismo podría haberse hecho también así:
   //$("#micapa").stop(true);

   alert("Lo he parado todo!, ni se ocultarán los botones de parar. Pasos encolados: " + $("#micapa").queue().length)
});

Esta función es la más compleja de todas, pero realmente lo es porque he decidido complicarme un poco la vida. Veamos por qué.

$("#micapa").queue([]);

Con esto estoy cambiando la cola por defecto del elemento con id="micapa". Y esamos asignando una cola de efectos vacía, porque el array enviado como parámetro no tiene elementos. Con eso consigo quitar todas las funciones de la cola, pero hay que tener en cuenta que alguno de los efectos puede estar ejecutándose todavía y lo puedo parar con la sentencia:

$("#micapa").stop();

Con eso consigo que la animación se detenga tal como estuviera en ese mismo instante. Esto, si lo preferimos, se podría haber conseguido con una simple llamada al método stop():

$("#micapa").stop(true);

Para acabar, lanzo un mensaje al usuario, en una simple caja de alert(), para indicar los pasos que quedaron encolados en ese momento, que son cero, dado que hemos retirado todas las funciones de la cola.

Eso es todo, si lo deseas, puedes verlo en marcha en esta página aparte.

Ya hemos avanzado bastante en nuestro análisis sobre las colas de efectos de jQuery, pero aun nos quedan algunas cosas más que deberíamos aprender. En el próximo artículo aprenderemos a manejar el método delay() que nos servirá para crear intervalos de espera entre la ejecución de elementos de la cola.