advanced.docbook

Amarok是一款在LINUX或其他类UNIX操作系统中运行的音频播放器软件。 经过两年开发后

<row>
<entry
>void enableRandomMode(bool w艂膮czony)</entry>
<entry
>W艂膮cza lub wy艂膮cza tryb losowy.</entry>
</row>

<row>
<entry
>void enableRepeatPlaylist(bool w艂膮czony)</entry>
<entry
>W艂膮cza lub wy艂膮cza tryb powtarzania listy.</entry>
</row>

<row>
<entry
>void enableRepeatTrack(bool w艂膮czony)</entry>
<entry
>W艂膮cza lub wy艂膮cza tryb powtarzania utworu.</entry>
</row>

<row>
<entry
>void mediaDeviceMount()</entry>
<entry
>Ustawia polecenie s艂u偶膮ce do montowania urz膮dzenia odtwarzaj膮cego.</entry>
</row>

<row>
<entry
>void mediaDeviceUmount()</entry>
<entry
>Ustawia polecenie s艂u偶膮ce do odmontowania urz膮dzenia odtwarzaj膮cego.</entry>
</row>

<row>
<entry
>void mute()</entry>
<entry
>Prze艂膮cza wyciszanie.</entry>
</row>

<row>
<entry
>void next()</entry>
<entry
>R贸wnoznaczne z naci艣ni臋ciem przycisku "Dalej".</entry>
</row>

<row>
<entry
>void pause()</entry>
<entry
>R贸wnoznaczne z naci艣ni臋ciem przycisku "Pauza".</entry>
</row>

<row>
<entry
>void play()</entry>
<entry
>R贸wnoznaczne z naci艣ni臋ciem przycisku "Odtwarzaj".</entry>
</row>

<row>
<entry
>void playPause()</entry>
<entry
>Prze艂膮cza pomi臋dzy odtwarzaniem a pauz膮 (wygodne dla u偶ytkownik贸w klawiatur mm). </entry>
</row>

<row>
<entry
>void prev()</entry>
<entry
>R贸wnoznaczne z naci艣ni臋ciem przycisku "Poprzedni".</entry>
</row>

<row>
<entry
>void queueForTransfer( KURL url )</entry>
<entry
>Kolejkuj plik przed przes艂aniem do urz膮dzenia odtwarzaj膮cego.</entry>
</row>

<row>
<entry
>void seek(int s)</entry>
<entry
>Wyszukaj w utworze wed艂ug pozycji w sekundach.</entry>
</row>

<row>
<entry
>void seekRelative(int s)</entry>
<entry
>Wyszukuje pozycj臋 wzgl臋dn膮 do bie偶膮cej pozycji utworu.</entry>
</row>

<row>
<entry
>void setEqualizer(int, int, int, int, int, int, int, int, int, int, int)</entry>
<entry
>Ustawia cz臋stotliwo艣ci equalizera. </entry>
</row>

<row>
<entry
>void setEqualizerEnabled( bool aktywny )</entry>
<entry
>Prze艂膮cza equalizer.</entry>
</row>

<row>
<entry
>void setEqualizerPreset( QString nazwa )</entry>
<entry
>Ustawia domy艣ln膮 konfiguracj臋 equalizera. </entry>
</row>

<row>
<entry
>void setLyricsByPath( QString url, QString tekst )</entry>
<entry
>Ustawia tekst utworu okre艣lonego przez 艣cie偶k臋.</entry>
</row>

<row>
<entry
>void setScore( int ocena )</entry>
<entry
>Ustawia ocen臋 aktualnie odtwarzanego utworu.</entry>
</row>

<row>
<entry
>void setScoreByPath( QString url, int wynik )</entry>
<entry
>Ustawia ocen臋 utworu okre艣lonego przez 艣cie偶k臋.</entry>
</row>

<row>
<entry
>void setVolume(int g艂o艣no艣膰)</entry>
<entry
>Ustawia g艂o艣no艣膰 w przedziale 0-100%.</entry>
</row>

<row>
<entry
>void showBrowser( QString przegl膮darka )</entry>
<entry
>Wy艣wietla przegl膮darki w oknie listy odtwarzania.</entry>
</row>

