# Format skórki MPlayera

Celem tego dokumentu jest opisanie formatu skórki MPlayera. Informacje zawarte tutaj mogą być niedokładne, ponieważ:

1. To nie ja napisałem GUI.

2. GUI nie jest ukończone.

3. Mogę się mylić.

A więc nie bądź zaskoczony, jeśli coś nie będzie działać tak, jak przedstawiono to tutaj.

Podziękowania dla Zoltána Ponekkera za jego pomoc.

András Mohari <mayday@freemail.hu>

## Wstęp

W zasadzie nie ma to żadnego związku z formatem skórki, ale powinieneś wiedzieć, że MPlayer nie ma wbudowanej skórki, w związku z tym co najmniej jedna skórka musi być zainstalowana, abyś miał możliwość korzystania z GUI.

### Katalogi

Skórki są szukane w następujących katalogach (w kolejności):

1. `$(DATADIR)/skins/`

2. `$(PREFIX)/share/mplayer/skins/`

3. `~/.mplayer/skins/`

Zauważ, że pierwsza ścieżka może się różnić, w zależności od sposobu w jaki MPlayer został skonfigurowany (zobacz argumenty `--prefix` oraz `--datadir` w skrypcie `configure`).

Każda skórka jest instalowana w swoim własnym katalogu, w jednej z wyżej wymienionych lokacji, na przykład:

    $(PREFIX)/share/mplayer/skins/default/

### Formaty obrazków

Obrazki muszą być zapisane w formacie PNG (paleta truecolor - 24 lub 32 bpp).

W głównym oknie oraz na panelu odtwarzania (zobacz niżej) możesz użyć obrazków z 'przezroczystością': obszary wypełnione kolorem #FF00FF (magenta) są w pełni przezroczyste dla MPlayera. Oznacza to, że możesz mieć okna o różnych kształtach jeśli Twój X Server ma rozszerzenie XShape.

### Składniki skórki

Skórki są całkowicie konfigurowalne (w odróżnieniu od skórek np. Winampa/XMMS), a więc zależy to wyłącznie od Ciebie, czy stworzysz coś wspaniałego.

W chwili obecnej mamy cztery okna, które można ozdobić: okno główne (main window), okno ekranu (subwindow), panel odtwarzania (playbar), menu skórki (skin menu) (które może być aktywowane prawym przyciskiem myszy).

- Okno główne i/lub panel odtwarzania to miejsca, gdzie możesz sterować MPlayerem. Tłem tego okna jest obrazek. Różne elementy mogą (i muszą) być umieszczone w tym oknie: przyciski, potencjometry (suwaki) i etykiety. Dla każdego elementu musisz określić ich pozycję oraz rozmiar.

  Przycisk ma trzy stany (wciśnięty, zwolniony, nieaktywny), zatem jego obrazki muszą być podzielone na trzy części w pionie. Zobacz sekcję button, by dowiedzieć się więcej.

  Potencjometr (suwak) (wykorzystywany głównie jako pasek przewijania i kontrolka głośności/balansu) może składać się z każdej liczby stanów poprzez podzielenie jego obrazka na wiele części, z których jedna jest pod drugą. Zobacz hpotmeter oraz potmeter, by dowiedzieć się więcej.

  Etykiety są nieco specyficzne: Znaki potrzebne do ich narysowania są pobierane z pliku graficznego, a znaki umieszczone w pliku graficznym są opisane przez plik opisu czcionek. Jest to plik, który za pomocą czystego tekstu określa współrzędne x, y oraz wielkość każdego znaku umieszczonego na obrazku (plik graficzny i jego plik opisu tworzą razem czcionkę). Zobacz dlabel oraz slabel, by dowiedzieć się więcej.

  Wszystkie obrazki mogą być całkowicie przezroczyste - tak, jak to opisano w sekcji formaty plików graficznych. Jeżeli X Server nie obsługuje rozszerzenia XShape, to elementy oznaczone jako przezroczyste będą czarne. Jeśli chciałbyś wykorzystać taką możliwość, szerokość obrazka tła głównego okna musi być podzielna przez 8.

- Okno ekranu to miejsce, gdzie odtwarzany jest film. Może ono wyświetlać określony obrazek, jeśli żaden film nie jest uruchomiony (to dość nudne mieć puste okno :-)) Uwaga: przezroczystość nie jest tutaj dostępna.

