# Teemade loomine &kdm;-i tervitajaga (greeter)

See osa kirjeldab temaatilise tervitaja teemade loomist. Näiteid koos ekraanipiltidega vaata paigaldatud standardteemades ning teemade veebileheküljel.

## Teema ülevaade

&kdm; teemade loomisel tuleb luua XML-fail, mis järgib spetsifikatsiooni `$`KDEDIR`/share/apps/doc/kdm/greeter.dtd`. Teemafailid asuvad kataloogis `$`KDEDIR`/share/apps/kdm/themes/teema_nimi`. Teemakataloog peab sisaldama faili `KdmGreeterTheme.desktop`, mille vorming on samasugune nagu teistel `.desktop`-failid, nähes välja selline:

    [KdmGreeterTheme]
    Greeter=circles.xml
    Name=Circles
    Description=Theme with blue circles
    Author=Bond, James Bond
    Copyright=(c) 2002 Bond, James Bond
    Screenshot=screenshot.png

Väljad `Name`, `Description`, `Author` ja `Copyright` võivad olla tõlgitavad, nagu teistegi `.desktop`-failide puhul. Kõik mainitud failid peavad asuma teemakataloogis endas, Väli `Screenshot` osutab failile, mis võib olla kasutuses teema 200x150 pilt (seda ei pruugi olla, aga pilti on muidugi kena vaadata). Väli `Greeter` osutab XML-failile, mis sisaldab teema kirjeldust.

Kui teema on põhjalikult testitud, paki see kokku failiks, mis sisaldab kataloogi, mis paigaldatakse kataloogi `$`KDEDIR`/share/apps/kdm/themes`. See on &kdm;-i teemade levitamise standardvorming.

## Teema XML-vormingu üksikasjalik kirjeldus

### Tipptaseme sõlm

&kdm;-i teemad on XML-failid, mille juures on silt <greeter>. Tipptaseme sõlm on elemendi sõlm tüübiga `rect` ja selge fikseeritud paigutusega.

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

Sildis greeter võivad sisalduda sõlmed, mida kirjeldatakse käsiraamatu järgmistes osades. Osad sõlmed on konteinerid (paigutuse sõlmed, elemendi sõlmed), mis võivad omakorda sisaldada sõlmi.

### Elemendi sõlmed

&kdm;-i teema loomisel määratakse kindlaks elemendi ja paigutuse sõlmede hierarhia. Elemendi sõlmed võivad sisaldada atribuudi `type` järgmisi väärtusi:

button

  Nupuväli. See väli kasutab Qt nuppu.

  Ka mis tahes muu element on võimalik panna käituma nupuna, kui määrata tema atribuudile `button` väärtus `true`. Siiski on etem kasutada &kdm;-i teemades Qt nuppe, sest need on kasutatavad ka puuetega kasutajate korral.

entry

  Sisendvidin, näiteks tekstikast või liitkast. Pane tähele, et see on kõigest Qt vidinate kohatäitja.

label

  Tekstipealdis. Peab sisaldama kas sõlme `text` või sõlme `stock`, mis määrab teksti.

list

  Näosirvija vidin.

pixmap

  Rasterpilt Qt toetatud vormingus, &eg; PNG, JPEG, TIFF jne.

rect

  Ristkülik.

svg

  Vektorpilt SVG-vormingus.

Näide:

    <item type="label">

Element, mis toimib nupuna:

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

Vaikimisi kaob &kdm;-i sisselogimisekraan pärast autentimist. See võib põhjustada vilkumist sisselogimisekraani ja seansi vahepeal. Atribuut `background` võimaldab kasutajal määrata, millised teema elemendid on taustapilt. Kasutamise korral paneb see &kdm;-i eemaldama kuvalt kõik mitte-taustaelemendid ja renderdama allesjäänud atribuudi `background` elemente juuraknas. Nii saab luua sujuva ülemineku sisselogimisekraani ja seansi vahel:

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

Sisselogimisest erineva tausta kasutamiseks ülemineku ajal peab teema määratlema kaks sõlme (need võivad sisaldada näiteks raster- või SVG-pilte). Tervitaja taustale vastaval elemendil ei tohi siis olla omadust `background`, ülenimekule vastaval elemendil aga peab omadus `background` kindlasti olema. Näide:

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

