# Tworzenie motywów dla menadżera logowania &kdm;

Rozdział opisuje tworzenie motywów dla menadżera logowania. Aby zobaczyć przykładowe motywy menedżera logowania wraz ze zrzutami ekranów, należy oglądnąć zainstalowane w systemie motywy i motywy zamieszczone na stronie motywów.

## Informacje podstawowe o motywach

Motywy &kdm; mogą być tworzone poprzez utworzenie pliku XML zgodnego ze specyfikacją zawartą w `$`KDEDIR`/share/apps/doc/kdm/greeter.dtd`. Pliki motywu przechowywane są w katalogu `$`KDEDIR`/share/apps/kdm/themes/`nazwa_motywu``. Katalog motywu powinien zawierać plik o nazwie `KdmGreeterTheme.desktop` który ma podobny format jak inne pliki `.desktop` i wygląda tak:

    [KdmGreeterTheme]
    Greeter=circles.xml
    Name=Okręgi
    Description=Motyw z niebieskimi okręgami
    Author=Bond, James Bond
    Copyright=(c) 2002 Bond, James Bond
    Screenshot=screenshot.png

Dane parametrów `Name`, `Description`, `Author` i `Copyright` mogą zostać przetłumaczone jak w innych plikach `.desktop` . Wszystkie wspomniane pliki powinny znaleźć się w katalogu motywu. Parametr `Screenshot` wskazuje na plik, który powinien być zrzutem wyglądu działającego motywu o rozmiarze 200x150 (może go nie być, ale jest ładnym dodatkiem dla użytkownika). Parametr `Greeter` wskazuje na plik XML który zawiera opis motywu.

W pełni przetestowany motyw należy umieścić w pliku tar zawierającym katalog, który może być zainstalowany do katalogu `$`KDEDIR`/share/apps/kdm/themes`. Jest to standardowa metoda rozprowadzania motywów &kdm;.

## Szczegółowy opis struktury pliku XML motywu

### Znacznik najwyższego rzędu

Pliki XML motywów &kdm; zaczynają się znacznikiem <greeter>. Znacznik najwyższego rzędu jest znacznikiem elementu typu`rect` z wymuszonym stałym układem.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE greeter SYSTEM "greeter.dtd">
    <greeter>
    [...]
    </greeter>

Pomiędzy znacznikami 'greeter' mogą znajdować się elementy opisane w dalszej części tego dokumentu. Niektóre z tych elementów są kontenerami (znacznikamiukładu, znacznikami elementów itp.), które mogą zawierać inne elementy.

### Znaczniki elementów

Motyw &kdm; jest określany za pomocą hierarchii znaczników elementów i znaczników układu. Atrybut `type` w znacznikach elementów może przyjmować następujące wartości:

button

- Pole przycisku. Element jest przyciskiem Qt.

  Możliwe jest też, aby inne elementy działały jak przycisk poprzez przypisanie atrybutowi `button` wartości `true`. Jednakże, lepiej jest używać standardowych przycisków Qt w motywach &kdm; gdyż są one dostępne dla niepełnosprawnych użytkowników.

entry

- Element służący wprowadzaniu danych taki jak np. linia edycyjna lub lista wyboru. Uwaga: jest to tylko znacznik miejsca dla innych elementów Qt.

label

- Etykieta tekstowa. Musi zawierać znaczniki `text` lub `stock` zawierające tekst do wyświetlenia.

list

- Element zawierający przeglądarkę twarzy.

pixmap

- Obrazek w formacie obsługiwanych przez Qt, ⪚ PNG, JPEG, Tiff, itp.

rect

- Prostokąt.

svg

- Grafika wektorowa w formacie SVG.

Na przykład:

    <item type="label">

Element funkcjonujący jak przycisk:

    <item type="rect" id="disconnect_button" button="true">.

W typowej sytuacji, ekran logowania &kdm; znika po uwierzytelnieniu. Może to spowodować migotanie pomiędzy ekranem logowania i ekranem sesji. Atrybut `background` pozwala określić jakie elementy motywu stanowią jego tło. Gdy zostanie użyty, spowoduje że &kdm; usunie wszystkie elementy nie będące tłem z ekranu, pozostawiając elementy z atrybutem `background` widoczne. Może to być użyte to uzyskania płynnego przejścia między ekranem logowania i ekranem sesji:

    <item type="rect" background="true">
      <normal file="background.svg"/>
      <pos x="0" y="0" width="100%" height="-75"/>
    </item>