- Menu skórki to po prostu jeden ze sposobów na kontrolowanie MPlayera poprzez wpisy w menu. Dwa obrazki są do tego potrzebne: pierwszy z nich jest obrazkiem podstawowym, który pokazuje zwykły stan menu, drugi zaś służy do wyświetlenia zaznaczonych obszarów. Gdy uaktywnisz menu, zostanie pokazany pierwszy obrazek. Jeśli przesuniesz mysz nad któryś z jego wpisów, wówczas zaznaczony element jest kopiowany z drugiego obrazka w miejsce, na które wskazuje kursor myszy (drugi obrazek nigdy nie jest wyświetlany w całości).

  Wpis w menu jest określony przez jego pozycję oraz rozmiar na obrazku (zobacz sekcję menu skórki by dowiedzieć się więcej).

Jedna ważna sprawa, która nie została jeszcze powiedziana: MPlayer musi wiedzieć co zrobić w momencie kliknięcia na przyciski, potencjometry i wpisy w menu, aby zadziałały. Zostało to zrobione za pomocą sygnałów (zdarzeń). Dla tych elementów musisz zdefiniować sygnały, które mają być wysłane podczas kliknięcia na nie.

### Pliki

Potrzebujesz następujących plików do stworzenia skórki:

- Plik konfiguracyjny o nazwie skin mówi MPlayerowi jak połączyć różne części skórki w jedną całość i co zrobić, gdy kliknie się gdzieś na obszarze okna.

- Plik graficzny tła w oknie głównym.

- Obrazki dla elementów w głównym oknie (zawierające jeden lub więcej plików opisu czcionek potrzebnych do rysowania etykiet).

- Obrazek wyświetlany w oknie ekranu (opcjonalnie)

- Dwa obrazki dla menu skórki (potrzebne są tylko wtedy, gdy chcesz stworzyć takie menu).

Za wyjątkiem pliku konfiguracyjnego skórki, możesz nazwać wszystkie pliki tak, jak tego chcesz (ale weź pod uwagę, że pliki opisu czcionek muszą mieć rozszerzenie `.fnt` ).

## Plik skin

Jak zostało powiedziane wcześniej, plik ten jest plikiem konfigurującym skórkę. Obsługuje różne rodzaje wierszy; komentarze zaczynają wiersz znakiem '`;`' (tylko spacje i znaki tabulacji są dopuszczone przed '`;`').

Plik podzielony jest na sekcje. Każda sekcja opisuje skórkę dla każdej aplikacji i ma następującą formę:

    section = nazwa sekcji
    .
    .
    .
    end

Obecnie jest tylko jedna aplikacja, a więc potrzebujesz tylko jedną sekcję 'section' - jej nazwa to movieplayer.

Wewnątrz tej sekcji każde z okien jest opisane przez blok następującej postaci:

    window = nazwa okna
    .
    .
    .
    end

gdzie nazwa okna może być jednym z poniższych łańcuchów:

- main - dla okna głównego

- sub - dla okna ekranu

- menu - dla menu skórki

- playbar - dla panelu odtwarzania

(Bloki sub i menu są opcjonalne - nie musisz tworzyć menu czy elementów skórki dla okna ekranu)

Wewnątrz bloku 'window' możesz definiować każdy element okna, wpisując linijkę tej postaci:

    item = parametr

Gdzie `item` jest łańcuchem, kóry identyfikuje typ elementu GUI, `parametr` jest wartością numeryczną lub tekstową (lub listą takich wartości oddzielonych od siebie znakiem przecinka).

Złożenie powyższych elementów razem tworzy plik, który wygląda mniej więcej tak:

    section = movieplayer
      window = main
      ; ... elementy okna głównego ...
      end

      window = sub
      ; ... elementy okna ekranu ...
      end

      window = menu
      ; ... elementy menu skórki ...
      end

      window = playbar
      ; ... elementy panelu odtwarzania ...
      end
    end

Nazwa pliku graficznego musi zostać podana bez żadnych nazw katalogów - obrazki są szukane w katalogu `skins`. Możesz (ale nie musisz) określić rozszerzenia tego pliku. Jeśli plik taki nie istnieje, MPlayer spróbuje wczytać plik `<nazwa pliku>.<rozszerzenie>`, gdzie `png` oraz `PNG` są brane jako `<rozszerzenie>` (w tej właśnie kolejności). Pierwszy pasujący plik będzie użyty.