Mitme monitoriga süsteemides võivad teemad määrata ka teiste ekraanide välimuse kui see, millel asub tervitaja, kuid reeglina on seal näha ainult taustaelemendid. Määramaks, millisel ekraanil on mõni element näha, saab kasutada atribuuti `screen`, millele saab lisada väärtuse `greeter`, `other` või `all`, mis vastavalt tähendab ekraani, millel tervitaja asub, kõiki neid ekraane, millel tervitaja ei asu, ning kõiki ekraane.

Igale elemendile võib anda nime atribuudi `id` abil. &kdm; tunneb ära teatud ID-d ja annab neile erilise funktsiooni:

`button` elemendid ja elemendid atribuudiga `button="true"`.

  Nupud käivitavad reeglina teatud toimingu. Lisaks peidab &kdm; nupud, mille toiming pole mingil põhjusel kättesaadav.

  Id
  Toiming
  chooser_button
  Käivitab XDCMP valija.
  disconnect_button
  Katkestab võrguseansi.
  session_button
  Avab seansitüübi valimise menüü.
  system_button
  Avab üldise menüü paljude valikute ja toimingutega sõltuvalt seadistusest.
`label` elemendid

  &kdm; näitab või peidab need pealdised ja määrab nende teksti sõltuvalt sisselogimisdialoogi olekust.

  Id
  Funktsioon
  pam-error
  Näitab teadet Sisselogimine nurjus.
Vidinat põimivad elemendid

  &kdm; põimib neisse elementidesse teatud Qt vidinad.

  Id
  Funktsioon
  user-entry
  Kasutajanime kirje väli.
  pw-entry
  Paroolikirje väli.
  domain-entry
  Mõned suhtlemispluginad kasutavad seda välja domeeninime pärimiseks. Kui väli on olemas, peavad nendega seotud suluselemendid olema näitamissõlmed tüübiga `plugin-domain-entry`.
  talker
  See element peab olema tüübiga `rect`. See tähistab tervitaja kuuma ala: see sisaldab elemente `label` ja `entry`, mis puudutavad autentimist. Kui antud suhtlusplugin ei suuda vastata olemasolevatele elementide vajadustele, püüab ta põimida elementi omaenda paigutusega kompleksvidina, mis täielikult tühistab teema talker'i. Põhimõtteliselt ei vaja &kdm;-i teemad üldse omaenda taltker'i paigutust, sest kõik &kdm;-i autentimispluginad võivad kasutada elementi `talker`.
  userlist
  See element peab olema tüübiga `list`. Kui kasutajate nimekirja võimalus on lubatud, põimib &kdm; siia kasutajate nimekirja vidina. Vastasel juhul element peidetakse.
  xconsole
  See element peab olema tüübiga `rect`. Kui sisseehitatud `xconsole` omadus on kompileeritud ja lubatud, põimib &kdm; siia konsolli logi vidina. Vastasel juhul element peidetakse.
Muud elemendid

  &kdm; näitab neid elemente või peidab nad sõltuvalt seadistusest ja tervitaja hetkeolekust. &kdm; ei kehtesta neile tüübinõuet, kuid tavaliselt on nad siiski teatud kindlat tüüpi.

  Id
  Näidatakse ainult siis, kui...
  timed-label
  ...käib sisselogimine.
  caps-lock-warning
  ...Caps Lock on sees.
  xauth-warning
  ...&X-Server; ei nõua ühendumiseks X'i autentimist.
  userlist-rect
  ...kasutajate nimekiri on lubatud. Pesastades siis elemendi `userlist`, on võimalik luua näiteks raam nimekirja ümber ja lasta seda näidata ainult siis, kui näidatakse kasutajate nimekirja.
  xconsole-rect
  ...sisseehitatud `xconsole` on lubatud. Samalaadne nagu `userlist-rect`.

### Paigutuse konteinersõlmed

Paigutuse sõlmed esinevad elemendi sõlmede sees ja sisaldavad omakorda elemendi sõlmi. Paigutuse sõlme tüüp märäab tema alamsõlmede korra. Elemendi sõlm võib sisaldada igast paigutuse sõlme tüübist ühe.

#### Kastsõlmed

Kastsõlmed korraldavad oma järglased automaatselt ritta. Nad on määratletud järgmiselt:

    <box orientation="joondus" min-width="arv" min-height="arv"
        xpadding="arv" ypadding="arv" spacing="arv"
        homogeneous="tõeväärtus">

