From Amarok Wiki
Contents |
Introduktion
Image:Scriptmanager 1.3.png Ved at scripte kan du udvide amaroK på mange måder, uden at ændre i selve kodebasen. Scripts svarer på mange måder til plugins, men i stedet for et dedikeret plugin API kommunikerer de igennem amaroKs DCOP interface. Det gør det muligt at skrive scripts i stort set alle programmeringssprog, såsom Ruby, Python og PHP. Men ikke blot kan du lave scripts i de klassiske scriptsprog, du kan også bruge kompilerede sprog som C++ eller blot C.
Ydermere kan amaroK underrette dine scripts ved specielle events så de kan reagere derefter. Dette orienteringssystem vil blive forklaret senere i dokumentet.
Bindinger
Det er både muligt at skrive simple scripts der ikke kræver nogen handling fra brugeren, og avancerede scripts med behagelige GUIer der fungerer som små, selvstændige programmer. Til GUI-programmering kan man bruge en af de mange bindinger som KDE leverer, for eksempel RubyQt, en binding mellem Qt og Ruby. Dog er det værd at bemærke at ikke alle brugere har de nødvendige bindinger installeret. Hvis du beslutter dig for at bruge en sådan, så brug så vidt muligt en af de mere gængse (f.eks. RubyQT eller PyQT).
For at kunne levere noget ordentlig feedback når et script fejler som følge af en manglende afhængighed bør dit script først undersøge om det modul der skal inkluderes virkelig eksisterer. Hvis afhængigheden mangler, bør du fange fejlen og vise den til brugere gennem værktøjet "kdialog", således at brugeren kan finde ud af hvorfor scriptet ikke virker.
Her er et eksempel på hvordan man kan fange en manglende afhægighed i Ruby:
begin
require 'Korundum'
rescue LoadError
error = 'Korundum (KDE bindings for ruby) from kdebindings v3.4 is required for this script.'
`kdialog --sorry '#{error}'`
exit
end
Begyndelsen: Eksempler
Med amaroK følger nogle scripts i adskillige sprog, der viser hvorledes det hænger sammen. Disse scripts ligger i mappen scripts/templates/. Du kan bruge dem som basis for dine egne scripts og udvide dem efter behov. Du vil hurtigt opdage at det faktisk er forholdsvis simpelt at kode. Hvis du f.eks. ved lidt om at kode i Python vil det ikke tage dig lang tid at regne ud hvorledes det fungerer :) TODO: Vi mangler flere eksempler! Hvis du laver et, så send det venligst til vores postliste amarok@kde.org.
Styr amaroK med DCOP
Scripts kan styre amaroK ved at benytte nogle af dets DCOP funktioner. Den nemmeste måde at kalde en DCOP funktion på er at bruge shell-kommandoen "dcop", der er en del af KDE distributionen. Her er et eksempel der øger lydstyrken:
"dcop amarok player volumeUp"
De fleste scriptsprog kan eksekvere shell-kommandoer med en funktion som exec(). På denne måde er det nemt at benytte DCOP. Her er et simpelt eksempel i Python:
import os
os.system("dcop amarok player volumeDown")
Underrettelser
amaroK underretter alle kørende scripts ved at printe strenge til deres stdin. Et script bør derfor konstant overvåge stdin og agere retmæssigt til hvert event. Man kan også bare ignorere de events man ikke har brug for.
Her er en liste over de ting amaroK underretter om:
- configure
- Beder scriptet om at vise et vindue med indstillinger. Scriptet skal selv håndtere at gemme og indlæse indstillingerne. Når et script bliver startet, sætter amaroK dets aktive mappe til den folder hvor alle data bør blive gemt.
- engineStateChange: {empty|idle|paused|playing}
- Markerer en ændring i afspillerens status.
- trackChange
- Markerer starten på et nyt nummer. Scriptet kan så bruge DCOP funktionerne til at skaffe mere info om nummeret, for eksempel metadata og længde.
- volumeChange: {newVolume}
- Markerer en ændring i den overordnede lydstyrke. Lydstyrken er et tal mellem 0 og 100
Bemærk: Dette blev tilføjet i amaroK 1.3 serien.
- customMenuClicked: {submenu itemTitle paths}
- Returnerer stien til valgte filer i playlisten når et tilfældigt element i playlistens kontekstmenu bliver aktiveret. submenu og itemTitle bliver også returneret for at muliggøre entydig identifikation for scripts der lytter efter flere events. For at indsætte et element i menuen skal du bruge DCOP kaldet 'dcop amarok script addCustomMenuItem( submenu itemTitle )'. For at fjerne et element skal du bruge 'dcop amarok script removeCustomMenuItem( submenu itemTitle )'.
Bemærk: Dette blev tilføjet i amaroK 1.3 serien.
Afslutning af scripts
Før amaroK lukker, eller når en bruger stopper et script fra ScriptManageren, sender amaroK et SIGTERM signal til scriptets proces. Det signal kan opfanges hvis det er nødvendigt at "rydde op" efter scriptet, dvs. gemme data eller indstillinger.
Pakkehåndtering
amaroK's ScriptManager kan selv installere de scripts brugeren har downloaded fra Internettet. Et script skal blot pakkes som normale tarballs (.tar), og eventuelt komprimeres med bzip2 (.bz2). Vi anbefaler kraftigt at scripts bliver navngivet efter dette skema: mitscript.amarokscript.tar.bz2. Så kan brugeren nemt identificere et amaroK script. BEMÆRK: amaroK 1.3+ vil kun acceptere scripts, der er pakket med amarokscript-endelsen, så det er bedre at bruge den fra starten.
BEMÆRK: Med amaroK 1.3.4 understøtter README rich text format. Vi viser dette i en kaboutdialog. Hvis en fil ved navn COPYING eksisterer, bliver der føjet et faneblad, ved navn Licens til kaboutdialog, der viser indholdet af den fil. Fanebladet til Licens understøtter dog ikke rtf. Indholdet af tarball'en skal være organiseret således:
myscript/ README COPYING myscript.py (executable) somemodule.py foo.data ...
Filer og rettigheder
Selve scriptet (filen) skal have rettigheden +x (executable) sat - yderligere moduler bør ikke være eksekverbare. Du kan bruge flaget -p i tar for at bibeholde filernes rettigheder, når du pakker scriptet:
tar -cf mitscript.amarokscript.tar -p myscript
Bemærk at amaroK ikke vil være i stand til at installere scriptet hvis ikke rettighederne er sat ordentligt.
Distribution
Når pakken er lavet kan du uploade den til kde-apps.org, og tilføje et link til vores Wiki (Scripts). På kde-apps skal du bruge kategorien amaroK Scripts.