Na koniec kilka słów na temat pozycjonowania. Okno główne oraz okno ekranu możesz umieścić w różnych narożnikach ekranu poprzez ustawienie współrzędnych `X` i `Y`. `0` to góra lub lewa strona, `-1` to środek, `-2` to strona prawa, lub dół, tak jak przedstawiono na poniższej ilustracji:

    (0, 0)----(-1, 0)----(-2, 0)
      |          |          |
      |          |          |
    (0,-1)----(-1,-1)----(-2,-1)
      |          |          |
      |          |          |
    (0,-2)----(-1,-2)----(-2,-2)

Oto przykład wyjaśniający to lepiej. Przypuśćmy, że masz obrazek nazwany `main.png`, który został użyty dla okna głównego:

    base = main, -1, -1

MPlayer spróbuje wczytać pliki `main`, `main.png`, `main.PNG`.

### Okno główne i panel odtwarzania

Poniżej znajduje się lista wpisów, które mogą być użyte w blokach '`window = main`'...'`end`' oraz '`window = playbar`' ... '`end`'.

`base = obrazek, X, Y`

  Możesz określić obrazek tła, który będzie używany w oknie głównym. Okno będzie widoczne na ekranie na współrzędnych `X, Y`. Okno będzie wielkości tego obrazka.

  Współrzędne te nie działają na razie dla okna ekranu.

  Obszary przezroczystości obrazka (kolor #FF00FF) będą widoczne jako czarne pod X serwerami niemającymi rozszerzenia XShape. Szerokość obrazka musi być podzielna przez 8.

`button = obrazek, X, Y, szerokość, wysokość, sygnał`

  Umieści przycisk o rozmiarze `szerokość` * `wysokość` na pozycji `X`, `Y`. Określony `sygnał` jest generowany podczas kliknięcia na przycisk. Obrazek ten opisany przez `obrazek` musi składać się z trzech części jedna pod drugą (stosownie do możliwych stanów przycisku), w ten oto sposób:

      +---------------+
      |  wciśnięty    |
      +---------------+
      |  zwolniony    |
      +---------------+
      | nieaktywny    |
      +---------------+

`decoration = enable|disable (włączona|wyłączona)`

  Włącza lub wyłącza dekorację menedżera okna w oknie głównym. Domyślnie jest wyłączona.

  Nie działa to w oknie ekranu, gdyż nie ma takiej potrzeby.

`hpotmeter = przycisk, szer_przycisku, wys_przycisku, faza, liczba_faz, domyślny, X, Y, szerokość, wysokość, sygnał`

`vpotmeter = przycisk, szer_przycisku, wys_przycisku, fazy, liczba_faz, domyślny, X, Y, szerokość, wysokość, sygnał`

  Umieszcza poziomo (hpotmeter) lub pionowo (vpotmeter) suwak o rozmiarze `szerokość` * `wysokość` i pozycji `X,Y`. Obrazek może być podzielony na różne części dla różnych faz suwaka (np. możesz mieć suwak głośności, który w zależności od położenia zmienia kolor z zielonego (minimum) na czerwony (maksimum)). `hpotmeter` może być przyciskiem umieszczonym poziomo. Jego parametry to:

  - `przycisk` - obrazek użyty do przycisku (musi posiadać trzy części jedna pod drugą tak, jak w przypadku przycisku)

  - `szer_przycisku`,`wys_przycisku` - wielkość przycisku

  - `fazy` - obrazek używany do określenie faz dla hpotmeter. Wartość specjalna `NULL` może być użyta, jeśli nie chcesz żadnego obrazka. Obrazek musi być podzielony w pionie na fragmenty `poszczególnych faz` tak, jak poniżej:

        +------------+
        |  faza #1   |
        +------------+
        |  faza #2   |
        +------------+
             ...
        +------------+
        |  faza #n   |
        +------------+

  - `liczba_faz` - liczba faz znajdująca się na obrazku z `fazami`

  - `domyślny` - domyślne ustawienie dla hpotmeter (zakres od `0` do `100`)

  - `X`,`Y` - pozycja dla hpotmeter

  - `szerokość`,`wysokość` - szerokość i wysokość dla `hpotmeter`

  - `sygnał` - sygnał generowany podczas zmiany wartości `hpotmeter`

`potmeter = fazy, liczba_faz, domyślny, X, Y, szerokość, wysokość, sygnał`

  `hpotmeter` bez przycisku. (domyślam się, że chodzi o to, aby nim kręcić, ale reaguje on tylko na poziome przesuwanie). Opis parametrów znajdziesz w części o hpotmeter. Parametr `fazy` może mieć wartość `NULL`, ale jest to zupełnie bezużyteczne, gdyż nie widać wtedy położenia potencjometru.

`font = plik_czcionek, id_czcionki`

  Definiuje czcionkę. `plik_czcionek` jest nazwą pliku opisu czcionki z rozszerzeniem `.fnt` (nie podawaj rozszerzenia w tym miejscu). `id_czcionki` jest używany do wskazywania konkretnej czcionki (zobacz dlabel oraz slabel). Można zdefiniować do 25 czcionek.

`slabel = X, Y, id_czcionki, "tekst"`

  Umieszcza statyczną etykietę w pozycji `X,Y`. `tekst` jest wyświetlany za pomocą czcionki wskazywanych przez `id_czcionki`. Tekst jest po prostu zwykłym łańcuchem znaków (zmienne `$x` nie działają), któru musi być umieszczony pomiędzy podwójnym cudzysłowem (znak " nie może być częścią tekstu). Etykieta wyświetlana jest za pomocą czcionki, na którą wskazuje `id_czcionki`.

`dlabel = X, Y, długość, wyrównanie, id_czcionki, "tekst"`

  Umieszcza dynamiczną etykietę w pozycji `X,Y`. Etykieta jest nazywana dynamiczną, ponieważ jej tekst jest cyklicznie odświeżany. Maksymalną długość etykiety określa parametr `długość` (jej wysokość określa wysokość czcionki). Jeśli tekst jest szerszy niż zdefiniowana długość, będzie on przewijany, w przeciwnym wypadku będzie wyrównany w miejscu określonym przez wartość parametru `wyrównanie`: `0` oznacza do prawej, `1` to wyśrodkowanie, `2` to wyrównanie do lewej.

  Wyświetlany tekst jest określony przez zmienną `tekst`: musi być zawarty pomiędzy podwójnymi cudzysłowami (znak " nie może być częścią tekstu). Etykieta wyświetlana jest za pomocą czcionki, na którą wskazuje parametr `id_czcionki`. Możesz użyć następujących zmiennych w tekście:

  Zmienna | Znaczenie
  --- | ---
  $1 | czas odtwarzania w formacie hh:mm:ss
  $2 | czas odtwarzania w formacie mmmm:ss
  $3 | czas odtwarzania w formacie (godziny) hh
  $4 | czas odtwarzania w formacie (minuty) mm
  $5 | czas odtwarzania w formacie (sekundy) ss
  $6 | długość filmu w formacie hh:mm:ss
  $7 | długość filmu w formacie mmmm:ss
  $8 | długość filmu w formacieh:mm:ss
  $v | format głośności w %xxx.xx
  $V | format głośności xxx.xx format
  $b | format balansu w %xxx.xx
  $B | format balansu xxx.xx
  $$ | znak $
  $a | oznaczenie zgodne z rodzajem typu pliku audio (nic: `n`, mono: `m`, stereo: `t`)
  $t | numer ścieżki (na liście odtwarzania)
  $o | nazwa pliku
  $f | nazwa pliku pisana małymi literami
  $F | nazwa pliku pisana wielkimi literami
  $T | oznaczenie zgodne z rodzajem strumienia (plik: `f`, Video CD: `v`, DVD: `d`, URL: `u`)
  $p | znak p (gdy film jest odtwarzany i czcionka ma znak p)
  $s | znak s (gdy film jest zatrzymany i czcionka ma znak s)
  $e | znak e (gdy film jest wstrzymany (pauza) i czcionka ma znak e)
  $x | rozdzielczość filmu (szerokość)
  $y | rozdzielczość filmu (wysokość)
  $C | nazwa używanego kodeka

Zmienne `$a, $T, $p, $s` oraz `$e` zwracają znaki, które powinny być wyświetlane jako znaki specjalne (na przykład e jest symbolem pauzy, która z reguły wygląda mniej więcej tak ||). Powinieneś mieć czcionkę dla zwykłych znaków oraz osobną czcionkę dla symboli. Zobacz sekcję na temat symboli, by dowiedzieć się więcej.

### Okno ekranu

Poniższe wpisy mogą być użyte w bloku '`window = sub`' . . . '`end`' .

`base = obrazek, X, Y, szerokość, wysokość`

  Wyświetla obrazek w oknie. Okno będzie widoczne na ekranie w miejscu oznaczonym przez współrzędne `X`, `Y` (`0,0` to lewy górny narożnik). Możesz użyć `-1` dla środka, `-2` dla prawej strony (`X`) i dołu (`Y`). Okno będzie mieć wielkość obrazka. `szerokość` oraz `wysokość` oznaczają wielkość okna; są one opcjonalne (jeśli nie są określone, okno będzie wielkości takiej, jak obrazek).

`background = R, G, B`

  Pozwala ustawić kolor tła. Jest to użyteczne jeśli obrazek jest mniejszy niż okno. `R`, `G` oraz `B` określają składniki kolorów czerwonego, zielonego i niebieskiego (każdy z nich jest reprezentowany przez liczbę dziesiętną w zakresie od 0 do 255).

### Menu skórki

Jak wspomniano wcześniej, menu jest wyświetlane przy użyciu dwóch obrazków. Zwykłe obszary menu są pobierane z obrazka określonego przez element `base`, podczas gdy obszary zaznaczone są pobierane z obrazka wskazywanego przez element `selected`. Musisz zdefiniować pozycję i rozmiar każdego obszaru menu poprzez element menu.

Poniższe wpisy mogą być użyte w bloku: '`window = menu`'. . .'`end`' .

`base = obrazek`

  Obrazek dla zwykłych obszarów menu.

`selected = obrazek`

  Obrazek pokazujący w menu wszystkie zaznaczone obszary.

`menu = X, Y, szerokość, wysokość, sygnał`

  Definiuje pozycję i rozmiar obszarów menu na obrazku przy pomocy `X,Y`. `sygnał` to zdarzenie wygenerowane podczas zwolnienia przycisku myszy nad obszarem.

## Czcionki

Jak wspomniano w sekcji na temat fragmentów skórki, czcionka jest definiowana przez obrazek i plik opisujący. Możesz umieścić znaki gdziekolwiek na obrazku, ale miej pewność, żeich pozycja i rozmiar jest dokładnie podana w pliku opisującym.

Plik opisujący czcionkę (o rozszerzeniu `.fnt`) może posiadać linie komentarzy zaczynające się znakiem '`;`'. Plik musi zawierać linie w postaci:

    image = obrazek

Gdzie `obrazek` jest nazwą pliku graficznego, który zawiera czcionkę (nie musisz dopisywać jego rozszerzenia).

    "char" = X, Y, szerokość, wysokość

`X` oraz `Y` określają pozycję znaku `char` na obrazku (`0,0` to górny lewy narożnik). `szerokość` i `wysokość` to rozmiar znaku w pikselach.

Przykład: definiujemy znaki A, B, C przy użyciu pliku `font.png`.

    ; Może być "font" zamiast "font.png".
    image = font.png

    ; Trzy znaki wystarczą do tej demonstracji :-)
    "A" =  0,0, 7,13
    "B" =  7,0, 7,13
    "C" = 14,0, 7,13

### Znaki specjalne (symbole)

Niektóre znaki mają specjalne znaczenie, gdy są zwracane przez pewne zmienne używane w dlabel. Znaki te mogą być wyświetlane jako symbole w ten sposób, że np. podczas odtwarzania strumienia DVD widoczne jest ładne logo zamiast znaku '`d`'.

Poniższa tablica zawiera znaki używane do wyświetlania symboli (wymagają one oddzielnych czcionek).

Znak | Symbol
--- | ---
p | odtwarzanie
s | stop
e | pauza
n | bez dźwięku
m | dźwięk mono
t | dźwięk stereo
f | strumień z pliku
v | strumień z Video CD
d | strumień z DVD
u | strumień z URL

## Sygnały GUI

Tutaj znajdują się sygnały, które mogą być generowane przez przyciski, suwaki i elementy menu.

Niektóre sygnały mogą nie działać w oczekiwany sposób (lub nie działać w ogóle). Jak wiadomo, GUI jest jeszcze w fazie rozwoju.

Kontrola odtwarzania :

evNext

  Przejdź do następnej pozycji na liście odtwarzania.

evPause

  Tworzy przełącznik razem z `evPlaySwitchToPause`. Mogą być użyte do utworzenia wspólnego przycisku odtwarzania/pauzy. Oba sygnały powinny być powiązane z przyciskami wyświetlonymi na tej samej pozycji w oknie. Sygnał ten wstrzymuje odtwarzanie i wyświetla obrazek dla przycisku `evPlaySwitchToPause` (aby zaznaczyć, że przycisk ten może być użyty do kontynuowania odtwarzania).

evPlay

  Rozpocznij odtwarzanie.

evPlaySwitchToPause

  Przeciwieństwo `evPauseSwitchToPlay`. Ten sygnał zaczyna odtwarzanie oraz wyświetla obrazek dla przycisku `evPauseSwitchToPlay` (aby zaznaczyć, że przycisk ten może być użyty ponownie do wstrzymania odtwarzania).

evPrev

  Przejdź do poprzedniej pozycji na liście odtwarzania.

evStop

  Zatrzymaj odtwarzanie.

Przewijanie:

evBackward10sec

  Przewiń do tyłu o 10 sekund.

evBackward1min

  Przewiń do tyłu o 1 minutę.

evBackward10min

  Przewiń do tyłu o 10 minut.

evForward10sec

  Przewiń do przodu o 10 sekund.

evForward1min

  Przewiń do przodu o 1 minutę.

evForward10min

  Przewiń do przodu o 10 minut..

evSetMoviePosition

  Przewiń do pozycji (może być wykorzystane przez suwak; użyte są względne wartości (0-100%) suwaka).

Kontrola video:

evHalfSize

  Ustawia okno filmu na połowę rozmiaru.

evDoubleSize

  Ustaw podwójny rozmiar okna z filmem.

evFullScreen

  Włącz/wyłącz tryb pełnoekranowy.

evNormalSize

  Ustaw typowy rozmiar okna z filmem.

Kontrola dźwięku:

evDecAudioBufDelay

  Zmniejsz opóźnienie bufora dźwięku.

evDecBalance

  Zmniejsz balans.

evDecVolume

  Zmniejsz głośność

evIncAudioBufDelay

  Zwiększ opóźnienie bufora dźwięku.

evIncBalance

  Zwiększ balans.

evIncVolume

  Zwiększ głośność.

evMute

  Wycisz/przywróć dźwięk.

evSetBalance

  Ustawi balans (może być używane przez suwak; używana jest wartość względna (0-100%)).

evSetVolume

  Ustaw głośność (może być używane przez suwak; używana jest wartość względna (0-100%)).

Różne:

evAbout

  Otwórz okno "o programie".

evDropSubtitle

  Wyłącz aktualnie używane napisy.

evEqualizer

  Włącz/wyłącz korektor.

evExit

  Wyłącz program.

evIconify

  Minimalizuj okno.

evLoad

  Wczytaj plik (poprzez otwarcie okna przeglądarki plików, gdzie możesz wybrać plik).

evLoadPlay

  Tto samo co `evLoad`, ale zacznij automatycznie odtwarzać zaraz po wyborze pliku.

evLoadSubtitle

  Wczytaj plik z napisami (z przeglądarki plików).

evLoadAudioFile

  Wczytaj plik dźwiękowy (z przeglądarki plików).

evNone

  Sygnał pusty - nic nie robi (może za wyjątkiem wersji z CVS:-)).

evPlaylist

  Otwórz/zamknij okno listy odtwarzania.

evPlayDVD

  Spróbuj odczytać płytę ze wskazanego czytnika DVD.

evPlayVCD

  Spróbuj odczytać płytę ze wskazanego czytnika CD.

evPreferences

  Otwórz okno z ustawieniami.

evSetAspect

  Ustaw proporcje obrazu.

evSetURL

  Wyświetl okienko dialogowe URL.

evSkinBrowser

  Otwórz okno przeglądarki skórek.