<row>
<entry
>void showOSD()</entry>
<entry
>Wy艣wietla OSD na ekranie.</entry>
</row>

<row>
<entry
>void stop()</entry>
<entry
>R贸wnoznaczne z naci艣ni臋ciem przycisku "Stop".</entry>
</row>

<row>
<entry
>void transferDeviceFiles()</entry>
<entry
>Transferuje pliki do urz膮dzenia odtwarzaj膮cego.</entry>
</row>

<row>
<entry
>void volumeDown()</entry>
<entry
>Zmniejsza g艂o艣no艣膰 o rozs膮dn膮 wielko艣膰.</entry>
</row>

<row>
<entry
>void volumeUp()</entry>
<entry
>Zwi臋ksza g艂o艣no艣膰 o rozs膮dn膮 wielko艣膰.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</sect2>

<sect2 id="dcop-playlist">
<title
>dcop amarok playlist</title>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry
>Funkcja DCOP</entry>
<entry
>Dzia艂anie</entry>
</row>
</thead>
<tbody>

<row>
<entry
>int getActiveIndex()</entry>
<entry
>Zwraca list臋 aktywnych utwor贸w. -1 je艣li ich brak.</entry>
</row>

<row>
<entry
>int getTotalTrackCount()</entry>
<entry
>Zwraca liczb臋 utwor贸w na li艣cie. 0 je艣li ich brak.</entry>
</row>

<row>
<entry
>QString saveCurrentPlaylist()</entry>
<entry
>Zapisuje bie偶膮c膮 list臋 do current.xml i zwraca 艣cie偶k臋 do pliku.</entry>
</row>

<row>
<entry
>void addMedia( KURL )</entry>
<entry
>Dodaje media d藕wi臋kowe okre艣lone przez URL.</entry>
</row>

<row>
<entry
>void addMediaList( KURL::List lista )</entry>
<entry
>Dodaje pewne media d藕wi臋kowe okre艣lone przez URL.</entry>
</row>

<row>
<entry
>void clearPlaylist()</entry>
<entry
>Oczyszcza list臋 odtwarzania.</entry>
</row>

<row>
<entry
>void playByIndex(int)</entry>
<entry
>Uruchamia odtwarzanie utworu wed艂ug okre艣lonego indeksu.</entry>
</row>

<row>
<entry
>void playMedia( KURL )</entry>
<entry
>Dodaje media d藕wi臋kowe okre艣lone przez URL.</entry>
</row>

<row>
<entry
>void popupMessage( QString)</entry>
<entry
>Wy艣wietla czasow膮 wiadomo艣膰 wyskakuj膮c膮.</entry>
</row>

<row>
<entry
>void removeCurrentTrack()</entry>
<entry
>Usuwa bie偶膮cy utw贸r z listy odtwarzania.</entry>
</row>

<row>
<entry
>void repopulate()</entry>
<entry
>Zape艂nia list臋 przypadkowymi utworami.</entry>
</row>

<row>
<entry
>void saveM3u( QString 艣cie偶ka, bool relatywne艢cie偶ki)</entry>
<entry
>Zapisuje bie偶膮c膮 list臋 jako m3u.</entry>
</row>

<row>
<entry
>void setStopAfterCurrent( bool )</entry>
<entry
>W艂膮cza i wy艂膮cza funkcj臋 "Zatrzymaj po bie偶膮cym utworze".</entry>
</row>

<row>
<entry
>void shortStatusMessage( QString)</entry>
<entry
>Wy艣wietla tymczasowy komunikat na pasku stanu.</entry>
</row>

<row>
<entry
>void shufflePlaylist()</entry>
<entry
>Tasuje list臋 odtwarzania.</entry>
</row>

<row>
<entry
>void togglePlaylist()</entry>
<entry
>W艂膮cza/wy艂膮cza okno listy odtwarzania.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</sect2>

<sect2 id="dcop-playlistbrowser">
<title
>dcop amarok playlistbrowser</title>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry
>Funkcja DCOP</entry>
<entry
>Dzia艂anie</entry>
</row>
</thead>
<tbody>

