Aktualizacja poleceń

W tym artykule zajmiemy się aktualizacją poleceń.

Wywoływanie komend

Jeśli element command posiada atrybut oncommand, możesz po prostu ją wywołać używając metody oncommand na komendę albo element przypisany do niej. Dla innych komend będziesz musiał użyć kilka dodatkowych linii kodu, np. gdy wywołujesz komendę zaimplementowaną przez kontroler. Dodatkowo będziesz musiał tego użyć, gdy tworzysz własne menu komend, np. żeby zaimplementować menu edytowania komend w swojej aplikacji.

Na szczęście dodatkowy kod jest w miarę prosty. Wszystko czego potrzebujesz to pobrać potrzebny kontroler i wywołać komendę. Oto prosty sposób aby to wykonać:

If a <code>command</code> has an <code>oncommand</code> attribute, you can just invoke it by using the <code>doCommand</code> method of the command or an element which is attached to it. For other commands, you will need to use a couple of additional lines of code. You will need to use these extra steps when invoking commands implemented by a controller. In addition, you will need to do this when creating your own menu commands, for instance to implement the edit menu commands in your own application. Fortunately, the extra code is fairly simple. All we need to do is get the needed controller and call the command. A simple way of doing this is the following:

var controller = document.commandDispatcher.getControllerForCommand("cmd_paste");
if (controller && controller.isCommandEnabled("cmd_paste")){
  controller.doCommand(command);
}

Powyższy kod najpierw odzyskuje kontrolera dla polecenia <tt>cmd_paste</tt> z rozdzielacza poleceń. Następnie, sprawdza czy polecenie jest włączone i wykonuje polecenie używając metody kontrolera doCommand . Zauważmy, że nie potrzebujemy zgadywać którego elementu albo którego kontrolera musimy użyć. Rozdzielacz komend zajmie się tym sam. Moglibyśmy również po prostu wywołać doCommand bez sprawdzania czy komenda jest dostępna, choć prawdopodobnie nie powinniśmy tak robić.

Powyższy kod jest wystarczająco ogólny, że może być funkcją wykonującą komendę, z komendą jako argumentem. Taka funkcja mogłaby być użyta wielokrotnie dla wielu komend. W rzeczywistości jest to bardzo częste, więc w Mozilli zawarta jest biblioteka, która właśnie to robi. Jeśli zawrzesz skrypt "chrome://global/content/globalOverlay.js" w pliku XUL, możesz wywoływać metodę goDoCommand , która wykonuje komendę przekazaną w argumencie. Kod tej funkcji to tylko kilka linijek, więc możesz zawrzeć go bezpośrednio w swoim kodzie, jeśli z pewnych powodów nie chcesz importować biblioteki.

The code above first retrieves the controller for the '<tt>cmd_paste</tt>' command from the command dispatcher. Then, it checks to see whether the command is enabled, and then executes the command using the <code>doCommand</code> method of the controller. Note that we don't need to figure out which element to use or which controller to use. The command dispatcher handles that part. Also, we could just call <code>doCommand</code> without checking if the command was enabled or not, although we probably shouldn't do that. The code above is generic enough that it can be a function that takes a command as an argument and executes that command. This function could then be reused for all commands. In fact, this is common enough that Mozilla includes a library which does just that. If you include the script '<tt>chrome://global/content/globalOverlay.js</tt>' in a XUL file, you can call the <code>goDoCommand</code> method which executes the command passed as the argument. The code for this function is only a few lines long so you could include it directly in your code if for some reason you didn't want to include the library.

<script src="chrome://global/content/globalOverlay.js"/>

<command id="cmd_paste" oncommand="goDoCommand('cmd_paste');"/>
<button label="Paste" command="cmd_paste"/>

Przykład powyżej zaimplementuje przycisk "Wklej" ( Paste ). Jest on dołączony do komendy, która wywoła komendę z określonego kontrolera. Kod ten to wszystko czego potrzebujesz, aby zaimplementować funkcjonalną komendę wklejania do swojej aplikacji. Jedyna inna rzecz, której potrzebujesz to upewnić się, czy status dostępności komendy wklej, a także przycisku, jest update'owany w odpowiednim czasie, co jest opisane poniżej.

The example above will implement a Paste button. It is attached to the command which will invoke the command on the necessary controller when called. The code above is all you need to implement the functionality of the paste command in your application. The only other thing you need to do is ensure that the enabled status of the paste command, and therefore the button, is updated at the right time, which is described below.

