Skrive scripter

Det er muligt at skrive enkle scripter som ikke kræver indblanding af brugeren, og det er også muligt at oprette scripter med bekvemme grafiske grænseflader som fungerer som små program i sig selv. For programmering af den grafiske grænseflade kan en af de mange bindinger som KDE sørger for bruges, for eksempel RubyQt, en binding til Qt-biblioteket for Ruby. Det er dog værd at notere at ikke alle brugere har installeret alle tilgængelige bindinger. Hvis du bestemmer dig for at bruge en binding, så forsøg at bruge en af dem som er relativt udbredte (f.eks. RubyQt eller PyQt).

For at give nogen tilbagemelding når et script mislykkes at køre på grund af en afhængighed som mangler, skal du kontrollere i scriptet om modulet du vil inkludere virkelig findes. Hvis afhængigheder mangler, bør du fange fejlen og vise en informationsdialog med kommandolinjeværktøjet "kdialog", så brugeren får rede på hvorfor scriptet mislykkes at køre.

Følgende eksempel viser hvordan en afhængighed som mangler kan fanges i Ruby:

begin
       require 'Korundum'
rescue LoadError
       error = 'Korundum (KDE-bindinger for Ruby) fra kdebindings v3.4 kræves af dette script.'
       `kdialog --sorry '#{error}'`
       exit
end

amaroK sørger for skabelonscripter for flere sprog i mappen scripts/templates/. Du kan bruge disse scripter som en basis for dine egne, og udvide dem med funktioner du behøver. Du vil bemærke at det i virkeligheden er ganske ligetil at skrive scripter. Hvis du for eksempel véd en del om hvordan man programmerer i Python, tager det ikke lang tid at oprette dit eget script.

Scripter kan styre amaroK ved at kalde visse af dets DCOP-funktioner. Den enkleste måde at udføre en DCOP-funktion er ved at bruge kommandolinjeværktøjet "dcop", som indgår i alle distributioner af KDE.

Her er et eksempel på hvordan hovedlydstyrken øges:

dcop amarok player volumeUp

De fleste scriptsprog tillader at eksterne programmer køres, med en funktion såsom exec(). På den måde kan værktøjet "dcop" nemt kaldes. Her er et enkelt eksempel i Python:

import os
 os.system("dcop amarok player volumeDown")

amaroK sender underretninger til alle scripter som kører ved at skrive strenge til deres standardindtastning. Scripterne bør derfor hele tiden overvåge standardindtastningen og reagere på passende måde på hver af de mulige begivenheder. Scripter kan også vælge at ignorere alle begivenheder de ikke har nogen nytte af.

Følgende underretninger sendes af amaroK:

configure
Fortæller scriptet at dets indstillingsdialog skal vises. Scriptet
skal håndtere opbevaring og indlæsning af indstillingtilvalg selv.
Når et script startes, indstiller amaroK dets arbejdsmappe til mappen
hvor al data skal opbevares.

engineStateChange: [empty|idle|paused|playing]
Signalerer en ændring af grænsefladens tilstand.

trackChange
Signalerer start af et nyt spor. Scriptet kan derefter bruge DCOP-funktioner
til at spørge efter yderligere information om sporet, f.eks. metadata og længde.

volumeChange [ny-volym]
Signalerer en ændring af hovedlydstyrken. Lydstyrken er et heltal i
intervallet 0-100.

customMenuClicked: [undermenu objektnavn søgestier]
Returnerer søgestier til markerede filer i spillelisten når det egne punkt
i spillelistens sammenhængsafhængige menu klikkes. Undermenuen og punktets navn returneres
også til identifikationsformål i tilfældet hvor et script lytter til flere underretninger.
Brug DCOP-kaldet 'dcop amarok script addCustomMenuItem( undermenu punktnavn )'
til at indsætte et punkt i den sammenhængsafhængige menu. Brug
DCOP-kaldet 'dcop amarok script removeCustomMenuItem( undermenu punktnavn )'
til at fjerne et punkt fra den sammenhængsafhængige menu.

Inden amaroK afsluttes, eller når brugeren stopper et script i scripthåndteringen, sender amaroK signalet SIGTERM til scriptet. Signalet kan indfanges for at udføre oprensningsarbejde, såsom at gemme data eller indstillinger.

Scripthåndteringen i amaroK kan installere scriptpakker som brugeren har hentet fra internettet. Pakker er blot normale arkiver (.tar), valgfrit komprimerede med bzip2 (.bz2). Vi anbefaler stærkt at bruge et filnavn såsom mit-script.amarokscript.tar.bz2, så brugeren let kan identificere pakken som et script for amaroK.

Filens indhold skal være organiseret på følgende vis:

mit-script/
   README
   mit-script.py (kørbar fil)
   en-modul.py
   fil.data
   ...

Hovedscriptet skal have kørerettigheder (+x) indstillede,mens yderligere moduler som scriptet indlæser ikke skal have kørerettigheder. For at bevare filrettigheder i arkivet, skal du bruge tar med flaget -p.

tar -cf mitt-script.amarokscript.tar -p mit-script

Når pakken er klar, kan du overføre den til www.kde-apps.org og tilføje linket på amaroKs Wiki scriptside. For indgangen i kde-apps skal du bruge kategorien amaroK Scripter.