<row>
<entry
>void addPodcast( QString )</entry>
<entry
>Dodaje pozycj臋 podcast do przegl膮darki list.</entry>
</row>

<row>
<entry
>void scanPodcasts()</entry>
<entry
>Wyszukaje aktualizacje wszystkich podcast贸w.</entry>
</row>

<row>
<entry
>void addPlaylist( QString )</entry>
<entry
>Dodaje list臋 odtwarzania do przegl膮darki list.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</sect2>

<sect2 id="dcop-script">
<title
>dcop amarok script</title>


<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry
>Funkcja DCOP</entry>
<entry
>Dzia艂anie</entry>
</row>
</thead>
<tbody>

<row>
<entry
>bool runScript( QString nazwa)</entry>
<entry
>Uruchamia skrypt o danej nazwie. Zwraca warto艣膰 prawda, je艣li operacja si臋 powiedzie.</entry>
</row>

<row>
<entry
>bool stopScript( QString nazwa)</entry>
<entry
>Zatrzymuje skrypt o danej nazwie. Zwraca warto艣膰 prawda, je艣li operacja si臋 powiedzie.</entry>
</row>

<row>
<entry
>QStringList listRunningScripts()</entry>
<entry
>Zwraca list臋 aktualnie uruchomionych skrypt贸w.</entry>
</row>

<row>
<entry
>void addCustomMenuItem(QString podmenu, QString tytu艂Pozycji )</entry>
<entry
>W艂膮cza i ustala w艂asn膮 nazw臋 pozycji w menu.</entry>
</row>

<row>
<entry
>void removeCustomMenuItem(QString podmenu, QString tytu艂Pozycji )</entry>
<entry
>Usuwa w艂asn膮 pozycj臋 z menu.</entry>
</row>

<row>
<entry
>QString readConfig( QString klucz)</entry>
<entry
>Zwraca warto艣膰 konfiguracyjn膮 AmarokConfig z podanego klucza.</entry>
</row>

</tbody>
</tgroup>
</informaltable>


</sect2>

</sect1>

<sect1 id="cmd-line-options">
<title
>Opcje wiersza polece艅</title>

<para
>Amarok obs艂uguje standardowe funkcje wiersza polece艅 Qt oraz kde, posiada tak偶e opcje wykorzystywane tylko przez niego samego.</para>

<para
>Opcje Qt i kde:</para>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry
>Opcja</entry>
<entry
>Dzia艂anie</entry>
</row>
</thead>
<tbody>

<row>
<entry
>--help</entry>
<entry
>Wy艣wietla pomoc na temat opcji.</entry>
</row>

<row>
<entry
>--help-qt</entry>
<entry
>Wy艣wietla opcje w艂a艣ciwe QT.</entry>
</row>

<row>
<entry
>--help-kde</entry>
<entry
>Wy艣wietla opcje w艂a艣ciwe KDE.</entry>
</row>

<row>
<entry
>--help-all</entry>
<entry
>Wy艣wietla wszystkie opcje.</entry>
</row>

<row>
<entry
>--author</entry>
<entry
>Wy艣wietla informacje na temat autora.</entry>
</row>

<row>
<entry
>-v, --version</entry>
<entry
>Pokazuje informacje o wersji.</entry>
</row>

<row>
<entry
>--license</entry>
<entry
>Wy艣wietla informacje na temat licencji.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

<para
>Opcje Amarok:</para>

<note
><para
>Opcje &amarok-dopelniacz; s膮 zaprojektowane do korzystania z nich podczas dzia艂ania programu.</para
></note>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry
>Opcja</entry>
<entry
>Dzia艂anie</entry>
</row>
</thead>
<tbody>

<row>
<entry
>-r, --previous</entry>
<entry
>Przechodzi do poprzedniego utworu na li艣cie odtwarzania.</entry>
</row>

<row>
<entry
>-p, --play</entry>
<entry
>Rozpoczyna odtwarzanie bie偶膮cej listy odtwarzania.</entry>
</row>

<row>
<entry
>-s, --stop</entry>
<entry
>Zatrzymanie odtwarzania.</entry>
</row>

