<chapter id="advanced-features">
<title
>Características Avançadas do Amarok</title>
<sect1 id="keybd-shortcuts">
<title
>Atalhos de teclado</title>
<para
>O &amarok; usa os atalhos do teclado, como a maioria das outras aplicações; abaixo, encontra-se uma listagem desses atalhos e das suas ações respectivas. Os atalhos globais podem ser configurados se clicar com o &RMB; na janela do Leitor e se selecionar a opção <guimenuitem
>Configurar os Atalhos Globais...</guimenuitem
>. Os atalhos do &amarok; podem ser configurados se clicar com o &RMB; na janela do Leitor e selecionar a opção <guimenuitem
>Configurar os Atalhos...</guimenuitem
></para>
<tip
><para
>Você poderá atribuir teclas multimídia para funcionarem como atalhos do &amarok;, tornando o seu teclado um centro de controle do &amarok;.</para
></tip>
<para
>Os atalhos globais são:</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Combinação de Teclas</entry>
<entry
>Ação</entry>
</row>
</thead>
<tbody>
<row>
<entry
><keycombo
><keycap
>Win</keycap
><keycap
>X</keycap
></keycombo
></entry>
<entry
>Reproduzir</entry>
</row>
<row>
<entry
><keycombo
><keycap
>Win</keycap
><keycap
>C</keycap
></keycombo
></entry>
<entry
>Pausar</entry>
</row>
<row>
<entry
><keycombo
><keycap
>Win</keycap
><keycap
>V</keycap
></keycombo
></entry>
<entry
>Parar</entry>
</row>
<row>
<entry
><keycombo
><keycap
>Win</keycap
><keycap
>B</keycap
></keycombo
></entry>
<entry
>Próxima Faixa</entry>
</row>
<row>
<entry
><keycombo
><keycap
>Win</keycap
><keycap
>Z</keycap
></keycombo
></entry>
<entry
>Faixa Anterior</entry>
</row>
<row>
<entry
><keycombo
><keycap
>Win</keycap
><keycap
>KP_Add</keycap
></keycombo
></entry>
<entry
>Aumentar o Volume</entry>
</row>
<row>
<entry
><keycombo
><keycap
>Win</keycap
><keycap
>KP_Subtract</keycap
></keycombo
></entry>
<entry
>Diminuir o Volume</entry>
</row>
<row>
<entry
><keycombo
><keycap
>Win</keycap
>&Shift;<keycap
>KP_Add</keycap
></keycombo
></entry>
<entry
>Avançar</entry>
</row>
<row>
<entry
><keycombo
><keycap
>Win</keycap
>&Shift;<keycap
>KP_Subtract</keycap
></keycombo
></entry>
<entry
>Procurar regressivamente</entry>
</row>
<row>
<entry
><keycombo
><keycap
>Win</keycap
><keycap
>A</keycap
></keycombo
></entry>
<entry
>Adicionar Mídia</entry>
</row>
<row>
<entry
><keycombo
><keycap
>Win</keycap
><keycap
>P</keycap
></keycombo
></entry>
<entry
>Comutar a Lista</entry>
</row>
<row>
<entry
><keycombo
><keycap
>Win</keycap
><keycap
>O</keycap
></keycombo
></entry>
<entry
>Mostrar o OSD</entry>
</row>
<row>
<entry
><keycombo
><keycap
>Win</keycap
><keycap
>M</keycap
></keycombo
></entry>
<entry
>Silenciar Volume</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para
>Os atalhos do &amarok; são:</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Combinação de Teclas</entry>
<entry
>Ação</entry>
</row>
</thead>
<tbody>
<row>
<entry
><keycombo
>&Ctrl;<keycap
>C</keycap
></keycombo
></entry>
<entry
>Copiar</entry>
</row>
<row>
<entry
><keycombo
>&Ctrl;<keycap
>KP_Enter</keycap
></keycombo
></entry>
<entry
>Ir para a Atual</entry>
</row>
<row>
<entry
><keycombo
>&Ctrl;<keycap
>D</keycap
></keycombo
></entry>
<entry
>Colocar na Fila as Faixas Selecionadas</entry>
</row>
<row>
<entry
><keycombo
>&Ctrl;<keycap
>Q</keycap
></keycombo
></entry>
<entry
>Sair</entry>
</row>
<row>
<entry
><keycombo
>&Ctrl;&Shift;<keycap
>Z</keycap
></keycombo
></entry>
<entry
>Refazer</entry>
</row>
<row>
<entry
><keycombo
>&Ctrl;<keycap
>S</keycap
></keycombo
></entry>
<entry
>Salvar a Lista de Reprodução</entry>
</row>
<row>
<entry
><keycombo
>&Ctrl;<keycap
>A</keycap
></keycombo
></entry>
<entry
>Selecionar Tudo</entry>
</row>
<row>
<entry
><keycombo
>&Ctrl;<keycap
>M</keycap
></keycombo
></entry>
<entry
>Mostrar o Menu</entry>
</row>
<row>
<entry
><keycombo
>&Ctrl;<keycap
>H</keycap
></keycombo
></entry>
<entry
>Embaralhar</entry>
</row>
<row>
<entry
><keycombo
>&Ctrl;<keycap
>Z</keycap
></keycombo
></entry>
<entry
>Desfazer</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para
>Os atalhos do Navegador na Lista de Reprodução são:</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Combinação de Teclas</entry>
<entry
>Ação</entry>
</row>
</thead>
<tbody>
<row>
<entry
><keycap
>Espaço</keycap
></entry>
<entry
>Carregar Listas</entry>
</row>
<row>
<entry
><keycap
>F2</keycap
></entry>
<entry
>Renomear a Lista</entry>
</row>
<row>
<entry
>&Backspace;</entry>
<entry
>Remover a Lista</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect1>
<sect1 id="the-dcop-interface">
<title
>A Interface DCOP</title>
<para
>A interface de DCOP do Amarok oferece-lhe uma forma simples de controlar o Amarok com os seus próprios programas personalizados.</para>
<para
>A interface de DCOP do Amarok tem várias funções genéricas que poderão ser encontradas noutras aplicações do KDE. Esta seção está dividida em seis tabelas e pretende descrever as funções do DCOP para a coleção, o navegador de contexto, o leitor, a lista, o navegador da lista para os programas. Um exemplo da função de DCOP <quote
>pause</quote
> seria semelhante ao seguinte:</para>
<para
><prompt
>%</prompt
>dcop amarok player pause</para>
<sect2 id="dcop-collection">
<title
>dcop amarok collection</title>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Chamada DCOP</entry>
<entry
>Ação</entry>
</row>
</thead>
<tbody>
<row>
<entry
>int totalAlbums()</entry>
<entry
>Devolve o número total de álbuns na sua coleção.</entry>
</row>
<row>
<entry
>int totalArtists()</entry>
<entry
>Devolve o número total de artistas na sua coleção.</entry>
</row>
<row>
<entry
>int totalCompilations()</entry>
<entry
>Devolve o número total de compilações na sua coleção.</entry>
</row>
<row>
<entry
>int totalGenres()</entry>
<entry
>Devolve o número total de gêneros musicais na sua coleção.</entry>
</row>
<row>
<entry
>int totalTracks()</entry>
<entry
>Devolve o número total de faixas na sua coleção.</entry>
</row>
<row>
<entry
>QString query( QString sql)</entry>
<entry
>Executa uma pesquisa de SQL na base de dados.</entry>
</row>
<row>
<entry
>QStringList similarArtists( int artistas )</entry>
<entry
>Devolve os artistas semelhantes às faixas atuais, limitando a quantidade a 'artistas'.</entry>
</row>
<row>
<entry
>void migrateFile( QString urlAntigo, QString urlNovo )</entry>
<entry
>Move um arquivo na coleção, mantendo as estatísticas intactas.</entry>
</row>
<row>
<entry
>void scanCollection()</entry>
<entry
>Pesquisa a coleção.</entry>
</row>
<row>
<entry
>void scanCollectionChanges()</entry>
<entry
>Pesquisa a coleção apenas à procura de alterações.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
<sect2 id="dcop-context">
<title
>dcop amarok contextbrowser</title>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Chamada DCOP</entry>
<entry
>Ação</entry>
</row>
</thead>
<tbody>
<row>
<entry
>void showCurrentTrack()</entry>
<entry
>Mostra a faixa atual no navegador de contexto.</entry>
</row>
<row>
<entry
>void showLyrics()</entry>
<entry
>Mostra a página das letras no navegador de contexto.</entry>
</row>
<row>
<entry
>void showWiki()</entry>
<entry
>Mostra a página do Wikipedia no navegador de contexto.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
<sect2 id="dcop-player">
<title
>dcop amarok player</title>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Chamada DCOP</entry>
<entry
>Ação</entry>
</row>
</thead>
<tbody>
<row>
<entry
>bool dynamicModeStatus()</entry>
<entry
>Devolve o estado do modo dinâmico.</entry>
</row>
<row>
<entry
>bool equalizerEnabled()</entry>
<entry
>Devolve o estado do equalizador.</entry>
</row>
<row>
<entry
>bool isPlaying()</entry>
<entry
>Devolve 'true' se algo estiver sendo tocado no momento.</entry>
</row>
<row>
<entry
>bool randomModeStatus()</entry>
<entry
>Devolve o estado do modo aleatório.</entry>
</row>
<row>
<entry
>bool repeatPlaylistStatus()</entry>
<entry
>Devolve o estado de repetição da lista.</entry>
</row>
<row>
<entry
>bool repeatTrackStatus()</entry>
<entry
>Devolve o estado de repetição da faixa.</entry>
</row>
<row>
<entry
>int getVolume()</entry>
<entry
>Devolve o volume num intervalo de 0-100%.</entry>
</row>
<row>
<entry
>int sampleRate()</entry>
<entry
>Devolve a taxa de amostragem da faixa atualmente em reprodução.</entry>
</row>
<row>
<entry
>int score()</entry>
<entry
>Devolve a pontuação da faixa atual.</entry>
</row>
<row>
<entry
>int status()</entry>
<entry
>Devolve o estado de reprodução: 0 - parado, 1 - pausa, 2 - em reprodução.</entry>
</row>
<row>
<entry
>int trackCurrentTime()</entry>
<entry
>Devolve a posição de reprodução atual em segundos.</entry>
</row>
<row>
<entry
>int trackPlayCounter()</entry>
<entry
>Devolve o contador de reprodução da música atual.</entry>
</row>
<row>
<entry
>int trackTotalTime()</entry>
<entry
>Devolve o tamanho da faixa em segundos.</entry>
</row>
<row>
<entry
>QString album()</entry>
<entry
>Devolve o álbum da música que está tocando no momento.</entry>
</row>
<row>
<entry
>QString artist()</entry>
<entry
>Devolve o artista da faixa atual.</entry>
</row>
<row>
<entry
>QString bitrate()</entry>
<entry
>Devolve a taxa de amostragem em bits da faixa atual (XX kbps).</entry>
</row>
<row>
<entry
>QString comment()</entry>
<entry
>Devolve o comentário da música que está tocando no momento.</entry>
</row>
<row>
<entry
>QString coverImage()</entry>
<entry
>Devolve o URL codificado da imagem de capa da faixa atual. </entry>
</row>
<row>
<entry
>QString currentTime()</entry>
<entry
>Devolve a posição ([h:]mm:ss) da música que está tocando no momento.</entry>
</row>
<row>
<entry
>QString encodedURL()</entry>
<entry
>Devolve o URL codificado da faixa atual.</entry>
</row>
<row>
<entry
>QString engine()</entry>
<entry
>Devolve o motor de áudio atual.</entry>
</row>
<row>
<entry
>QString genre()</entry>
<entry
>Devolve o gênero da música que está tocando no momento.</entry>
</row>
<row>
<entry
>QString lyrics()</entry>
<entry
>Devolve as letras da faixa atual.</entry>
</row>
<row>
<entry
>QString lyricsByPath( QString local )</entry>
<entry
>Devolve as letra de uma faixa pela sua localização.</entry>
</row>
<row>
<entry
>QString nowPlaying()</entry>
<entry
>O título da faixa atualmente em reprodução.</entry>
</row>
<row>
<entry
>QString path()</entry>
<entry
>Devolve o local não-codificado da faixa atual.</entry>
</row>
<row>
<entry
>QString setContextStyle( QString )</entry>
<entry
>Define o estilo de CSS para o navegador de contexto.</entry>
</row>
<row>
<entry
>QString title()</entry>
<entry
>Devolve o título da faixa atual.</entry>
</row>
<row>
<entry
>QString totalTime()</entry>
<entry
>Devolve o tamanho total da música em reprodução (no formato [h:]mm:ss).</entry>
</row>
<row>
<entry
>QString track()</entry>
<entry
>Devolve o número da faixa.</entry>
</row>
<row>
<entry
>QString type()</entry>
<entry
>Devolve o tipo de arquivo.</entry>
</row>
<row>
<entry
>QString year()</entry>
<entry
>Devolve o ano da música que está sendo tocada no momento.</entry>
</row>
<row>
<entry
>void configEqualizer()</entry>
<entry
>Ativa ou desativa a janela de configuração do equalizador.</entry>
</row>
<row>
<entry
>void enableDynamicMode(bool ativar)</entry>
<entry
>Ativa ou desativa o Modo Dinâmico.</entry>
</row>
<row>
<entry
>void enableOSD(bool ativar)</entry>
<entry
>Ativa ou desativa a visualização OSD.</entry>
</row>
<row>
<entry
>void enableRandomMode(bool ativar)</entry>
<entry
>Ativa ou desativa o Modo Aleatório.</entry>
</row>
<row>
<entry
>void enableRepeatPlaylist(bool ativar)</entry>
<entry
>Ativa ou desativa a Repetição da Lista.</entry>
</row>
<row>
<entry
>void enableRepeatTrack(bool ativar)</entry>
<entry
>Ativa ou desativa a Repetição da Faixa.</entry>
</row>
<row>
<entry
>void mediaDeviceMount()</entry>
<entry
>Muda o comando usado para montar o dispositivo multimídia.</entry>
</row>
<row>
<entry
>void mediaDeviceUmount()</entry>
<entry
>Muda o comando usado para desmontar o dispositivo multimídia.</entry>
</row>
<row>
<entry
>void mute()</entry>
<entry
>Alterna o som entre ativo e em silêncio.</entry>
</row>
<row>
<entry
>void next()</entry>
<entry
>Equivalente a clicar no botão "Próximo".</entry>
</row>
<row>
<entry
>void pause()</entry>
<entry
>Equivalente a clicar no botão "Pausa".</entry>
</row>
<row>
<entry
>void play()</entry>
<entry
>Equivalente a clicar no botão "Tocar".</entry>
</row>
<row>
<entry
>void playPause()</entry>
<entry
>Alterna entre o estado de reprodução/pausa (bom para teclados multimídia) </entry>
</row>
<row>
<entry
>void prev()</entry>
<entry
>Equivalente a clicar no botão "Anterior".</entry>
</row>
<row>
<entry
>void queueForTransfer( KURL url )</entry>
<entry
>Coloca o arquivo na fila para ser transferido para o Dispositivo Multimídia.</entry>
</row>
<row>
<entry
>void seek(int s)</entry>
<entry
>Coloca a faixa na posição absoluta indicada em segundos.</entry>
</row>
<row>
<entry
>void seekRelative(int s)</entry>
<entry
>Coloca a faixa na posição relativa à atual em segundos.</entry>
</row>
<row>
<entry
>void setEqualizer(int, int, int, int, int, int, int, int, int, int, int)</entry>
<entry
>Configura as bandas do equalizador </entry>
</row>
<row>
<entry
>void setEqualizerEnabled( bool ativo )</entry>
<entry
>Comuta o equalizador.</entry>
</row>
<row>
<entry
>void setEqualizerPreset( QString nome )</entry>
<entry
>Configura as predefinições do equalizador </entry>
</row>
<row>
<entry
>void setLyricsByPath( QString url, QString letras )</entry>
<entry
>Atribui as letras de uma faixa pelo seu local.</entry>
</row>
<row>
<entry
>void setScore( int pontos )</entry>
<entry
>Configura a pontuação da faixa atual.</entry>
</row>
<row>
<entry
>void setScoreByPath( QString url, int pontos )</entry>
<entry
>Configura a pontuação de uma faixa pelo seu local.</entry>
</row>
<row>
<entry
>void setVolume(int volume)</entry>
<entry
>Configura o volume num intervalo de 0-100%.</entry>
</row>
<row>
<entry
>void showBrowser( QString navegador )</entry>
<entry
>Mostra os navegadores na janela da lista de reprodução</entry>
</row>
<row>
<entry
>void showOSD()</entry>
<entry
>Mostra a visualização OSD na tela.</entry>
</row>
<row>
<entry
>void stop()</entry>
<entry
>Equivalente a clicar no botão "Parar".</entry>
</row>
<row>
<entry
>void transferDeviceFiles()</entry>
<entry
>Transfere os arquivos para o dispositivo multimídia.</entry>
</row>
<row>
<entry
>void volumeDown()</entry>
<entry
>Diminui o volume de forma razoável.</entry>
</row>
<row>
<entry
>void volumeUp()</entry>
<entry
>Aumenta o volume de forma razoável.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
<sect2 id="dcop-playlist">
<title
>dcop amarok playlist</title>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Chamada DCOP</entry>
<entry
>Ação</entry>
</row>
</thead>
<tbody>
<row>
<entry
>int getActiveIndex()</entry>
<entry
>Devolve o índice da faixa atual ou -1 se não existir.</entry>
</row>
<row>
<entry
>int getTotalTrackCount()</entry>
<entry
>Devolve o número de faixas na lista de reprodução. 0 se não existirem faixas.</entry>
</row>
<row>
<entry
>QString saveCurrentPlaylist()</entry>
<entry
>Salva a lista atual em 'current.xml' e devolve o seu local.</entry>
</row>
<row>
<entry
>void addMedia( KURL )</entry>
<entry
>Adiciona conteúdos multimídia com base no seu URL.</entry>
</row>
<row>
<entry
>void addMediaList( KURL::List )</entry>
<entry
>Adicionas alguns conteúdos multimídia com base nos seus URLs.</entry>
</row>
<row>
<entry
>void clearPlaylist()</entry>
<entry
>Limpa a lista de reprodução.</entry>
</row>
<row>
<entry
>void playByIndex(int)</entry>
<entry
>Começa a tocar a faixa correspondente ao índice indicado.</entry>
</row>
<row>
<entry
>void playMedia( KURL )</entry>
<entry
>Adiciona conteúdos multimídia com base no seu URL.</entry>
</row>
<row>
<entry
>void popupMessage( QString)</entry>
<entry
>Mostra uma mensagem temporária.</entry>
</row>
<row>
<entry
>void removeCurrentTrack()</entry>
<entry
>Remove o item da faixa atual da lista de reprodução.</entry>
</row>
<row>
<entry
>void repopulate()</entry>
<entry
>Volta a preencher a lista de reprodução com faixas aleatórias.</entry>
</row>
<row>
<entry
>void saveM3u( QString local, bool locaisRelativos)</entry>
<entry
>Salva a lista de reprodução atual como M3U.</entry>
</row>
<row>
<entry
>void setStopAfterCurrent( bool )</entry>
<entry
>Ativa/desativa a funcionalidade "Parar Após a Faixa Atual".</entry>
</row>
<row>
<entry
>void shortStatusMessage( QString)</entry>
<entry
>Mostra uma mensagem temporária na barra de estado.</entry>
</row>
<row>
<entry
>void shufflePlaylist()</entry>
<entry
>Embaralha a lista de reprodução.</entry>
</row>
<row>
<entry
>void togglePlaylist()</entry>
<entry
>Ativa ou desativa a janela da lista de reprodução.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
<sect2 id="dcop-playlistbrowser">
<title
>dcop amarok playlistbrowser</title>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Chamada DCOP</entry>
<entry
>Ação</entry>
</row>
</thead>
<tbody>
<row>
<entry
>void addPodcast( QString )</entry>
<entry
>Adiciona um item de Podcast ao navegador de contexto.</entry>
</row>
<row>
<entry
>void scanPodcasts()</entry>
<entry
>Procura todas as atualizações de Podcast's.</entry>
</row>
<row>
<entry
>void addPlaylist( QString )</entry>
<entry
>Adiciona uma lista de reprodução ao navegador da lista.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
<sect2 id="dcop-script">
<title
>dcop amarok script</title>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Chamada DCOP</entry>
<entry
>Ação</entry>
</row>
</thead>
<tbody>
<row>
<entry
>bool runScript( QString nome )</entry>
<entry
>Inicia o programa com o nome indicado. Devolve 'true' em caso de sucesso.</entry>
</row>
<row>
<entry
>bool stopScript( QString nome )</entry>
<entry
>Pára o programa com o nome indicado. Devolve 'true' em caso de sucesso.</entry>
</row>
<row>
<entry
>QStringList listRunningScripts()</entry>
<entry
>Devolve uma lista com todos os programas atualmente em execução.</entry>
</row>
<row>
<entry
>void addCustomMenuItem(QString submenu, QString tituloItem )</entry>
<entry
>Ativa e atribui um título ao item de menu personalizado.</entry>
</row>
<row>
<entry
>void removeCustomMenuItem(QString submenu, QString tituloItem )</entry>
<entry
>Remove o item de menu personalizado.</entry>
</row>
<row>
<entry
>QString readConfig( QString chave )</entry>
<entry
>Devolve um valor de item do AmarokConfig com base na chave indicada.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
</sect1>
<sect1 id="cmd-line-options">
<title
>Opções de Linha de Comando</title>
<para
>O Amarok suporta a utilização das opções normais da linha de comando para o Qt e o &kde;. O Amarok tem também as suas opções específicas da aplicação.</para>
<para
>As opções do Qt e kde:</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Opção</entry>
<entry
>Ação</entry>
</row>
</thead>
<tbody>
<row>
<entry
>--help</entry>
<entry
>Mostra a ajuda sobre as opções.</entry>
</row>
<row>
<entry
>--help-qt</entry>
<entry
>Mostra as opções específicas do Qt.</entry>
</row>
<row>
<entry
>--help-kde</entry>
<entry
>Mostra opções específicas do KDE.</entry>
</row>
<row>
<entry
>--help-all</entry>
<entry
>Mostra todas as opções.</entry>
</row>
<row>
<entry
>--author</entry>
<entry
>Mostra informações sobre o autor.</entry>
</row>
<row>
<entry
>-v, --version</entry>
<entry
>Mostra a versão.</entry>
</row>
<row>
<entry
>--license</entry>
<entry
>Mostra informações sobre a licença.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para
>As opções do Amarok:</para>
<note
><para
>As opções do &amarok; foram concebidas para serem utilizadas enquanto o &amarok; está rodando.</para
></note>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Opção</entry>
<entry
>Ação</entry>
</row>
</thead>
<tbody>
<row>
<entry
>-r, --previous</entry>
<entry
>Passa à faixa anterior na lista de reprodução.</entry>
</row>
<row>
<entry
>-p, --play</entry>
<entry
>Começa a tocar a lista de músicas atual.</entry>
</row>
<row>
<entry
>-s, --stop</entry>
<entry
>Interrompe a reprodução.</entry>
</row>
<row>
<entry
>--pause</entry>
<entry
>Pausa a reprodução.</entry>
</row>
<row>
<entry
>-f, --next</entry>
<entry
>Passa para a próxima faixa na lista de reprodução.</entry>
</row>
<row>
<entry
>-a, --append</entry>
<entry
>Adicionar arquivos/URLs à lista de reprodução.</entry>
</row>
<row>
<entry
>-e, --enqueue</entry>
<entry
>Veja 'append', disponível por razões de compatibilidade.</entry>
</row>
<row>
<entry
>--queue</entry>
<entry
>Coloca arquivos/URLs na lista após a faixa atual.</entry>
</row>
<row>
<entry
>-m, --toggle-playlist-window</entry>
<entry
>Ativa ou desativa a janela da lista de músicas.</entry>
</row>
<row>
<entry
>--wizard</entry>
<entry
>Lança o assistente da Primeira Execução.</entry>
</row>
<row>
<entry
>--engine "nome"</entry>
<entry
>Inicia o &amarok; como o motor "nome".</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect1>
<sect1 id="script-writing">
<title
>Criação de 'Scripts'</title>
<para
>A programação permite-lhe estender o &amarok; facilmente sem ter que alterar o código principal. Os programas ou 'scripts' são semelhantes a 'plugins', mas em vez de terem uma API de 'plugins' dedicada, eles usam apenas a interface de DCOP do &amarok; para a comunicação. Isto torna possível criar 'scripts' em qualquer linguagem de programação, como o Ruby, o Python ou o PHP. Você não só poderá criar programas nas linguagens de 'scripting' clássicas, como também em linguagens compiladas, como em C++ ou em C simples. Além disso, o &amarok; poderá notificar os 'scripts' para certos eventos e fazer com que estes reajam de acordo com essa situação. Este sistema de notificação será explicado mais tarde nesta seção.</para>
<sect2 id="script-bindings">
<title
>Combinações</title>
<para
>É possível criar programas simples que não necessitem de interação com o usuário, assim como também é possível criar programas com GUIs confortáveis que se comportem como pequenas aplicações independentes. Para a programação da GUI, poderá ser usada uma das várias interfaces que o KDE oferece, como por exemplo o RubyQt, uma interface para a biblioteca do Qt em ruby. Contudo, deve ficar claro que nem todos os usuários possuem as interfaces disponíveis instaladas. Se optar por usar uma interface, tente usar uma das que sejam mais usada (p.ex., o RubyQt ou o PyQt).</para>
<para
>Para mostrar alguma reação, quando algum programa se recusa a rodar devido a uma dependência em falta, verifique por favor o seu programa para saber se o módulo que deseja incluir existe de fato. Se faltar essa dependência, deverá capturar o erro e mostrar uma janela de informação, usando a ferramenta da linha de comando "kdialog", para que o usuário saiba porque o programa não funciona.</para>
<para
>Este exemplo mostra como capturar uma dependência em falta no Ruby:</para>
<programlisting
>begin
require 'Korundum'
rescue LoadError
error = 'É necessário o Korundum (interface para o KDE em Ruby) do kdebindings v3.4 neste programa.'
`kdialog --sorry '#{error}'`
exit
end
</programlisting>
</sect2>
<sect2 id="script-templates">
<title
>Introdução: Os Modelos</title>
<para
>O &amarok; oferece modelos de programas em várias linguagens na pasta <filename class="directory"
>scripts/templates/</filename
>. Você poderá usar estes programas como base para os seus próprios 'scripts', assim como estendê-los com a funcionalidade que necessita. Irá reparar que a programação é, de fato, bastante intuitiva; por exemplo, se souber programar mais ou menos em Python, a criação do seu programa não irá levar muito tempo.</para>
</sect2>
<sect2 id="script-controlling-amarok">
<title
>Controlar o &amarok; com o DCOP</title>
<para
>Os programas poderão controlar o Amarok, invocando algumas das suas funções de DCOP. A forma mais simples de invocar uma função do DCOP é usando o utilitário da linha de comando "dcop", que faz parte de qualquer distribuição do KDE.</para>
<para
>Aqui está um exemplo para aumentar o volume-mestre:</para>
<programlisting
>dcop amarok player volumeUp</programlisting>
<para
>A maioria das linguagens de programação permitem executar programas externos, com uma função do tipo exec(). Desta forma, o utilitário "dcop" poderá ser invocado facilmente. Aqui está um exemplo simples em Python:</para>
<programlisting
>import os
os.system("dcop amarok player volumeDown")
</programlisting>
</sect2>
<sect2 id="script-notifications">
<title
>Notificações</title>
<para
>O &amarok; envia notificações para todos os programas em execução, escrevendo mensagens para o seu canal de 'stdin'. O programa deverá, deste modo, vigiar constantemente o 'stdin', de modo a reagir de acordo com cada um dos eventos possíveis. Os programas também poderão optar por ignorar qualquer evento que não necessitem.</para>
<para
>Serão enviadas as seguintes notificações pelo &amarok;:</para>
<programlisting
><cmdsynopsis
><command
>configure</command
></cmdsynopsis>
Diz ao programa para mostrar a sua janela de configuração. O programa deverá
lidar com o carregamento e salvamento das suas opções de configuração. Quando
um programa é iniciado, o Amarok muda a sua pasta de trabalho para a pasta
onde todos os dados deverão estar gravados.
</programlisting>
<programlisting
><cmdsynopsis
><command
>engineStateChange:</command
><arg
>empty|idle|paused|playing</arg
></cmdsynopsis>
Assinala uma mudança no estado do motor.
</programlisting>
<programlisting
><cmdsynopsis
><command
>trackChange</command
></cmdsynopsis>
Assinala o início de uma faixa nova. O programa poderá então usar as
funções de DCOP para obter mais informações sobre a faixa, p.ex., os
meta-dados e o tamanho.
</programlisting>
<programlisting
><cmdsynopsis
><command
>volumeChange</command
><arg
>novoVolume</arg
></cmdsynopsis>
Assinala a mudança do nível de volume-mestre. O volume é um número inteiro
de 0-100.
</programlisting>
<programlisting
><cmdsynopsis
><command
>customMenuClicked:</command
><arg
>submenu tituloItem locais</arg
></cmdsynopsis>
Devolve as localizações dos arquivos selecionados na lista de reprodução
quando o item do menu de contexto da lista de reprodução for clicado. O
submenu e o tituloItem são também devolvidos por razões de identificação,
no caso de um programa estar à espera de várias notificações.
Para inserir um item no menu de contexto, use a chamada de DCOP
'dcop amarok script addCustomMenuItem( submenu tituloItem )'. Para remover
um item do menu de contexto, use a chamada de DCOP
'dcop amarok script removeCustomMenuItem( submenu tituloItem )'.
</programlisting>
</sect2>
<sect2 id="script-termination">
<title
>Finalização do 'Script'</title>
<para
>Antes de o &amarok; sair, ou quando o usuário parar um 'script' com o Gerenciador de 'Scripts', o &amarok; envia o sinal SIGTERM para o programa. Este sinal poderá ser capturado para fazer algum trabalho de limpeza, como a gravação dos dados ou das opções de configuração.</para>
</sect2>
<sect2 id="script-packaging">
<title
>Empacotando</title>
<para
>O Gerenciador de 'Scripts' do &amarok; é capaz de instalar pacotes de programas que o usuário tenha obtido de um servidor da Web. Os pacotes são arquivos comprimidos perfeitamente normais (.tar), opcionalmente comprimidos com o bzip2 (.bz2). Recomenda-se em grande medida que use um nome de arquivo do tipo meu-programa.amarokscript.tar.bz2, para que o usuário consiga identificar facilmente o pacote como um programa do Amarok.</para>
<note
><para
>O &amarok; 1.3 só irá aceitar pacotes de 'scripts' com a extensão 'amarokscript', por isso é melhor é usá-la logo desde o início.</para
></note>
<para
>O conteúdo do pacote deverá estar organizado da seguinte forma:</para>
<programlisting
>myscript/
README
meu-programa.py (executável)
um-modulo.py
xpto.data
...
</programlisting>
</sect2>
<sect2 id="script-permissions">
<title
>Permissões dos arquivos</title>
<para
>O programa principal deverá ter permissões de execução (+x) ativas, enquanto os módulos adicionais que o programa carregar não deverão ser executáveis. Para preservar as permissões do arquivo no pacote, você deverá usar o 'tar' com a opção '-p':</para>
<programlisting
>tar -cf meu-programa.amarokscript.tar -p meu-programa</programlisting>
<note
><para
>O &amarok; não será capaz de instalar o programa se as permissões não estiverem definidas corretamente.</para
></note>
</sect2>
<sect2 id="script-distributing">
<title
>Distribuir</title>
<para
>Quando o pacote estiver terminado, você poderá enviá-lo para o <ulink url="http://www.kde-apps.org"
>www.kde-apps.org</ulink
> e adicionar a referência à <ulink url="http://amarok.kde.org/amarokwiki/index.php/Scripts"
>Página de 'Scripts' do Wiki do &amarok;</ulink
>. Para o item do 'kde-apps', deverá usar a categoria de <ulink url="http://kde-apps.org/index.php?xcontentmode=56"
>'Scripts' do &amarok;</ulink
>.</para>
</sect2>
</sect1>
</chapter>