Aby użyć innego tła dla efektu przejścia logowania a innego dla pytania o login, motyw powinien definiować dwa znaczniki elementu (które mogą zawierać obrazek typu mapy bitowej lub svg). Element, który ma być tłem ekranu powitalnego nie powinien mieć ustawionego atrybutu `background`, natomiast element, który ma być tłem dla efektu przejścia powinien mieć atrybut `background`. Przykładowo:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE greeter SYSTEM "greeter.dtd">
    <greeter>
      <item type="rect" background="true">
        <normal file="background_for_login.svg" element="background"/>
        <pos x="0" y="0" width="100%" height="100%"/>
      </item>
      <item type="rect">
        <normal file="background_for_greeter.svg"/>
        <pos x="0" y="0" width="100%" height="100%"/>
      </item>
      [...]
    </greeter>

W systemach wyposażonych w wiele monitorów, motywy mogą definiować wygląd ekranu na innych monitorach - jednakże w typowym rozwiązaniu na pozostałych monitorach pojawiają się jedynie elementy tła. Aby określić na którym ekranie (ekranach) ma pojawiać się elementy, należy skorzystać z atrybutu `screen`. Jako wartość atrybutu należy podać jedną z następujących wartości`greeter`, `other` lub `all`, oznaczającą odpowiednio umiejscowienie elementu na: ekranie logowania, na pozostałych ekranach lub na wszystkich ekranach.

Każdemu elementowi można nadać nazwę za pomocą atrybutu:`id`. Niektóre nazwy są rozpoznawane przez &kdm; i nadają elementom specjalne funkcje:

Elementy typu `button` oraz elementy zawierające atrybut `button="true"`.

- Przyciski zwykle służą do wywołania określonego działania. Dodatkowo &kdm; nie pokazuje przycisków, dla których działanie jest z jakichś powodów niedostępne.

  Id Akcja
  - chooser_button Uruchamia okno wyboru protokołu XDMCP.
  - disconnect_button Odłącza zdalną sesję.
  - session_button Otwiera menu wyboru rodzaju sesji.
  - system_button Otwiera systemowe menu zawierające różne opcje i działania, w zależności od konfiguracji.

Elementy typu `label`

- Program &kdm; pokazuje lub ukrywa etykiety oraz określa ich treść w zależności od stanu okna dialogowego logowania.

  Id Funkcja
  - pam-error Wyświetla wiadomość Logowanie się nie powiodło..

Elementy do osadzania elementów interfejsu

- Program &kdm; osadza niektóre elementy interfejsu Qt w tych elementach.

  Id Funkcja
  - user-entry Pole do wprowadzania nazwy użytkownika.
  - pw-entry Pole do wprowadzania hasła.
  - domain-entry Niektóre wtyczki dialogu uwierzytelniania wykorzystują to pola do wprowadzenia nazwy domeny. Jeżeli ten znacznik jest określony, to zależne od niego elementy powinny zawierać atrybuty:show nodes z określonym typem `plugin-domain-entry`.
  - talker Ten element powinien być typu `rect`. Określa on aktywną ( hot) powierzchnię ekranu logowania: zawiera etykietę `label` oraz elementy wprowadzania danych `entry` dotyczące procesu uwierzytelniania. Jeżeli wybrana wtyczka dialogu (conversation) nie dopasować podanych elementów do swoich potrzeb, to stara się osadzić złożony element interfejsu z własnych układem w tych elementach, co anuluje działanie zdefiniowanego w motywie elementu talker. Oznacza to, że motywy &kdm; nie muszą definiować własnego projektu elementu talker, jako że wszystkie wtyczki uwierzytelniania &kdm; mogą wykorzystać ten element.
  - userlist Ten element musi być typu `list`. Jeżeli w ustawieniach włączone jest wyświetlanie listy użytkowników, program &kdm; osadzi w nim element interfejsu - listę użytkowników. W przeciwnym wypadku ten element jest niewidoczny.
  - xconsole Ten element powinien być typu `rect`. Jeżeli funkcjonalność wbudowanej konsoli`xconsole` jest skompilowana i włączona, &kdm; osadzi tutaj element interfejsu - konsolę. W przeciwnym wypadku ten element jest niewidoczny.