kus joondus tähendab pikslite arvu ja tõeväärtus on kas `true` või `false`. Kui jätta mõni atribuut ära, siis määratakse vaikimisi selle väärtus nulliks arvude korral, false tõeväärtuse korral ning `vertical` orientatsiooni korral.

Spacing on vahe kõrvutiste järglaselementide vahel. Padding on kasti väline piir. Kui kast on homogeenne, omistatakse igale järglaselemendile ühesugune ruum.

#### Fikseeritud sõlmed

Fikseeritud sõlmed on konteinerid, mille järglased on paigutatud täpsetele koordinaatidele. Konteineri suurus on väikesim ristkülik, mis sisaldab kõiki järglasi. Fikseeritud sõlmel ei ole lisaatribuute, nii et kasutada tuleb lihtsalt:

    <fixed>

Seejärel tuleb asetada sellesse teised elemendid, määrates nende positsiooni sõlmed.

### Positsiooni sõlmed

Iga element võib määrata oma positsiooni ja suuruse sõlmega `pos`. Näide:

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

Kui suurust pole määratud, saab selleks elemendi loomupärane suurus, mida nimetatakse suurusevihjeks. Pane tähele, et mitte kõigil elementidel ei ole mõistlikku suurusevihjet.

Nii positsiooni kui ka suuruse võib anda protsendina, millisel juhul see arvutatakse suhtelisena ümbritseva konteineri suuruse suhtes. Tipptaseme elementide korral on see protsent tervest ekraanist. Katuse lisamisega (`^`) suuruse määatlusele on võimalik seda muuta, nii et see oleks suhtelise ümbritsevat elementi ümbritseva elemendi ümbritseva elemendi ja nii edasi suuruse suhtes.

Kui element sisaldab kasti, võib määrata, et `width` ja `height` on `box`, mis tähendab, et nad on kasti laius ja kõrgus, see tähendab elemendid kastis pluss lisaruum (padding).

Võib määrata, et `width` või `height` on `scale`, mis tähendab, et neid tuleb skaleerida vastavalt teisele mõõtmele, arvestades suurusevihjet. Seda on mõtet kasutada, kui soovid, et skaleeritud piltide proportsioon automaatselt säilitataks.

Kui määatud on atribuut `expand` ja atribuut `true`, siis laiendatakse elementi ümbritsevas kastis nii palju kui võimalik (see tähendab, et talle antakse võimaluse korral rohkem ruumi).

Kui `width` või `height` on lihtsalt arv, tähendab negatiivne väärtus nihet ümbritseva konteineri suurusest. Pane tähele, et on võimalik määrata ka positiivne nihe, kirjutades kaks miinusmärki.

Mõlemal juhul on võimalik piirata lõppsuurust atribuutidega `min-width`, `min-height`, `max-width` ja `max-height`, mida saab määratleda samamoodi nagu atribuute `width` ja `height`.

Kui `x` või `y` on lihtsalt arv, siis tähendab negatiivne arv nihet paremast või alumisest servast, positiivse puhul aga vasakpoolset või ülemist serva.

Samuti on võimalik määrata, millisele elemendi punktile positsioon osutab. Seda nimetatakse ankruks ja see võib olla kas `c` (tsentreeritud) või `n`, `ne`, `e`, `se`, `s`, `sw`, `w` ja `nw`, mis tähistavad erinevaid servi/nurki vastavalt ilmakaartele. Vaikimisi on see `nw`, mis tähendab ülemist vasakut nurka. Näide:

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

### Näitamissõlmed

Võib määrata atribuudi `type`, mis osutab, et teatud elemente tuleb näidata ainult siis, kui tüüp on määratud. Lisades tüübi ette hüüumärgi, (`!`), muudetakse tingimus vastupidiseks. Kehtivad väärtused on järgmised:

Tüüp
Näidatakse, kui...
chooser
lubatud on lülitumine võrgust sisselogimisele.
halt
ja `reboot`
lubatud on süsteemi seiskamine.
system
tingimus puudub (&kdm;-is alati määratud).
plugin-
entry-name
suhtlusplugin pakub vastava sisendvälja.

Näide:

    <show type="chooser"/>

