Comandos

Un comando es una operación o función que se puede invocar.

El elemento comando

El elemento command se usa para crear comandos los cuales pueden ser usados para llevar a cabo operaciones. Usted no necesitaría usar comandos, ya que usted puede invocar un script para manejar las cosas. Sin embargo, un comando tiene la ventaja de que puede ser deshabilitado automáticamente cuando se necesite y puede ser invocado externamente sin necesidad de saber de los detalles de su implementación. Los comandos son una manera adecuada de abstraer operaciones del código. Además los comandos son muy útiles para aplicaciones extensas.

Para empezar, con el fin de implementar los comandos del menú portapapeles, cortar, copiar y pegar usted puede usar comandos. Si no usara comandos, usted necesitaría averiguar cual campo tiene el foco (focus), luego verificar para asegurarse que la operación es la adecuada para ese elemento. Además, los comandos del menú necesitarían ser habilitados y deshabilitados dependiendo de si el elemento enfocado haya seleccionado texto o no, y para las operaciones de pegar (paste), si hay algo adecuado en el portapapeles (clipboard) para pegar. Como puede ver, esto se vuelve complicado. Usando comandos, gran parte del trabajo es manejada para usted. Usted puede usar un comando para cualquier operación. Mozilla los usa para casi todos los comandos del menú. Ademas, campos de texto y otros accesorios tienen un número de comandos ya soportados y que usted puede invocar. Usted debería usarlos cuando la operación depende de cual elemento es enfocado.

Un comando es identificado por su atributo id. Mozilla usa la convención de que el id del comando comience con 'cmd_'. Usted probablemente querrá usar el mismo id si un comando está siendo usado, sin embargo para sus comandos propios, usted puede usar cualquier id de comando que desee. Para evitar conflictos, usted puede desear incluir el nombre de la aplicación en el id del comando. Una manera simple de usar comandos es como sigue:

Ejemplo: un sólo comando

Ejemplo 1: Código Ver en funcionamiento

<command id="cmd_openhelp" oncommand="alert('Ayuda!');"/>
<button label="Ayuda" command="cmd_openhelp"/>

En este ejemplo, en vez de colocar el atributo oncommand en el button, simplemente lo colocamos sobre un elemento command. Los dos son entonces enlazados usando el atributo command el cual tiene el valor del id del comando. El resultado es que cuando el botón es presionado, el comando: 'cmd_openhelp' es invocado.

Hay dos ventajas al usar ésta técnica:

• Primero, que transfiere todas sus operaciones a comandos los cuales pueden ser agrupados juntos en una sección del archivo XUL. Esto significa que el código está todo junto y no esparcido por el código UI.

• La otra ventaja es que muchos botones u otros elementos UI pueden ser enlazados al mismo comando. Para empezar, usted puede tener un menu item, un botón de barra de herramientas y un atajo de teclado todos para la misma operación. En vez de repetir el código tres veces, usted puede enlazar todos los tres al mismo comando. Normalmente, usted solo enlazará elementos que enviarían un evento de comando.

Adicionalmente:

• Si usted coloca el atributo disabled en el comando , el comando será deshabilitado y no será invocado.
• Cualquier botón y objeto del menú enlazados a éste serán deshabilitados automáticamente.
• Si usted rehabilita el comando, los botones se habilitan de nuevo.

Ejemplo: toggling command disabled

Ejemplo 2: Código Ver en funcionamiento

<command id="cmd_openhelp" oncommand="alert('Ayuda');"/>
<button label="Ayuda" command="cmd_openhelp"/>
<button label="Más ayuda" command="cmd_openhelp"/>

<button label="Desactivado"
        oncommand="document.getElementById('cmd_openhelp').setAttribute('disabled','true');"/>
<button label="Activado"
        oncommand="document.getElementById('cmd_openhelp').removeAttribute('disabled');"/>

En este ejemplo, ambos botones usan el mismo comando. Cuando un botón deshabilitar es presionado, el comando es deshabilitado al colocar su atributo desactivado, y ambos botones serán deshabilitados también.

Es normal colocar un grupo de comandos dentro de un elemento

commandset, junto cerca del inicio del archivo XUL, tal como en el siguiente:

<commandset>
  <command id="cmd_open" oncommand="alert('Abrir!');"/>
  <command id="cmd_help" oncommand="alert('Ayuda!');"/>
</commandset>

Un comando es invocado cuando el usuario activa el botón u otro elemento agregado al comando. Usted puede también invocar un comando al llamar el método doCommand cualquier elemento de lcomando o un elemento agregado al comando tal como un botón.

Command Dispatching

Es posible usar comandos sin el elemento comando elements, o al menos, sin añadir un atributo oncommand al comando. In this case, the command will not invoke a script directly, but instead, find an element or function which will handle the command. This function may be separate from the XUL itself, and might be handled internally by a widget. In order to find something to handle the command, XUL uses an object called a command dispatcher. This object locates a handler for a command. A handler for a command is called a controller. So, essentially, when a command is invoked, the command dispatcher locates a controller which can handle the command. You can think of the comando element as a type of controller for the command.