<row>
<entry
>--pause</entry>
<entry
>Pauzuje odtwarzanie.</entry>
</row>

<row>
<entry
>-f, --next</entry>
<entry
>Przechodzi do nast臋pnego utworu na li艣cie odtwarzania.</entry>
</row>

<row>
<entry
>-a, --append</entry>
<entry
>Do艂膮cza pliki/adresy URL do listy odtwarzania.</entry>
</row>

<row>
<entry
>-e, --enqueue</entry>
<entry
>Zobacz append, dost臋pny na potrzeby wstecznej kompatybilno艣ci</entry>
</row>

<row>
<entry
>--queue</entry>
<entry
>Kolejkuj pliki/adresu URL po aktualnie odtwarzanym utworze.</entry>
</row>

<row>
<entry
>-m, --toggle-playlist-window</entry>
<entry
>W艂膮cza/wy艂膮cza okno listy odtwarzania.</entry>
</row>

<row>
<entry
>--wizard</entry>
<entry
>Uruchamia asystenta pierwszego uruchamiania.</entry>
</row>

<row>
<entry
>--engine "name"</entry>
<entry
>Uruchamia program &amarok-mianownik; z silnikiem o nazwie...</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</sect1>


<sect1 id="script-writing">
<title
>Pisanie skrypt贸w</title>

<para
>Skrypty pozwalaj膮 na poszerzenie mo偶liwo艣ci &amarok-dopelniacz; bez zmiany g艂贸wnego kodu. Skrypty przypominaj膮 wtyczki, ale zamiast dedykowanej wtyczki API, wykorzystuj膮 one do komunikacji interfejs DCOP &amarok-dopelniacz;. Umo偶liwia to pisanie skrypt贸w w prawie ka偶dym j臋zyku programowania, jak np. Ruby, Python lub PHP. Ka偶dy mo偶e tworzy膰 skrypty, nie tylko w klasycznych j臋zykach skryptowych, ale r贸wnie偶 w j臋zykach programowania jak C++ lub C. Dodatkowo, &amarok-mianownik; mo偶e powiadamia膰 skrypty o specjalnych zdarzeniach i sprawia膰, 偶e b臋d膮 dzia艂a膰 w odpowiedni spos贸b. Ten system powiadamiania b臋dzie wyja艣niony w dalszej cz臋艣ci tej sekcji.</para>

<sect2 id="script-bindings">
<title
>Powi膮zania dla j臋zyk贸w skryptowych</title>

<para
>Mo偶liwe jest tworzenie prostych skrypt贸w, kt贸re nie wymagaj膮 interakcji z u偶ytkownikiem, mo偶na tak偶e tworzy膰 skrypty z przyjaznym interfejsem, kt贸re zachowuj膮 si臋 jak samodzielne programy. Przy programowaniu interfejsu mo偶e by膰 wykorzystane jedno lub wi臋cej powi膮za艅 dostarczonych przez KDE, np. RubyQt, biblioteka powi膮zania dla j臋zyka Ruby. Traci to jednak jak膮kolwiek warto艣膰, je艣li nie ka偶dy z u偶ytkownik贸w ma zainstalowane wszystkie dost臋pne powi膮zania. Je艣li zdecydujesz si臋 na u偶ycie powi膮zania, wybierz jedno z bardziej rozpowszechnionych (np. RubyQt lub PyQt).</para>

<para
>Aby otrzymywana by艂a informacja zwrotna, w sytuacji gdy jaki艣 skrypt nie dzia艂a z powodu brakuj膮cej zale偶no艣ci, musisz sprawdzi膰 w skrypcie czy modu艂, kt贸ry chcesz do艂膮czy膰 rzeczywi艣cie istnieje. Je艣li brak jest zale偶no艣ci, powiniene艣 wychwyci膰 b艂膮d i wy艣wietli膰 okno informacyjne za pomoc膮 programu "kdialog". Dzi臋ki temu u偶ytkownik dowie si臋, czemu jego skrypt nie dzia艂a.</para>

<para
>Ten przyk艂ad pokazuje jak wychwyci膰 brakuj膮c膮 zale偶no艣膰 w j臋zyku Ruby:</para>

