Kurs XUL:Aktualizacja poleceń

z Mozilla Developer Center, polskiego centrum programistów Mozilli.

W tym artykule zajmiemy się aktualizacją poleceń.

[edytuj] 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ć:

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

Powyższy kod najpierw odzyskuje kontrolera dla polecenia cmd_paste 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.

<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.

[edytuj] 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:

<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.