Inne elementy

- Program &kdm; będzie pokazywał/ukrywał te elementy w zależności od konfiguracji systemu i bieżącego stanu ekranu logowania. &kdm; nie wymusza wymagań odnośnie rodzaju na tych elementach, ale zwykle są one dopasowane to określonego typu.

  Id Widoczny tylko jeżeli ...
  - timed-label ... opóźnione logowanie jest w trakcie.
  - caps-lock-warning ... aktywny jest klawisz Caps Lock.
  - xauth-warning ... serwer &X-Server; nie wymaga autoryzacji do połączenia.
  - userlist-rect ... lista użytkowników jest włączona. Poprzez zagnieżdżenie w tym elemencie elementu `userlist`, możliwe jest utworzenie czegoś w rodzaju ramki otaczającej listę użytkowników i pokazującej się tylko wtedy gdy lista użytkowników jest widoczna.
  - xconsole-rect ... wbudowana konsola `xconsole` jest włączona. Stosowanie analogiczne jak `userlist-rect`.

### Kontenery układu

Znaczniki układu pojawiają się wewnątrz znaczników elementów i zawierają ponownie znaczniki elementów. Rodzaj znacznika układu określa umiejscowienie znaczników podrzędnych. Znacznik elementu może zawierać po jednym znaczniku układu z każdego rodzaju.

#### Znaczniki prostokątów

Prostokąty automatycznie rozmieszczają podrzędne elementy w rzędzie. Są one definiowane następująco:

    <box orientation="alignment" min-width="num" min-height="num"
        xpadding="num" ypadding="num" spacing="num"
        homogeneous="bool">

Gdzie `num` określa liczbę pikseli `bool` oznacza albo `true` albo `false`. Wartością `alignment` może być albo `horizontal` albo`vertical`. Jeżeli jakiś atrybut nie będzie wprowadzony, to zostaną przyjęte wartości domyślne: zero dla liczb, `false` dla wartości logicznych i `vertical` dla orientacji.

Atrybut 'spacing' określa obszar pomiędzy sąsiadującymi elementami podrzędnymi, 'padding' definiuje zewnętrzny margines prostokąta. Jeżeli prostokąt jest homogeniczny ('homogenous') to dla każdego elementu podrzędnego udostępniana jest jednakowa powierzchnia ekranu.

#### Znaczniki układu ustalonego

Znaczniki 'fixed' są kontenerami, w których wszystkie elementy podrzędne są umieszczone w określonych współrzędnych. Rozmiar kontenera to najmniejszy prostokąt mieszczący wszystkie elementy podrzędne. W znaczniku 'fixed' niepotrzebne są żadne dodatkowe atrybuty, więc wystarczy wpisać jedynie:

    <fixed>

, a następnie umieścić pozostałe elementy z określoną pozycją wewnątrz niego.

### Znaczniki pozycji

Dla każdego elementu można określać położenie i rozmiar za pomocą znacznika `pos`. Na przykład:

    <pos x="0" y="4" width="100%" height="100%"/>

Jeżeli rozmiar nie jest określony, to przyjęty zostanie domyślny rozmiar elementu, tzw. 'hint' rozmiaru. Uwaga ! nie wszystkie elementy posiadają użyteczną wartość 'hint'.

Zarówno pozycja jak i rozmiar elementu może być podany procentowo, co powoduje iż będzie obliczany relatywnie do rozmiaru kontenera, w którym się znajduje. Dla elementów najwyższego rzędu będzie to procent całego ekranu. Dodając znak `^` do określenia rozmiaru, możliwe jest określenie rozmiaru względem kontenera zawierającego kontener w którym jest dany element itd.

Jeżeli element zawiera prostokąt, parametry `width` i `height` mogą być określone jako `box` co oznacza, że oznaczają szerokość i wysokość prostokąta, tzn. szerokość i wysokość elementów w prostokącie razem z marginesem.

Jeden z parametrów `width` lub `height` może posiadać atrybut `scale` co oznacza, że ma być skalowany relatywnie do drugiego atrybutu biorąc pod uwagę domyślny 'hint' rozmiaru. Może to być wykorzystane do automatycznego zachowywania proporcji skalowanych obrazów.

