# Guia d'estil de la finestra de xat del &kopete;

## Referència d'estil de la finestra de xat del &kopete;.

Des del &kopete; 0.12, usem el format Adium per al nostre estil de finestra de xat. El format del tema està basat en plantilles HTML i CSS. Són més simples de fer i desenvolupar, només cal un coneixement d'HTML i CSS. A més, els estils poden tenir variants (definides com a fitxer CSS) que afegeixen més valor de personalització :).

### Guia de referència.

El format Adium consisteix en una estructura de directoris, plantilles HTML, fitxers CSS i paraules clau que es reemplacen cada cop que es processa la plantilla. La conversa final és una pàgina XHTML on els missatges s'afegeixen amb operacions DOM. L'element central és un element div anomenat `Xat`. Abans i després aquest element div va la plantilla Capçalera i Peu. Els missatges són fills de l'element div `Xat`.

#### Estructura de directoris

Un estil ha de respectar aquesta estructura de directoris. La programació al &kopete; pensa mitjançant aquesta estructura de directoris. Quan s'arxiva l'estil, s'arxiva el directori `styleName`. L'estructura de directoris és una estructura d'un bundle Mac OS X per a aquells familiaritzats amb aquest sistema operatiu. També heu de respectar la caixa que es mostra aquí, perquè un sistema UNIX és sensible a caixa.

    styleName\ (pot tenir .adiumMessageStyle com a sufix, perquè al Mac OS X això és un bundle)
            Contents\
                    Info.plist
                    Resources\
                            main.css
                            Header.html
                            Footer.html
                            Status.html
                            Incoming\ (and Outgoing\)
                                    Content.html
                                    NextContent.html (for consecutive messages)
                                    Context.html (for message history)
                                    NextContext.html
                                    Action.html
                            Variants\
                                    *.css

#### About <div id="insert"></div>

Això és un element div especial usat internament. És un marcador de posició per a indicar on inserir el següent missatge. Si és un nou missatge, aquest s'esborra i té lloc el nou missatge. Però si és un missatge consecutiu, l'element div es reemplaça amb el contingut del nou missatge. Aquest element div especial és obligatori a les plantilles Content,Context,NextContent,NextContext. Tot i que no està malament posar-lo també a les plantilles Action i Status.

#### Plantilles HTML.

##### Descripció de la plantilla.

`Header.html` (Obligatori)

  Usa la plantilla Header per a mostrar una capçalera maca a la conversa. Aquesta plantilla s'insereix abans de l'element div `Chat`. Si no l'useu, poseu-hi un fitxer buit.

`Footer.html` (Obligatori)

  Això és bàsicament el mateix que Header, però és per al peu d'una conversa. Aquesta plantilla s'insereix després de l'element div `Chat`. Si no l'useu, poseu-hi un fitxer buit.