The command dispatcher locates a controller by looking at the currently focused element to see if it has a controller which can handle the command. XUL elements have a controladores property which is used to check. You can use the controladores property to add your own controllers. You might use this to have a listbox respond to cut, copy and paste operations, for instance. An example of this will be provided later. By default, only textboxes have a controller that does anything. The textbox controller handles clipboard operations, selection, undo and redo as well as some editing operations. Note that an element may have multiple controllers, which will all be checked.

If the currently focused element does not have a suitable controller, the window is checked next. The window also has a controladores property which you can modify if desired. If the focus is inside a frame, each frame leading to the top-level window is checked as as well. This means that commands will work even if the focus is inside a frame. This works well for a browser, since editing commands invoked from the main menu will work inside the content area. Note that HTML also has a commands and controller system although you can't use it on unprivileged web pages, but you may use it from, for example, a browser extension. If the window doesn't provide a controller capable of handling the command, nothing will happen.

You can get the command dispatcher using the document's commandDispatcher property, or you can retrieve it from the controllers list on an element or a window. The command dispatcher contains methods for retrieving controllers for commands and for retrieving and modifying the focus.

Añadiendo controladores

You can implement your own controllers to respond to commands. You could even override the default handling of a command with careful placement of the controller. A controller is expected to implement four methods, which are listed below:

supportsCommand (command) 

this method should return true if the controller supports a command. If you return false, the command is not handled and command dispatcher will look for another controller. A single controller may support multiple commands.

isCommandEnabled (command) 

this method should return true if the command is enabled, or false if it is disabled. Corresponding buttons will be disabled automatically.

doCommand (command) 

execute the command. This is where you would put the code to handle the command.

onEvent (event) 

this method handles an event.

Ejemplo: implementación del controlador

Let's assume that we want to implement a listbox that handles the delete command. When the user selects Delete from the menu, the listbox deletes the selected row. In this case, you just need to attach a controller to a listbox which will perform the action in its doCommand method.

Try opening the example below (Código Ver en funcionamiento) in a browser window and selecting items from the list. You'll notice that the Delete command on the browser's Edit menu is enabled and that selecting it will delete a row. (See Discussion about opening this example). The example below isn't completely polished. Really, we should ensure that the selection and focus is adjusted appropriately after a deletion.

<window id="controller-example" title="Ejemplo de controlador" onload="init();"
        xmlns="https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<script>
function init()
{
  var list = document.getElementById("laLista");

  var listController = {
    supportsCommand : function(cmd){ return (cmd == "cmd_delete"); },
    isCommandEnabled : function(cmd){
      if (cmd == "cmd_delete") return (list.selectedItem != null);
      return false;
    },
    doCommand : function(cmd){
      list.removeItemAt(list.selectedIndex);
    },
    onEvent : function(evt){ }
  };

  list.controllers.appendController(listController);
}
</script>

<listbox id="laLista">
  <listitem label="Ocean"/>
  <listitem label="Desert"/>
  <listitem label="Jungle"/>
  <listitem label="Swamp"/>
</listbox>

</window>

The controller (listController) implements the four methods described above. The supportsCommand method returns true for the 'cmd_delete' command, which is the name of the command used when the Delete menu item is selected. For other commands, false should be returned since the controller does not handle any other commands. If you wanted to handle more commands, check for them here, since you will often use a single controller for multiple related commands.

The isCommandEnabled method returns true if the command should be enabled. In this case, we check if there is a selected item in the listbox and return true if there is. If there is no selection, false is returned. If you delete all the rows in the example, the Delete command will become disabled. You may have to click the listbox to update the menu in this simple example. The doCommand method will be called when the Delete menu item is selected, and this will cause the selected row in the listbox to be deleted. Nothing needs to happen for the onEvent method, so no code is added for this method.

Override Default Controller

We attach this controller to the listbox by calling the appendController method of the listbox's controladores. The el objeto controlador has a number of methods that may be used to manipulate the controllers. For instance, there is also an insertControllerAt method which inserts a controller into an element before other ones. This might be useful to override commands. For example, the following example will disable pasting into a textbox.

var tboxController = {
  supportsCommand : function(cmd){ return (cmd == "cmd_paste"); },
  isCommandEnabled : function(cmd){ return false; },
  doCommand : function(cmd){ },
  onEvent : function(evt){ }
};

document.getElementById("tbox").controllers.insertControllerAt(0,tboxController);

In this example, we insert the controller at index 0, which means before any others. The new controller supports the 'cmd_paste' command and always indicates that the command is disabled. The default textbox controller never gets called because the command dispatcher found the controller above to handle the command first.

Seguimos con la actualización de comandos.