Jeżeli wprowadzony jest atrybut `expand` z wartością `true`, element będzie rozszerzony w otaczającym go prostokącie do maksymalnych możliwych rozmiarów (czyli oczyma więcej miejsca, jeżeli jest to możliwe).

Jeżeli parametry `width` lub `height` są wpisane liczbowo, wartość ujemna określa offset względem rozmiaru kontenera. Uwaga, możliwe jest określenie dodatniego offsetu poprzez zapisanie dwóch znaków minus.

W każdym przypadku możliwe jest ograniczenie ostatecznych rozmiarów elementu za pomocą atrybutów: `min-width`, `min-height`, `max-width` i `max-height`, które mogą być zapisane w analogiczny sposób jak atrybuty `width` oraz `height`.

Jeżeli atrybuty `x` lub `y` są liczbami, wartość ujemna określa offset - przesunięcie - względem prawej - dolnej krawędzi, a nie lewej - górnej krawędzi.

Możliwe jest także określenie punktu wewnątrz elementu, którego dotyczą atrybuty pozycji. Jest on nazywany kotwicą (anchor) i może być albo w środku elementu, lub może być określony za pomocą wartości: `n`, `ne`, `e`, `se`, `s`, `sw`, `w` oraz `nw`, które oznaczają różne krawędzie/rogi odpowiadające współrzędnym topograficznym. Wartością domyślną jest `nw`, oznaczającą górny-lewy narożnik. Na przykład:

    <pos x="10%" y="50%" anchor="w" width="80%" height="95"/>

### Znaczniki wyświetlania

Można zdefiniować atrybut `type` dla wskazania pewnych elementów, które powinny być wyświetlane tylko jeżeli dany rodzaj funkcji jest włączony w konfiguracji.Poprzedzenie rodzaju znakiem wykrzyknika (`!`) odwraca znaczenie warunku. Dostępne wartości są następujące:

Typ Wyświetlaj jeśli ...
- `chooser` dozwolone jest przełączenie na zdalny login.
- `halt` oraz `reboot` dozwolone jest zamknięcie systemu.
- `system` brak warunków (zawsze włączone w &kdm;).
- `plugin-``entry-name` wtyczka conversation udostępnia odpowiednie pole wprowadzania.

Na przykład:

    <show type="chooser"/>

Dodatkowo można określić wartości `min-screen-width` lub `min-screen-height` aby spowodować, iż pewne elementy powinny być wyświetlane tylko wtedy gdy rozdzielczość ekranu będzie większa lub równa pożądanej wielkości. Na przykład:

    <show min-screen-height="768"/>

### Znaczniki stanów elementu (normalny/aktywny/podświetlony)

Wygląd większości elementów może być ustawiany za pomocą następujących znaczników:

`normal`

- Stan normalny.

`prelight`

- Jeżeli myszka znajduje się nad elementem.

`active`

- Jeżeli nad elementem zostanie naciśnięty przycisk myszki.

Dokładny zbiór dostępnych atrybutów jest uzależniony od rodzaju elementu:

`rect`

-     <normal color="#000000" alpha="0.0"/>

  Każdy z opisywanych atrybutów może zostać pominięty, w takim wypadku użyte zostaną wartości domyślne (w przykładzie zastosowano wartości domyślne). Parametr `alpha` jest liczbą zmiennoprzecinkową o wartościach od zera (pełna przeźroczystość) do jeden (brak przeźroczystości). Wartość parametru`color` zaczyna się od znaku hash, który poprzedza 6 liczbową liczbę szesnastkową, której format jest następujący `#``rrggbb`. Możliwe jest także określenie wartości `color` za pomocą 8 znaków szesnastkowo, w takim przypadku pierwsze dwa znaki dotyczą wartości przeźroczystości (alpha).

`label`