`Status.html` (Obligatori)

  Aquesta plantilla s'usa per a mostrar un missatge intern. Els missatges interns com el canvi d'estat, missatge del Kopete (&pex; el rebut d'una transferència de fitxer). Quan l'estil no proveu una plantilla d'acció, se sol mostrar el missatge Action.

`Incoming/Content.html`
`Outgoing/Content.html` (Obligatori)

  La plantilla de contingut és el cor del missatge. Penseu en ell com a un bloc que no reté missatges. Assegureu-vos que està preparat per a rebre missatges consecutius, no el dissenyeu per a rebre només un missatge. Els missatges consecutius s'inseriran a l'element d'inserció div.

`Incoming/NextContent.html`
`Outgoing/NextContent.html` (Obligatori)

  La plantilla NextContent és un fragment de missatge per a missatges consecutius. S'inserirà al bloc principal del missatge. La plantilla HTML ha de contenir el mínim per a mostrar un missatge.

`Incoming/Action.html`
`Outgoing/Action.html` (Opcional) (Extensió del &kopete;)

  Aquesta plantilla és una extensió del &kopete; al format Adium. Està disponible en les direccions d'entrada i sortida. Els missatges d'acció són missatges especials per a dir que fem una acció. Exemple: «/me està instal·lant el &kopete;» apareixeria com a «DarkShock està instal·lant el &kopete;».

`Incoming/Context.html`
`Incoming/NextContext.html`
`Outgoing/Context.html`
`Outgoing/NextContext.html` (Opcional)

  Aquestes plantilles no s'usen al Kopete. A l'Adium, s'usen per a mostrar l'historial. És bàsicament el mateix que Content i NextContent però amb algunes diferències per a distingir-los dels missatges normals.

#### Quant als estils CSS i variants

La plantilla HTML s'usa per a descriure com es fa l'estructura. Però tot all l'estil es descriu en fitxers CSS. `main.css`és l'estil principal, on les variants són només alteracions de l'estil principal. Exemples de variants són els diferents colors, no mostrar la foto de l'usuari. Tant `main.css` com les variants s'importen en una pàgina XHTML final.

##### -`main.css`

Aquest és el fitxer principal CSS que és comú per a totes les variants. Aquest fitxer ha de contenir tota la descripció principal de l'estil.

##### -Variants

Les variants són fitxers CSS localitzats al directori `Variants/`. Cada variant és un únic fitxer CSS que inclou el `main.css` i altera l'estil principal.

#### Estils de depuració

Aquí hi ha dues pistes per a provar l'estil quan el creeu.

##### -Deseu una conversa de mostra.

En una finestra de xat, podeu desar una conversa. Aquesta és una còpia de la pàgina interna XHTML mostrada. Useu-la al Konqueror per a provar els vostres fitxers CSS.

##### -Desactiveu la memòria cau de l'estil.

Hi ha un petit commutador de configuració per a desactivar la memòria cau de l'estil. Quan està activat, recarrega les plantilles HTML cada cop que se li pregunta a l'estil. Afegiu les següents línies al vostre `kopeterc`. Molt útil quan proveu un estil al &kopete;.

    [KopeteStyleDebug]
    disableStyleCache=true

### Referència de paraules clau

Les paraules clau són com a forats per a omplir-los de detalls. En cada nou missatge, es reemplacen amb el valor correcte corresponent al seu context. Per a una compatibilitat amb totes les característiques del Kopete, hem afegit algunes extensions de paraules clau a l'Adium. A més, algunes paraules clau només estan disponibles en cert context.

#### Llista de paraules clau per a plantilles de Capçalera i Peu.

Aquestes paraules clau es processen al principi del xat.

`%chatName%`

  Aquest és el nom de la sessió actual de xat. Per a una sessió típica, mostra el nom del contacte i el seu estat. Per a IRC, mostra l'assumpte del canal.

`%sourceName%`
`%destinationName%`

  Aquests són els contactes per a una sessió de xat. `%sourceName%` és el vostre nom. `%destinationName%` és el nom del contacte amb esteu xatejant. Preferim `%chatName%` sobre aquests, perquè poden ser confusos per al xat de grup i l'IRC.

`%incomingIconPath%`
`%outgoingIconPath%`

  Aquestes són les imatges, fotos o avatars dels contactes per a la sessió de xat. Incoming representa la foto del contacte i Outgoing representa la vostra foto. Si no hi ha cap foto disponible, usa la imatge `buddy_icon.png` que està localitzada al directori `Incoming` o `Outgoing`.

`%timeOpened%`
`%timeOpened{X}%`

  És l'hora a la que comença la sessió de xat. `%timeOpened%` usa per defecte el format d'hora de les locals actuals. Si voleu usar un format específic d'hora, useu `%timeOpened{X}%` on X és una cadena que conté el format d'hora. Els paràmetres d'hora són els mateixos que la funció glibc `strftime`. Feu `man strftime` per a obtenir la llista de paràmetres disponibles.

#### Llista de paraules clau per a les plantilles Content, NextContent, Context, NextContext, Action.

Aquestes paraules clau es processen per a cada missatge.

`%userIconPath%`

  Aquesta és la imatge, foto o avatar del contacte associat amb el missatge. Si no hi ha cap foto disponible, usa `buddy_icon.png` la imatge a la qual està localitzat als directoris `Incoming` i `Outgoing` depenent de l'adreça del missatge.

`%senderScreenName%`

  Aquesta és la identificació de contacte associat amb el missatge. Exemples: me@hotmail.com, 45566576, JohnSmith.

`%sender%`

  Aquest és el nom del contacte associat amb el missatge. Usa el nom de mostra del Metacontacte com a font.

`%service%`

  Mostra el nom del servei associat amb el missatge. Exemples: Jabber, Yahoo, MSN.

`%textbackgroundcolor{X}%`

  Al &kopete;, aquesta paraula clau s'usa per a representar el color de fons del ressaltat. Ignoreu el paràmetre en claus i useu-lo només com a `%textbackgroundcolor{}`.

`%senderStatusIcon%` (extensió del &kopete;)

  Mostra la icona d'estat del contacte associat amb el missatge. És un camí cap a un fitxer.

`%senderColor%`
`%senderColor{N}%` (extensió del &kopete;)

  Genera un color des de la identificació de contacte del remitent. Es pot usar per a mostrar un color diferent per al sobrenom de contacte.

  `%senderColor{N}%` on N és un nombre positiu. Si N és més gran que 100, representa un color més lleuger que el color del contacte. Si N és igual a 150, és un color que és un 50% més brillant. Si N és menys de 100, llavors és un color fosc. És útil per a tenir un fons de color diferent per a cada contacte.

  Si voleu usar aquests colors en una variant, però no a l'estil principal, haureu de trobar una solució.

      <div style="color:%senderColor%;border:none;border-color:%senderColor{40}%;"
      ><p class="message"
      >...</p
      ></div>

  podeu aplicar color a l'element p.message al vostre fitxer `main.css`, i la vostra variant posa alguna cosa com

      p.message { color:inherit; border-color:inherit; }

#### Llista de paraules clau comuna per a missatges i Status.html

`%message%`

  El missatge mateix. Això és un fragment HTML.

`%time%`
`%time{X}%`

  L'hora en que es va rebre el missatge. `%time%` usa el format d'hora de les locals actuals. Si voleu usar un format d'hora específica, useu `%time{X}%` on X és una cadena que conté el format d'hora. Els paràmetres d'hora són el mateix que la funció glibc `strftime`. Feu `man strftime` per a obtenir la llista de paràmetres disponibles.

`%messageDirection%` (Extensió del &kopete;)

  Representa la direcció del missatge, si el missatge s'ha de mostrar de dreta a esquerra o d'esquerra a dreta. Els valors són «rtl» o «ltr». Llegiu Guia de direcció de Missatge per a veure com usar aquesta paraula clau correctament.

## Guia d'estil de finestra de xat del &kopete;

La guia d'estil de finestra de xat del &kopete; és un conjunt de coses amb les quals ha de ser compatible el vostre estil de finestra de xat per a complir amb el Kopete.

### Compatible amb ressaltat

El vostre estil ha de mostrar el ressaltat. Al Kopete i l'Adium, el `%textbackgroundcolor{}%` es reemplaça amb el color de ressaltat. Afegiu aquest atribut d'estil: `background-color: %textbackgroundcolor{}%` a l'element HTML que mostri el missatge.

### Calen plantilles de missatges consecutius.

Aquesta guia és per a gent que reescrigui antics estils XSL al nou format. Tots els estils han de proveir una plantilla per als missatges consecutius. Ara és una característica per defecte.

### Useu la codificació UTF-8.

El títol ho diu tot. Heu de desar els vostres fitxers a UTF-8.

### Subministra `Contents/Info.plist` per a la interoperabilitat amb l'Adium

El fitxer `Contents/Info.plist` no s'usa encara al Kopete. Però si voleu que el vostre estil sigui compatible amb l'Adium, heu de subministrar aquest fitxer. Aquí hi ha un exemple bàsic de fitxer. Les cadenen a reemplaçar estan entre «$».

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
            <key
    >CFBundleDevelopmentRegion</key>
            <string
    >English</string>
            <key
    >CFBundleGetInfoString</key>
            <string
    >$Your style full name$</string>
            <key
    >CFBundleIdentifier</key>
            <string
    >$Your style ID in the form: com.adiumx.smooth.operator.style$</string>
            <key
    >CFBundleInfoDictionaryVersion</key>
            <string
    >1.0</string>
            <key
    >CFBundleName</key>
            <string
    >$Your style name here$</string>
            <key
    >CFBundlePackageType</key>
            <string
    >AdIM</string>
            <key
    >MessageViewVersion</key>
            <integer
    >3</integer>
    </dict>
    </plist>

### Subministra `buddy_icon.png`

Heu d'emplaçar un fitxer anomenat `buddy_icon.png` a `Incoming` i `Outgoing`. Aquestes imatges s'usaran quan el contacte no tingui foto.

### Subministra idiomes que s'escriuen de dreta a esquerra amb la paraula clau `%messageDirection%`.

La paraula clau `%messageDirection%` és present per als idiomes del món que s'escriuen de dreta a esquerra. Defineix la direcció del missatge, si és «rtl» (right-to-left -dreta a esquerra-) o «ltr» (left-to-right -esquerra a dreta-). Afegiu aquest atribut d'estil a l'element HTML que mostra el missatge: `direction: %messageDirection%`. La previsualització de l'estil a la configuració de l'aparença inclou dreta a esquerra per a verificar si el vostre estil el mostra correctament. Hauria de començar la cadena per la dreta.