Kurs XUL:Tworzenie okien dialogowych

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

Aplikacja XUL często wymaga wyświetlania okien dialogowych. Ten artykuł opisuje jak takie okna skonstruować.

Spis treści 1 Tworzenie okien dialogowych 2 Element okna dialogowego 2.1 Przykład okienka dialogowego 2.2 Przykładowe okno dialogowe wraz z dodatkowymi możliwościami 2.3 Więcej przykładów

[edytuj] Tworzenie okien dialogowych

Funkcja openDialog() stosowana jest do otwarcia okna dialogowego. Podobną funkcją jest open(). Różni się jednak pod kilkoma względami. Wyświetli okno, a nie okno dialogowe, z czego wynika, że oczekujemy jakiejś akcji użytkownika. Okno to może mieć subtelne różnice w sposobie pracy i w postrzeganiu je przez użytkownika. Te różnice wynikają z platformy, na której pracujemy.

W dodatku funkcja openDialog() może wymagać dodatkowych argumentów, poza trzema opisanymi wcześniej. Te argumenty są przesyłane do okienka dialogowego i umieszczane w obszarze przechowywanym we właściwościach argumentów nowego okna. Można przesłać tyle argumentów, ile jest potrzebne. Jest to bardzo wygodny sposób dostarczania wartości domyślnych do pól w oknie dialogowym.

var somefile=document.getElementById('enterfile').value;

window.openDialog("chrome://findfile/content/showdetails.xul","showmore",
                  "chrome",somefile);

W tym przykładzie zostanie wyświetlone okno dialogowe showdetails.xul. Przesłany mu będzie jeden argument somefile wzięty z wartości elementu o id enterfile. W skrypcie używanym przez to okienko dialogowe, możemy się odwołać do tego argumentu używając własności arguments okna. Na przykład:

var fl = window.arguments[0];

document.getElementById('thefile').value = fl;

Jest to bardzo efektywny sposób przekazywania wartości nowemu oknu. Można przesłać wartości z otwartego okna do oryginalnego na dwa sposoby. Po pierwsze można użyć własności window.opener, która pozostawia okno, z którego otwarto dialog. Po drugie można przesłać funkcję lub obiekt jako jeden z argumentów, a potem odwołać się do tej funkcji lub zmodyfikować obiekt w otwartym dialogu.

[edytuj] Element okna dialogowego

Element okna dialogowego powinien być używany zamiast elementu window, podczas tworzenia dialog. Zapewnia to użyteczną możliwość stworzenia nawet do czterech przycisków w dole okienka dialogowego na polecenia takie jak 'OK', 'Anuluj' itd. Nie musisz zamieszczać XUL-a dla każdego button, ale musisz pamiętać o kodzie, który wygeneruje odpowiednią akcję, gdy użytkownik naciśnie dany przycisk. Ta procedura jest niezbędna, ponieważ różne platformy mają odpowiednią dla siebie kolejność, w której pojawiają się te przyciski.

[edytuj] Przykład okienka dialogowego

Źródła Podgląd

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/global.css" type="text/css"?>

<dialog id="donothing" title="Przykład okienka dialogowego"
        xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
        buttons="accept,cancel"
        ondialogaccept="return doOK();"
        ondialogcancel="return doCancel();">

<script>
function doOK(){
  alert("Nacisnąłeś OK!");
  return true;
}

function doCancel(){
  alert("Nacisnąłeś  Cancel!");
  return true;
}
</script>

<description value="Zaznacz przycisk"/>

</dialog>

W oknie dialogowym możesz umieszczać elementy jakie tylko chcesz. Element dialog ma kilka dodatkowych możliwości, których nie posiadają elementy okien. Atrybut buttons jest używany w celu zdefiniowania, które przyciski mają się pojawić w oknie dialogowym. Następujące wartości mogą być użyte, gdy zostaną oddzielone przecinkami:

• accept - przycisk OK
• cancel - przycisk Anuluj
• help - przycisk Pomoc
• disclosure - przycisk szczegółów, służący do wyświetlania dodatkowych informacji

Możemy ustawić kod do wykonania po naciśnięciu jakiegoś przycisku, za pomocą atrybutów ondialogaccept, ondialogcancel, ondialoghelp i ondialogdisclosure. Jeśli wypróbujesz powyższy przykład, odkryjesz, że funkcja do doOK() jest wywoływana, gdy przycisk 'OK' został wciśnięty, a funkcja doCancel(), gdy wciśnięty został przycisk 'Anuluj'.

Te dwie funkcje doOK() i doCancel() - zwracają true, co oznacza, że okno dialogowe musi zostać zamknięte. Jeśli zwrócone byłoby false, to okno dialogowe pozostałoby otwarte. Jest to używane w przypadku wpisania błędnej wartości w pole w oknie dialogowym.

Użytecznymi atrybutami między innymi są:

• buttonlabelaccept - etykieta pokazująca się na przycisku akceptacji np. Zapisz
• buttonaccesskeyaccept - skrót klawiaturowy do zastosowania dla przycisku akceptującego np. Z
• defaultButton - przycisk jest aktywny, kiedy naciśnięty zostanie klawisz Enter

[edytuj] Przykładowe okno dialogowe wraz z dodatkowymi możliwościami

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/global.css" type="text/css"?>

<dialog id="myDialog" title="Moje okienko"
        xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
        onload="window.sizeToContent();"
        buttons="accept,cancel"
        buttonlabelaccept="Ustaw ulubione"
        buttonaccesskeyaccept="U"
        ondialogaccept="return doSave();"
        buttonlabelcancel="Anuluj"
        buttonaccesskeycancel="n"
        ondialogcancel="return doCancel();">

<script>
function doSave(){
 //doSomething()
 return true;
}
function doCancel(){
  return true;
}
</script>

<dialogheader title="Moje okienko dialogowe" description="Przykładowe okno"/>
<groupbox flex="1">
  <caption label="Wybierz ulubiony owoc"/>
  <radio id="orange" label="Oranges because they are fruity"/>
  <radio id="violet" selected="true" label="Strawberries because of colour"/>
  <radio id="yellow" label="Bananna because it pre packaged"/>
</groupbox>

</dialog>

Elementy przycisków mogą być dostępne z następującym kodem JavaScript

// przycisk accept
var acceptButt = document.documentElement.getButton("accept")

[edytuj] Więcej przykładów

Więcej przykładów znajdziemy w Dialogs and prompts (fragment kodu).

Następnie, zobaczymy jak otworzyć okienko dialogowe pliku.