<programlisting
>begin
       require 'Korundum'
rescue LoadError
       error = 'Korundum (powi膮zania KDE dla j臋zyka Ruby) z pakietu kdebindings v3.4 s膮 wymagane przez ten skrypt.'
       `kdialog --sorry '#{error}'`
       exit
end
</programlisting>

</sect2>

<sect2 id="script-templates">
<title
>Podstawowe informacje o szablonach</title>

<para
>&amarok-mianownik; udost臋pnia szablony skrypt贸w dla wielu j臋zyk贸w w katalogu <filename class="directory"
>scripts/templates/</filename
>. Mo偶esz u偶y膰 tych skrypt贸w jako podstawy Twoich w艂asnych skrypt贸w i poszerzy膰 je o po偶膮dane funkcje. Przekonasz si臋, 偶e tworzenie skrypt贸w jest teraz rzeczywi艣cie 艂atwe. Np. je艣li znasz nieco j臋zyk Python; stworzenie skryptu nie zajmie Ci wiele czasu.</para>

</sect2>

<sect2 id="script-controlling-amarok">
<title
>Zarz膮dzanie &amarok-narzednik; za pomoc膮 interfejsu DCOP</title>

<para
>Poprzez odwo艂ania do niekt贸rych funkcji DCOP, skrypty mog膮 zarz膮dza膰 programem Amarok. Najprostszym sposobem wywo艂ania funkcji DCOP jest u偶ycie linii polece艅 "dcop", kt贸ra jest cz臋艣ci膮 ka偶dej dystrybucji KDE.</para>

<para
>Oto przyk艂ad jak zwi臋kszy膰 g艂o艣no艣膰:</para>

<programlisting
>dcop amarok player volumeUp</programlisting>

<para
>Wi臋kszo艣膰 j臋zyk贸w skryptowych zezwala na wykonywanie zewn臋trznych program贸w, z funkcj膮 typu exec(). W ten spos贸b narz臋dzie "dcop" mo偶e by膰 艂atwo wywo艂ane. Oto prosty przyk艂ad z j臋zyka Python:</para>

<programlisting
>import os
 os.system("dcop amarok player volumeDown")
</programlisting>

</sect2>

<sect2 id="script-notifications">
<title
>Powiadomienia</title>

<para
>&amarok-mianownik; wysy艂a powiadomienia do wszystkich uruchomionych skrypt贸w poprzez wprowadzenie napis贸w do kana艂u stdin. Skrypt powinien zatem nieustannie monitorowa膰 stdin i odpowiednio reagowa膰 na ka偶de z mo偶liwych zdarze艅. Skrypty mog膮 r贸wnie偶 zignorowa膰 ka偶de, nieistotne dla nich zdarzenie.</para>

<para
>&amarok-mianownik; wysy艂a nast臋puj膮ce powiadomienia:</para>

<programlisting
><cmdsynopsis
><command
>configure</command
></cmdsynopsis>
Nakazuje skryptowi wy艣wietlenie okna konfiguracyjnego. Skrypt musi obs艂ugiwa膰 
samodzielnie przechowywanie i wczytywanie opcji konfiguracyjnych. Kiedy skrypt 
jest uruchomiony, amaroK przenosi jego katalog roboczy do katalogu w kt贸rym 
powinny by膰 przechowane wszystkie dane.
</programlisting>

<programlisting
><cmdsynopsis
><command
>engineStateChange:</command
><arg
>empty|idle|paused|playing</arg
></cmdsynopsis>
Sygnalizuje zmian臋 stanu silnika.
</programlisting>

<programlisting
><cmdsynopsis
><command
>trackChange</command
></cmdsynopsis>
Sygnalizuje rozpocz臋cie nowego utworu. Skrypt mo偶e wykorzysta膰 funkcje DCOP do
zapyta艅 o dalsze informacje o utworze, np o metadane i o d艂ugo艣膰.
</programlisting>

<programlisting
><cmdsynopsis
><command
>volumeChange</command
><arg
>newVolume</arg
></cmdsynopsis>
Sygnalizuje zmian臋 poziomu g艂o艣no艣ci. Poziom g艂o艣no艣ci jest liczb膮 ca艂kowit膮 z
 zakresu 0-100.