Command Updaters

Edytor komend to dodatkowa cecha elementu <commandset>, która pozwala edytować dostępne statusy jednej lub więcej komend, gdy zaszła pewna akcja. Musisz się zastanowić kiedy komenda jest ważna, a kiedy nie. Dodatkowo musisz rozważyć kiedy status może się zmienić i kiedy komenda powinna zostać edytowana.

Na przykład komenda "wklej" jest ważna, gdy coś dzieje się w oknie tekstowym i schowek nie jest pusty. Komenda stanie się dostępna za każdym razem, gdy kursor będzie w polu tekstowym i gdy zmieni się zawartość schowka. Edytor komend będzie wyczekiwał na te sytuacje i kod włączający lub wyłączający dostępność komend będzie wykonany.

Prosty edytor wygląda tak:

A command updater is an extra feature of the <code>commandset</code> element which allows it to update the enabled status of one or more commands when certain events happen. You will need to think about when a command is valid and when it is not. In addition, you will need to consider when the state could change and when the commands should be updated. For example, the paste command is valid when a textbox has the focus and there is something on the clipboard to paste. The command will become enabled whenever a textbox is focused and when the clipboard contents change. A command updater will listen for these situations and code can be executed which enables and disables commands as necessary. A simple command updater looks like this:

<commandset id="updatePasteItem"
            commandupdater="true"
            events="focus"
            oncommandupdate="goUpdateCommand('cmd_paste');"/>

Edytor jest oznaczony przez atrybut commandupdater , który powinien mieć wartość true . Atrybut events jest używany aby wypisać sytuacje, w które wsłuchuje się edytor. Możesz wyszczególnić wiele wydarzeń, przedzielając je przecinkiem. W powyższym przykładzie edytor czeka na wydarzenie, gdy kursor znajdzie się w odpowiednim polu ( focus event ). Sprawi to, że komenda zostanie edytowana.

Gdy pojawi się oczekiwane wydarzenie, zostanie wywołany kod w atrybucie oncommandupdate . W przykładzie wywołana jest metoda goUpdateCommand , która jest funkcją dostarczaną przez skrypt globalOverlay.js opisany wcześniej. Wyedytuje on komendę i dostosuje dostępność odpowiednich przycisków i elementów menu. Stojący za tym kod jest w miarę łatwy. Po prostu bierze wymaganego kontrolera, wywołuje jego metodę isCommandEnabled i dostosowuje dostępność komendy. Jeśli masz kilka komend do wyedytowania, wywołaj metodę goUpdateCommand dla każdej z nich.

Zauważmy, że edytor komendy otrzyma powiadomienia o wszystkich wydarzeniach z wszystkich elementów, nawet jeśli inny słuchacz wydarzeń na nie odpowiada. Tak więc edytor komend jest jak globalny słuchacz wydarzeń ( event handler ).

Edytorzy mają kilka wydarzeń, na które odpowiadają, wymienione poniżej. Można też stworzyć własne wydarzenia.

  • focus: pojawia się, gdy zmienia się miejsce kursora;
  • select: pojawia się, gdy zmienia się zaznaczony tekst;
  • undo: pojawia się, gdy buffer cofnięcia zmian się zmienia;
  • clipboard: pojawia się, gdy zmienia się zawartość schowka.

Następujący przykład pokazuje edytorów komend używanych w Mozilli do edytowania komend menu edycji. Użyte tu funkcje możecie znaleźć w skrypcie "chrome://communicator/content/utilityOverlay.js".

<commandset id="globalEditMenuItems"
            commandupdater="true"
            events="focus"
            oncommandupdate="goUpdateGlobalEditMenuItems()"/>
<commandset id="selectEditMenuItems"
            commandupdater="true"
            events="select"
            oncommandupdate="goUpdateSelectEditMenuItems()"/>
<commandset id="undoEditMenuItems"
            commandupdater="true"
            events="undo"
            oncommandupdate="goUpdateUndoEditMenuItems()"/>
<commandset id="clipboardEditMenuItems"
            commandupdater="true"
            events="clipboard"
            oncommandupdate="goUpdatePasteMenuItems()"/>

Następnie dowiemy się jak używać obserwatorów.

Autorzy i etykiety dokumentu

Etykiety: 
 Autorzy tej strony: fscholz, teoli, Ujoux, Mgjbot, Ptak82, Julcia r
 Ostatnia aktualizacja: fscholz,