[< Poprzedni rozdział] [Spis treści] [Strona Alladyn Project online >]
7. Opis języka - language reference.
Poniżej znajduje się dokładny opis obiektów, właściwości i metod wprowadzanych przez Alladyna.

7.1. Obiekt vlay.
Jest to obiekt będący podstawą DOM Alladyna. To właśnie w nim po przebudowaniu DOM przeglądarki znajdują się wszystkie warstwy dokumentu. Jest on tożsamy do znanych z IE oraz NS4 document.all i document.layers.
Dostęp do warstw zawartych w tym obiekcie możliwy jest na dwa sposoby:
vlay.nazwawarstwy
lub
vlay["nazwawarstwy"]
Warstwy w modelu opartym na vlay posiadają następujące, dodane przez Alladyna, właściwości i metody:

7.1.1. Obiekt style (vlay.nazwawarstwy.style).
Obiekt, zawierający wszystkie CSS-owe właściwości warstwy: top, left, width, height, color, wszystkie właściwości z rodziny font (fontFamily, fontSize itp.) itd.

7.1.2. Metoda vpos(left,top).
Jest to metoda pozwalająca na szybkie przemieszczenie warstwy w podane miejsce. Jest odpowiednikiem jednoczesnego pisania do właściwości style.left i style.top. Umieszczona, podobnie jak inne rozszerzenia Alladyna, bezpośrednio w obiekcie warstwy, pozwala na szybki dostęp do przemieszczania warstw.
Przykładowe użycie:
vlay.nazwawarstwy.vpos(10,100)
7.1.3. Metoda vclip(top,right,bottom,left).
Metoda pozwala na kadrowanie warstwy do zadanych brzegów. Parametry top, right, bottom, left to odpowiednio górna, prawa, dolna i lewa krawędź kadru.
Przykład użycia:
vlay.nazwawarstwy.vclip(0,400,300,100)
7.1.4. Metoda voppacity(opacity).
Metoda służąca do zdefiniowania przeŸroczystości warstwy. Podany parametr określa stopień widzialności warstwy i może przyjmować wartości od 0 do 100. Wartość parametru równa 0 oznacza całkowitą niewidoczność warstwy, 100 zaś oznacza brak przeźroczystości. Wszelkie wartości pomiędzy określają stopień przeźroczystości warstwy.
Przykład użycia:
vlay.nazwawarstwy.vopacity(75)
Ze względu na to, iż NS4 nie obsługuje przeźroczystości, w Alladynie została zaimplementowana dwustopniowa emulacja przeźroczystości w przypadku tej przeglądarki. Standardowo wartości opacity mniejsze niż 50 oznaczają niewidoczność warstwy, zaś 50 oraz większe - jej widoczność (z pełną nieprzeźroczystością). Można jednak tą wartość graniczną (poniżej której w przypadku NS4 warstwa jest niewidoczna) zdefiniować samemu i to zarówno indywidualnie (dla pojedynczej warstwy) jak i globalnie (dla wszystkich warstw).
Wartość tą określają zmienne vlay.nazwawarstwy.vol (odnosząca się do konkretnej warstwy) oraz STPE.vol (odnosząca się do wszystkich warstw).

7.1.5. Właściwość vol.
Właściwość ta określa próg symulacji przeźroczystości dla NS4 (patrz metoda vopacity) dla danej warstwy. Wartości opacity poniżej tej liczby spowodują ukrycie warstwy w NS4, zaś równe i większe - pokazanie jej z pełną nieprzeźroczystością.
Jeśli wartość tej właściwośći jest niezdefiniowana (jak to jest domyślnie), próg przeźroczystości określa zmienna STPE.vol.
Właściwość ta ma znaczenie oczywiście tylko w przypadku NS4, który nie obsługuje przeźroczystości.