-     <normal color="#ffffff" alpha="1.0" font="Sans 14"/>

  `alpha` oraz `color` są określane analogicznie jak dla elementów rect.

  Format parametru `font` jest analogiczny jak `family-list` `style-options` `size`. Każdy atrybut jest opcjonalny.

  `family-list` jest rozdzieloną przecinkami listą rodzin czcionek, jak np.: helvetica, monospace, itp.

  Parametr `style-options` jest rozdzielaną spacjami listą słów kluczowych z następujących kategorii: styl, waga i szerokość, z każdej kategorii po jednym słowie. Styl czcionki może być następujący: `normal`, `italic` lub `oblique`. Waga może być: `ultra-light`, `light`, `medium`, `semi-bold`, `bold`, `ultra-bold` lub`heavy`. Dostępne szerokości to: `ultra-condensed`, `extra-condensed`, `condensed`, `semi-condensed`, `normal`, `semi-expanded`, `expanded`, `extra-expanded` i `ultra-expanded`.

  Parametr `size` jest zmiennoprzecinkową liczbą określającą rozmiar czcionki w punktach (1/72 cala) lub liczbą całkowitą z przyrostkiem `px` określającą rozmiar w pikselach. Podawanie rozmiaru w punktach jest preferowane, gdyż jest niezależne od rozdzielczości ekranu.

  Jeżeli jakieś atrybuty są pominięte, użyte zostaną atrybuty znacznika style. Jeżeli nie będzie określonego koloru tekstu, to przyjęty zostanie kolor biały. Domyślne czcionki ustawiane są w programie &kdmrc;.

`pixmap`

`svg`

-     <normal file="picture.png" tint="#dddddd" alpha="1.0"/>

  `file` określa nazwę pliku zawierającego obrazek. Względne ścieżki są określane względem katalogu motywu.

  `element` określa nazwę elementu z pliku SVG do wyświetlenia. Jeżeli pusty, to cały obraz SVG zostanie wyświetlony.

  Dla znaczników map bitowych `pixmap`, program &kdm; próbuje najpierw otworzyć plik o nazwie: `nazwa_bazowa``-``szerokość` `x` `wysokość``.``rozszerzenie`, tak aby użyć pliku o rozdzielczości najlepiej pasującej do aktualnej rozdzielczości ekranu.

  Atrybut `scalemode` określa jak dopasowywać rozmiar obrazków, które nie pasują do rozmiaru elementu. Wartość `free` (domyślna) oznacza że obraz zostanie po prostu przeskalowany do właściwego rozmiaru, może to spowodować zaburzenie proporcji. Pozostałe dwa tryby zachowują proporcje obrazu:`fit` powoduje iż obraz zostanie powiększony do maksymalnego dozwolonego dla geometrii elementu rozmiaru. Obraz będzie wyśrodkowany. Pozostała wolna powierzchnia nie będzie wypełniona, dlatego też element powinien być umieszczony nad wypełnionym elementem `rect`. tryb `crop` oznacza powiększenie obrazu do minimalnego rozmiaru wypełniającego w całości obszar elementu. Wystające części obrazka zostaną obcięte symetrycznie.

  Atrybuty `tint` oraz `alpha` określają specyfikację kolorów analogicznie jak dla elementu `rect`. Każdy piksel obrazka jest mnożony przez ten kolor w skali całego elementu.

### Znaczniki stylów dla elementów interfejsu

Ten znacznik pozwala na zmianę wyglądu etykiet i elementów interfejsu Qt osadzonych w motywie, np. pól wprowadzania, przycisków lub list użytkowników. Ustawienia stylu są dziedziczone przez elementy podrzędne, ale mogą być nadpisane indywidualnie dla każdego elementu. Wartości domyślne pobierane są z &kdmrc;.

Atrybut `font` definiuje kolor dla wszystkich elementów interfejsu. Dla elementów mających funkcje wprowadzania danych, może być nadpisywany przez atrybut `edit-font`. Czcionki są określane analogicznie jak dla znaczników trybu normalnego/aktywnego/podświetlonego.

Standardowo, silnik motywów stara się bardzo usunąć wszelkie ramki z elementów interfejsu Qt, tak aby ładnie się komponowały w motywie. W przypadkach gdy takie zachowanie nie jest pożądane, należy ustawić wartość atrybutu `frame` na `true`.

Możliwe jest zdefiniowanie niemal całej palety elementów interfejsu zgodnie z dokumentacją na stronach firmy Trolltech. Nazwy atrybutów składają się z zakresu, roli koloru i przyrostka. Możliwe nazwy zakresów zgodnie z poziomem ważności są następujące: `all-` dla wszystkich grup kolorów, brak zakresu dla aktywnych i nieaktywnych grup kolorów, oraz odpowiednio `active-`, `inactive-` i `disabled-` dla poszczególnych grup kolorów. Dostępne role kolorów są następujące: `window`, `window-text`, `base`, `alternate-base`, `text`, `bright-text`, `highlight`, `highlighted-text`, `button` i `button-text`. Przyrostkiem może być `-color` albo `-alpha` o znaczeniu analogicznym jak dla znaczników trybu normalnego/aktywnego/podświetlonego.