Lisaks võib määrata `min-screen-width` või `min-screen-height` väärtuse, mis osutab, et teatud elemente näidatakse ainult siis, kui ekraanilahutus on vähemalt määratud suurusega. Näide:

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

### Tavaline/aktiivne/hiirealune sõlm

Enamiku elemenditüüpide välimust võib määrata järgmiste siltidega:

`normal`

  Tavaline olek.

`prelight`

  Kui hiirekursor viibib elemendi kohal.

`active`

  Kui elemendil klõpsatakse hiirenupuga.

Saadaolevate atribuutide täpne valik sõltub elemendi tüübist:

`rect`

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

  Ükspuha kumma atribuudi võib ära jätta, millisel juhul kasutatakse vaikeväärtust (näide näitabki vaikeväärtusi). `alpha` on murdarv vahemikus null (läbipaistev) kuni üks (läbipaistmatu). `color` koosneb trellidest, millele järgneb kuuekohalike arv: vorming on `#`rrggbb. Selle kõrval võib `color` olla määratud ka kaheksakohalise arvuna, millisel juhul kaks esimest arvu on alfakanali väärtus.
`label`

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

  `alpha` ja `color` on määratud nagu rect elemendid.

  `font` on vormingus perekonna-nimekiri stiilivalikud suurus. Ükski osa ei ole kohustuslik.

  perekonna-nimekiri on komadega eraldatud fondiperede nimekiri, näiteks helvetica, monospace jne.

  stiilivalikud on tühikutega eraldatud kategooriate stiil, kaal ja ulatus võtmesõnade nimekiri, kusjuures igast kategooriast võib olla maksimaalselt üks. Stiil võib olla `normal`, `italic` või `oblique`. Kaal võib olla `ultra-light`, `light`, `medium`, `semi-bold`, `bold`, `ultra-bold` või `heavy`. Lubatud ulatused on `ultra-condensed`, `extra-condensed`, `condensed`, `semi-condensed`, `normal`, `semi-expanded`, `expanded`, `extra-expanded` ja `ultra-expanded`.

  suurus on kas murdarv, mis näitab suurust punktides (1/72 tolli) või täisarv, millele järgneb `px`, mis näitab suurust pikslites. Punktisuurus on eelistatav, sest see ei sõltu lahutusvõimest.

  Kui mõni atribuut on andmata, kasutatakse stiili sõlme väärtusi. Kui see ei anna aknateksti värvi määratlust, kasutatakse valget. Vaikefont on määratud failis &kdmrc;.

`pixmap`
`svg`

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

  `file` määrab pilti sisaldava faili. Suhtelised asukohtade puhul lähtutakse teemakataloogi asukohast.

  `element` määrab SCG-faili elemendi ID. Kui see on andmata, renderdatakse kogu SVG-pilt.

  `pixmap` sõlmede puhul püüab &kdm; kõigepealt avada faili, mille puhul baasnimi`-`laius `x` kõrgus`.`laiend vastab määratud failinimele, nii et kasutatakse antud lahutusega parima kvaliteediga pilti.

  `scalemode` määrab, kuidas kohandada nende piltide suurust, mis ei sobi elemendi suurusega. `free` (vaikeväärtus) tähendab lihtsalt pildi skaleerimist õigesse suurusesse, millega võib kaasneda proportsiooni moonutamine. Teised kaks valikut säilitavad proportsiooni: `fit` tähendab pildi suurendamist maksimaalse elemendi geomeetriaga lubatud suuruseni. Pilt tsentreeritakse. Ülejäänud ala see element täis ei joonista, niisiis tuleb see asetada ühtlaselt täidetud ristküliku `rect` peale. `crop` tähendab pildi suurendamist minimaalse suuruseni, mis täidaks täielikult elemendi geomeetria. Pilti kärbitakse sümmeetriliselt.

  `tint` ja `alpha` moodustavad värvimääratluse nagu `rect` elementides. Iga pildi piksel korrutatakse värvikomponendiga.

### Vidinastiili sõlmed

See silt võimaldab muuta pealdiste ja teemasse põimitud Qt vidinate välimust, nt tekstikastid, nupud või kasutajate nimekiri. Stiiliseadistused päritakse järglaselementidelt, kuid neid võib ükshaaval tühistada. Vaikeväärtused võetakse failist &kdmrc;.