7.1.6. Metoda vHTML(zawartość).
Metoda pozwala na podmienienie zawartości warstwy na nową. Po jej wykonaniu do warstwy zostanie wpisana nowa zawartość, która może być zarówno czystym tekstem, jak i zawierać może znaczniki HTML.
Należy pamiętać, iż NS4 przy zapisywaniu do warstwy resetuje stylowe formatowanie warstwy i jeśli chcemy, żeby po użyciu vHTML warstwa nadal wyglądała poprawnie, należy zapisać warstwę wraz z odpowiednimi stylami.
Przykład użycia:
vlay.nazwawarstwy.vHTML("<span class='font-family: Arial; font-size: 12px; color: red;'>nowa zawartość warstwy!</span>");
7.1.7. Metoda vkf({elementy zmieniane},ilość kroków).
Jest to metoda służąca do definiowania klatek kluczowych (keyframów) opisujących ruch warstw oraz zmianę ich wyglądu w czasie.
Ilość kroków to liczba klatek, w których ma zostać wykonany ruch pomiędzy poprzednią klatką kluczową a definiowaną. W szczególnym przypadku, gdy wartość ta jest równa 1, następuje natychmiastowe osiągnięcie klatki kluczowej - w jednym kroku.
Elementy zmieniane to te parametry opisujące warstwę, które mają się zmienić pomiędzy poprzednia klatką kluczową a definiowaną. Powinny być one zamknięte w nawiasach klamrowych, zaś poszczególne pary nazwa:wartość oddzielone powinny być przecinkami.
Składnia polecenia wygląda następująco:
vlay.nazwawarstwy.vkf({nazwa:wartość,nazwa:wartość, ...,nazwa:wartość},liczba_klatek)
Elementami zmienianymi mogą być:
Przykłady:
with(vlay.nazwawarstwy){
    vkf({left:100,top:200,vopacity:100},1)
    // ustawiamy początkową pozycję i przeźroczystość warstwy
    vkf({left:300},10)
    // w 10 klatkach przesuwamy ją o 200 pikseli w prawo
    vkf({top:400},10)
    // 200 pikseli w dół
    vkf({left:100},10)
    // spowrotem 200 pikseli w lewo
    vkf({top:200},10)
    // spowrotem 200 pikseli w górę
    vkf({vopacity:0},10)
    // wykonujemy łagodne zniknięcie poprzez wykorzystanie stopniowego zmniejszania parametru opacity od 100 do 0 w przeciągu 10 klatek
}
Jak to zilustrowano w powyższym przykładzie, definiować musimy jedynie te parametry, które między danymi klatkami kluczowymi ulegają zmianie.

W szczególnym przypadku nie podanie żadnych elementów zmienianych spowoduje brak aktywności warstwy przez zadana liczbę klatek:
vlay.nazwawarstwy.vkf({},25)
7.2. Obiekt van.
Jest to obiekt opisujący sposób ewentualnej animacji warstwy. Posiada go każda warstwa w obiekcie vlay (vlay.nazwawarstwy.van). Posiada on następujące właściwości i metody:

7.2.1. Właściwość group.
Określa przynależność warstwy do grupy animacyjnej. W Alladynie warstwy można grupować i osobno zarządzać ruchem poszczególnych grup.
Domyślna grupa, do której należą wszystkie warstwy bez określonej grupy animacyjnej, to "".

7.2.2. Właściwość go.
Właściwość ta określa, czy dana warstwa ma być animowana podczas animacji grupy, do której należy. Przyjmować może wartości true lub false.

7.2.3. Właściwość mode.
Właściwość określa sposób zachowania się animacji warstwy, tryb ruchu. Przyjmować może następujące wartości:
7.2.4. Właściwość UDF (User Defined Function).
Określa funkcję, jaka ma zostać wykonana po zakończeniu animacji danej warstwy. Może to być polecenie języka JavaScript, wywołanie jednej lub kilku funkcji.

7.2.5. Metoda reset().
Powoduje natychmiastowe przerwanie animacji warstwy i wyczyszczenie tablicy animacji, funkcji użytkownika, itp. Aby wstrzymać animację warstwy bez czyszczenia innych parametrów obiektu van, należy zamiast metody reset() ustawić właściwość go na false.

7.2.6. Metoda purge().
Czyści ścieżkę animacji, pozostawiając w niej jedynie bieżącą klatkę. Zachowuje grupę animacyjną, funkcję użytkownika oraz aktualne właściwości warstwy. jej użycie pozwala na łatwą i płynną zmianę zdefiniowanej ścieżki animacji warstwy w trakcie trwania animacji, pod warunkiem jednak, że w aktualnie wykonywanym ruchu (do następnej zdefiniowanej klatki kluczowej) zdefiniowane są wszystkie zmieniane elementy ruchu (zarówno pozycja left jak i top oraz ewentualnie inne, które były zmieniane w trakcie trwania animacji).