Przykład:

    <style edit-font="Comic 16" text-color="#dddddd" frame="true"/>

### Znaczniki kolorów dla przeglądarki twarzy

Znaczniki kolorów pozwalają na nadpisanie koloru tła dla elementów przeglądarki twarzy. Atrybuty `labelcolor` i `altlabelcolor` są zasadniczo odpowiednikami atrybutów `all-base-color` i`all-alternate-base-color` w znacznikach stylu. Jeżeli jednak występuje atrybut `labelcolor` to alternatywne kolory tła elementu są wyłączone.

    <color labelcolor="#80ffffff" altlabelcolor="#80f0f0f0"/>

### Znaczniki tekstu

Znaczniki tekstu są wykorzystywane przez etykiety. Mogą być wykorzystane do wyświetlenia tekstu dostosowanego do lokalizacji w sposób następujący (jeżeli pominięto atrybut `xml:lang` do przyjmowana jest lokalizacja POSIX):

    <text xml:lang="fr">Option</text>

Znaczniki tekstowe mogą zawierać sekwencje specjalnie znaków, które mają następujące znaczenie:

Sekwencja Znaczenie
- %% Znak %
- %c Czas i data
- %d Wyświetla nazwę (zmienną środowiskową `DISPLAY`)
- %h Nazwa komputera (wynik działania `gethostname`)
- %m Nazwa maszyny (część machine wyniku polecenia `uname`)
- %n Nazwa węzła (część nodename wyniku polecenia `uname`)
- %o Nazwa domeny (wynik polecenia `getdomainname`)
- %r Nazwa dystrybucji (część release wyniku polecenia `uname`)
- %s Nazwa systemu (część sysname wyniku polecenia `uname`)
- %t Pozostała liczba sekund do wykonania opóźnionego logowania, wraz z odpowiednią formą liczby mnogiej słowa sekunda
- %u Nazwa użytkownika dla opóźnionego logowania
- _ Ustala skrót klawiszowy dla następującego po _ znaku

Sekwencje `%t` oraz `%u` są używane tylko wewnętrznie do wyświetlania etykiety opóźnionego logowania `timed-label`, która jest aktualizowana co sekundę.

### Znaczniki magazynu

Niektóre powszechnie występujące zlokalizowane etykiety mogą być określone za pomocą znaczników magazyny. Atrybut `text` jest ignorowany dla znacznika `stock`. Zamiast umieszczania wszystkich tłumaczeń wewnątrz motywu, lepiej jest stosować znaczniki magazynu. Dzięki temu można uzyskać szybsze ładowanie i prawdopodobnie lepsze tłumaczenia. Dostępne są następujące wartości:

Typ Znaczenie
- caps-lock-warning Caps Lock włączony
- chooser Wybie_rz protokół XDMCP
- quit Za_kończ
- disconnect _Rozłącz
- halt _Wyłącz komputer
- language _Język
- login _Zaloguj
- session _Typ sesji
- reboot _Uruchom komputer ponownie
- system _Menu
- timed-label Użytkownik %u zaloguje się w ciągu %t
- domain-label _Domena:
- username-label _Użytkownik:
- password-label _Hasło:
- welcome-label Witamy w %h

Na przykład:

    <stock type="welcome-label"/>

### Elementy stowarzyszone

Elementy, które bezpośrednio nie wywołują żadnego działania mogą mieć status stowarzyszonego. Element stowarzyszony będzie aktywowany gdy właściwy element jest aktywowany (kliknięty lub wybrany za pomocą klawisza akceleratora etykiety `label`).

Element stowarzyszony jest wskazywane za pomocą wartości 'id' w atrybucie `idref`. Oznacza to oczywiście, że musi posiadać nadaną nazwę id. Na przykład:

    <item type="label">
      <stock type="username-label"/>
      <buddy idref="user-entry"/>
      [...]
    </item>
    [...]
    <item type="entry" id="user-entry">
      [...]
    </item>