# Utilização Avançada

## Opções da Linha de Comandos

Ao executar o &appname; a partir da linha de comandos, existem várias opções para abrir os ficheiros de dados. Estas poderão ser consultadas com o comando `tellico --help`.

    Utilização: tellico [opções do Qt] [opções do KDE] [opções] [ficheiro]

    Tellico - um gestor de colecções para o KDE

    Opções:
      --nofile                  Não reabrir o último ficheiro aberto
      --bibtex                  Importar o <ficheiro> como um ficheiro bibtex
      --mods                    Importar o <ficheiro> como um ficheiro MODS
      --ris                     Importar o <ficheiro> como um ficheiro RIS

    Argumentos:
      ficheiro                  O ficheiro a abrir

## A Interface de &DBus;

O &appname; tem uma interface mínima de &DBus;, que pode ser usada para programar ou interagir com uma aplicação em execução, a partir da linha de comandos. Como acontece com todas as chamadas de &DBus;, terá de indicar a aplicação com que deseja interagir, assim como a interface em particular. O nome do serviço de &DBus; é `org.kde.tellico`.

### Comandos de &DBus;

Estão disponíveis dois objectos &DBus; na interface do Tellico: `Tellico` e `Collections`.

#### O Objecto `Tellico`

A lista completa de comandos de &DBus; do objecto `tellico` encontra-se disponível abaixo:

    bool importTellico(QString ficheiro, QString acção)
    bool importBibtex(QString ficheiro, QString acção)
    bool importMODS(QString ficheiro, QString acção)
    bool importRIS(QString ficheiro, QString acção)
    bool exportXML(QString ficheiro)
    bool exportZip(QString ficheiro)
    bool exportBibtex(QString ficheiro)
    bool exportHTML(QString ficheiro)
    bool exportCSV(QString ficheiro)
    bool exportPilotDB(QString ficheiro)
    QList<int> selectedEntries()
    QList<int> filteredEntries()
    void openFicheiro(QString ficheiro)
    void setFilter(QString texto)
    bool showEntry(int id)

Para os quatro comandos de importação, o primeiro argumento é o ficheiro a importar, enquanto o segundo é a acção de importação. Estão disponíveis três acções: replace (substituição), append (adição) e merge (reunião). São suportados quatro formatos de ficheiros na importação: ficheiros &XML; do Tellico, ficheiros Bibtex, ficheiros MODS e ficheiros RIS.

A colecção aberta de momento no &appname; poderá ser exportada para um ficheiro, sendo no formato &XML; do Tellico, no formato ZIP do mesmo, em Bibtex, &HTML;, valores separados por vírgulas (CSV) ou no formato PilotDB.

Uma lista dos ID's dos elemento seleccionados ou filtrados de momento permite facilitar a apresentação ou actualização dos itens na janela.

Poderá abrir um novo ficheiro de dados com o comando `openFile()`. Deverá indicar a localização completa.

Poderá definir um novo filtro com o comando `setFilter()`, o qual é o equivalente de escrever o mesmo filtro no campo respectivo da janela principal.

Dado um ID de um elemento, o `showEntry()` irá seleccionar esse item e mostrar os seus detalhes na janela principal.

#### O Objecto `Collections`

A lista completa de comandos &DBus; do objecto `Collections` encontra-se descrita abaixo:

    int addEntry()
    bool removeEntry(int idItem)
    QStringList allValues(QString nomeCampo)
    QStringList entryValues(int idItem, QString nomeCampo)
    QStringList selectedBibtexKeys()
    QString entryBibtexKey(int idItem)
    bool setEntryValue(int idItem, QString nomeCampo, QString valor)
    bool addEntryValue(int idItem, QString nomeCampo, QString valor)

Poderá criar um novo elemento vazio na colecção actual, usando o comando `addEntry()`. O valor devolvido é o ID do elemento, que poderá ser usado para definir os valores dos campos do mesmo elemento. Poderá apagar um elemento da colecção com o comando `removeEntry()`.

Se invocar o `allValues()` com apenas um nome de campo, irá devolver todos os valores desse campo, para os itens seleccionados de momento. Se não forem seleccionados nenhuns elementos, é devolvida uma lista vazia. Se for incluído num ID de elemento no comando, são devolvidos os valores dos campos para esse elemento em particular.

Se a colecção actual for uma bibliografia, a invocação do `selectedBibtexKeys()` irá devolver a citação do Bibtex para todos os itens seleccionados. A 'bibtexKey' de um item específico poderá ser obtida com o comando `entryBibtexKey()`.

Poderá editar os elementos directamente com a interface &DBus;. Dado um ID de elemento, o `setEntryValue()` irá configurar o valor do campo directamente. Para adicionar um valor, sem afectar os valores existentes, use o `addEntryValue()`. O novo valor é adicionado ao fim da lista existente.

### Exemplos de &DBus;

Aqui estão alguns exemplos de programação do &appname; com a interface &DBus;. Dado que o pid deverá ser conhecido, a forma mais simples de incluir isso num comando da consola será algo do género: `dbus $(dbus | grep tellico) tellico`.

    Abrir um ficheiro do Bibtex
    % qdbus org.kde.tellico /Tellico org.kde.tellico.importBibtex "/home/ze/referência.bib" "replace"
    true

    Exportar um ficheiro do Bibtex
    % qdbus org.kde.tellico /Tellico org.kde.tellico.exportBibtex ~/documentos/referência.bib
    true

    Apresentar a chave de citação da selecção actual
    % qdbus org.kde.tellico /Collections org.kde.tellico.selectedBibtexKeys
    stephenson2004

    Adicionar um novo elemento e modificar o título
    % o_meu_id=`qdbus org.kde.tellico /Collections org.kde.tellico.addEntry`
    % qdbus org.kde.tellico /Collections org.kde.tellico.setEntryValue $o_meu_id título "O Meu Livro Novo"
    true