</programlisting>

<programlisting
><cmdsynopsis
><command
>customMenuClicked:</command
><arg
>submenu itemTitle paths</arg
></cmdsynopsis>
Zwraca 艣cie偶ki do wybranych plik贸w listy odtwarzania, po klikni臋ciu w menu 
kontekstowym listy odtwarzania u偶ytkownika. W celach identyfikacyjnych zwracane s膮 r贸wnie偶 podmenu i tytu艂, 
na wypadek gdyby skrypt oczekiwa艂 licznych powiadomie艅. 
Aby umie艣ci膰 element w menu kontekstowym, u偶yj funkcji DCOP 
'dcop amarok script addCustomMenuItem( podmenu tytu艂Pozycji )'. Aby usun膮膰 element z 
menu kontekstowego, u偶yj funkcji DCOP 
'dcop amarok script removeCustomMenuItem( podmenu tytu艂Pozycji )'.
</programlisting>

</sect2>

<sect2 id="script-termination">
<title
>Zako艅czenie skryptu</title>

<para
>Zanim &amarok-mianownik; zostanie zamkni臋ty lub kiedy u偶ytkownik zatrzyma skrypt w mened偶erze skrypt贸w, &amarok-mianownik; wysy艂a do skryptu sygna艂 SIGTERM. Sygna艂 mo偶e by膰 zatrzymany w celu wykonania prac porz膮dkowych, typu zapisanie danych czy opcji konfiguracyjnych.</para>

</sect2>

<sect2 id="script-packaging">
<title
>Pakowanie</title>

<para
>Mened偶er skrypt贸w &amarok-dopelniacz; potrafi instalowa膰 paczki skrypt贸w, kt贸re u偶ytkownik pobra艂 z serwera WWW. Paczki to zwyk艂e tarball (.tar), opcjonalnie skompresowane za pomoc膮 bzip2 (.bz2). Gor膮co zach臋camy do u偶ywania nazw takich jak myscript.amarokscript.tar.bz2, tak aby u偶ytkownik zidentyfikowa艂 paczk臋 jako skrypt programu Amarok.</para>

<note
><para
>&amarok-mianownik; 1.3 zaakceptuje jedynie paczki z rozszerzeniem amarokscript, wi臋c lepiej u偶ywa膰 tego rozszerzenia ju偶 teraz.</para
></note>

<para
>Zawarto艣膰 tarball musi by膰 zorganizowana w spos贸b nast臋puj膮cy:</para>

<programlisting
>myscript/
   README
   mojskrypt.py (program wykonywalny)
   modul.py
   foo.data
   ...
</programlisting>

</sect2>

<sect2 id="script-permissions">
<title
>Zezwolenia pliku</title>

<para
>G艂贸wny skrypt musi posiada膰 zestaw zezwole艅 wykonawczych (+x), podczas gdy dodatkowe modu艂y wczytywane przez skrypt nie powinny by膰 wykonawcze. Aby chroni膰 zezwolenia pliku w tarball, powiniene艣 u偶y膰 tar z -p flag:</para>

<programlisting
>tar -cf myscript.amarokscript.tar -p myscript</programlisting>

<note
><para
>&amarok-mianownik; nie b臋dzie w stanie zainstalowa膰 skryptu, je艣li zezwolenia nie b臋d膮 poprawnie ustawione.</para
></note>

</sect2>

<sect2 id="script-distributing">
<title
>Dystrybucja</title>

<para
>Kiedy paczka jest sko艅czona, mo偶esz wys艂a膰 j膮 do <ulink url="http://www.kde-apps.org"
>www.kde-apps.org</ulink
>i umie艣ci膰 odno艣nik w &amarok-narzednik; <ulink url="http://amarok.kde.org/amarokwiki/index.php/Scripts"
>Wiki Scripts Page</ulink
>. Przy wpisach kde-apps powiniene艣 u偶y膰 kategorii <ulink url="http://kde-apps.org/index.php?xcontentmode=56"
>&amarok; Scripts</ulink
>.</para>

</sect2>

</sect1>


</chapter>