Atribuut `font` määrab kõigi vidinate fondi. Sisendifunktsiooniga vidinate puhul saab seda tühistada atribuudiga `edit-font`. Fondid on määratud samamoodi nagu normaalne/aktiivne/hiirealune sõlmes.

Tavaliselt püüab teemamootor igati eemaldada Qt vidinatest raamid, et nad sulanduksid sujuvalt teemasse. Kui see pole aga soovitatav, võib atribuudile `frame` anda väärtuse `true`.

Vidinatele on võimalik määrata peaaegu kogu palett, nagu seda dokumenteerib Trolltechi sait. Atribuudi nimed koosnevad skoobist, värvirollist ja sufiksist. Võimalikud skoobid on - kasvava eesõiguse järjekorras. `all.` kõigile värvigruppidele, skoobita aktiivsetele ja mitteaktiivsetele värvigruppidele ning `active-`, `inactive-` ja `disabled-` vastavale värvigrupile. Toetatud värvirollid on `window`, `window-text`, `base`, `alternate-base`, `text`, `bright-text`, `highlight`, `highlighted-text`, `button` ja `button-text`. Sufiks võib olla `-color` või `-alpha`, mille tähendus on samasugune nagu normaalne/aktiivne/hiirealune sõlmes.

Näide:

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

### Näosirvija värvi sõlmed

Värvisõlmed lubavad tühistada näosirvijas elementide taustavärvi. `labelcolor` ja `altlabelcolor` on põhimõtteliselt sama, mis `all-base-color` ja `all-alternate-base-color` stiilisõlmedes. Kui määratud on ainult `labelcolor`, on elemendi taustade vahetamine keelatud.

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

### Teksti sõlmed

Tekstisilte kasutavad pealdised. Neid võib kasutada lokaliseeritud teksti kuvamiseks järgmiselt (kui atribuut `xml:lang` puudub, eeldatakse POSIX-i lokaati):

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

Tekstisõlmed võivad sisaldada järgmisi spetsiaalseid märgijadasid, mis tõlgitakse järgmiselt:

Jada
Laiendamine
%%
Märk %
%c
Kella aeg ja kuupäev
%d
Kuva nimi (keskkonnamuutuja `DISPLAY`)
%h
Masinanimi (`gethostname` väljund)
%m
Masinanimi (machine osa `uname` väljundist)
%n
Sõlmenimi (nodename osa `uname` väljundist)
%o
Domeeni nimi (`getdomainname` väljund)
%r
Väljalaske nimi (release osa `uname` väljundist)
%s
Süsteemi nimi (sysname osa `uname` väljundist)
%t
Jäänud sekundite arv ajastatud sisselogimise korral pluss vastav i18n mitmuse vorm sõnast sekund
%u
Kasutajanimi ajastatud sisselogimise korral
_
Põhjustab järgneva märgi muutumise kiirklahviks

`%t` ja `%u` pn mõeldud kasutamiseks ainult teate `timed-label` kuvamisel, mida uuendatakse atuomaatselt iga sekund.

### Tüvisõlmed

Teatud üldisi lokaliseeritud pealdisi võib määratleda tüvisiltidega. Silti `text` eiratakse, kui kasutatakse silti `stock`. Palju mõistlikum ongi kasutada tüvipealdisi, mitte lisada teemasse kõik tõlked. See tagab kiirema laadimise ja tõenäoliselt ka parema tõlke. Lubatud on järgmised väärtused:

Tüüp
Laiendamine
caps-lock-warning
Caps Lock on sees
chooser
XDMCP _valija
quit
_Välju
disconnect
La_huta
halt
_Seiska
language
_Keel
login
_Logi sisse
session
Seansi _tüüp
reboot
_Taaskäivita
system
_Menüü
timed-label
Kasutaja %u logib sisse %t pärast
domain-label
_Domeen:
username-label
Kas_utajanimi:
password-label
_Parool:
welcome-label
Tere tulemast - %h

Näide:

    <stock type="welcome-label"/>

### Semusõlmed

Elemendid, mis ei põhjusta otseselt toimingut, võib omistada semule. Semule antakse sisendifookus, kui element aktiveeritakse (klõpsamisel või elemendi `label` kiirklahvi vajutamisel).

Semule osutatakse ID-ga atribuudis `idref`. Seepärast peab tal mõistagi olema ID. Näide:

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