7.3. Obiekt STPE.
Jest to obiekt zawierający zmienne globalne Alladyna oraz zawierający mechanizmy odpowiedzialne za kontrolowanie i synchronizację animacji poszczególnych warstw oraz grup animacyjnych.
Posiada następujące metody i właściwości:

7.3.1. Zmienna v.
Zmienna ta określa numer wersji biblioteki Alladyn. Jest w postaci liczby zmiennoprzecinowej.

7.3.2. Metoda go(grupa, interwał, autostop, funkcja użytkownika).
Funkcja uruchamia animację danej grupy animacyjnej, a więc wszystkich warstw, które do tej grupy należą.
Interwał to odstęp pomiędzy klatkami w milisekundach.
Autostop to parametr opcjonalny. Jeśli jego wartość wynosi true, wówczas po zakończeniu animacji wątek jest wygaszany i nie będzie reagował na aktywację jakichkolwiek warstw tej grupy. Domyślna wartość to false.
Funkcja użytkownika jest również parametrem opcjonalnym i ma sens tylko dla wartości true parametru autostop. Określa funkcję, jaka zostanie wykonana po zakończeniu i wygaszeniu wątku grupy animacyjnej.

7.3.3. Metoda stop(grupa).
Funkcja powoduje natychmiastowe zatrzymanie grupy animacyjnej i likwidację wątku. Nie zmienia stanu poszczególnych warstw wchodzących w skład grupy, co pozwala wznowić animację w dowolnie wybranym momencie.

7.3.4. Właściwość vol.
Jest to właściwość określająca globalny próg symulacji przeźroczystości dla NS4 (patrz metoda vopacity) - stosowany dla wszystkich warstw, które nie mają zdefiniowanego indywidualnego progu (vlay.nazwawarstwy.vol). Wartości opacity poniżej tej liczby spowodują ukrycie warstwy w NS4, zaś równe i większe - pokazanie jej z pełną nieprzeźroczystością. Domyślna wartośc to 50.

7.4. Funkcja Alladyn().
Cała biblioteka jest zawarta wyłącznie w tej funkcji. Uruchomiona po całkowitym załadowaniu dokumentu, tworzy nowy model obiektowy w hierarchii vlay, wszystkie obiekty, metody i właściwości Alladyna.
Zaleca się uruchamiać tą funkcję poprzez onLoad znacznika <body>, po uprzednim załadowaniu biblioteki Alladyn.js w sekcji <head>.

7.5. Zmienne globalne.
Alladyn wprowadza następujące zmienne globalne:

7.5.1. Zmienna doc.
Skrót od document. Pozwala m.in. na skrócenie zapisu (np. doc.write itp.).

7.5.2. Zmienne ns4, ie, ns6.
Zmiennie pozwalające na identyfikację przeglądarki w różnych specyficznych zastosowaniach, np. nie zunifikowanych w opisywanej bibliotece. ns6 jest zmienną boolowską, zaś ie oraz ns4 mają wartość bądź to null (równoważną false) bądź są od razu referencjami do tradycyjnych modeli warstw (odpowiednio document.all i document.layers) co odpowiada wartości logicznej true.
Można zatem stosować zapisy if(ie), if(ns4), ie?a:b itp., jak i odwoływać się do warstw odpowiednio przez ie.test, ie.["test"], ns4.test, ns4.["test"] itd.

7.5.3. Zmienna up5.
Zmienna określa czy browser zalicza się do IE5.x, NS6.x (lub wyższych numerów wersji), co może oznaczać, że realizuje DOM zalecany przez W3C oraz że działać w nim będą zgodnie z oczekiwaniami niektóre z nowych efektów DHTML.
Zmienna ta jest oczywiście także referencją do warstw albo posiada wartość logiczną false.

Najnowsze informacje o Alladyn Project, więcej przykładów oraz galeria znajdują się na Stronie Alladyn Project online.

[< Poprzedni rozdział] [Spis treści] [Strona Alladyn Project online >]