http://docs.kde.org/
AnteriorAmpliando o KatePartPróxima

Scripts com JavaScript

O componente de edição do KatePart é facilmente extensível, através da criação de scripts. A linguagem de programação é o ECMAScript (popularmente conhecido como JavaScript). O KatePart suporta dois tipos de scripts: os de recuo e os de linha de comando. Uma funcionalidade semelhante aos scripts de linha de comando também é fornecida no plugin de trechos.

Scripts de recuo

Scripts de recuo - também conhecidos por recuadores - formatam automaticamente o código-fonte enquanto você digita o texto. Por exemplo, depois de pressionar a tecla Return, o nível de recuo costuma aumentar.

As seções a seguir descrevem, passo-a-passo, como criar o esqueleto de um módulo de recuo simples. Como primeiro passo, crie um novo arquivo *.js, chamado de, por exemplo, javascript.js na pasta pessoal local $XDG_DATA_HOME/katepart5/script/indentation. Nesse sentido, a variável de ambiente XDG_DATA_HOME normalmente se expande para qualquer ~/.local ou ~/.local/share.

No Windows® estes arquivos estão localizados em %USERPROFILE%\AppData\Local\katepart5\script\indentation. %USERPROFILE% que normalmente se expandem para C:\\Users\\usuário.

O cabeçalho do script de recuo

O cabeçalho do arquivo javascript.js está incorporado como JSON no início do documento no seguinte formato: 

var katescript = {
    "name": "JavaScript",
    "author": "Nome de Exemplo <nome.exemplo@endereco.org>",
    "license": "BSD License",
    "revision": 1,
    "kate-version": "5.1",
    "required-syntax-style": "javascript",
    "indent-languages": ["javascript"],
    "priority": 0,
}; // kate-script-header, deve estar no início do arquivo, sem comentários

Cada item será agora explicado em detalhes:

  • name [obrigatório]: Este é o nome do modo de recuo que aparece no menu Ferramentas → Recuar e na janela de configuração.

  • author [opcional]: O nome e a informação de contato do autor.

  • license [opcional]: Forma curta da licença, como por exemplo, BSD License ou LGPLv3.

  • revision [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado.

  • kate-version [obrigatório]: A versão mínima do KatePart necessária.

  • required-syntax-style [opcional]: O estilo do sintaxe necessário, que corresponde ao style indicado no sintaxe dos arquivos realçados. Isto é importante para recuadores que se baseiam em informações de realce no documento. Se uma determinada realce de sintaxe dor especificada, o recuador estará disponível somente quando a realce de sintaxe apropriada estiver ativa. Isto evite um “comportamento inesperado” causado pelo uso do recuador sem o esquema de realce esperado. Por exemplo, o recuado do Ruby faz uso dos arquivos ruby.js e ruby.xml.

  • indent-languages [opcional]: Uma lista JSON de estilos de sintaxe que este módulo consegue recuar corretamente, por exemplo: ["c++", "java"].

  • priority [opcional]: Se existirem vários módulos de recuo adequados para um determinado arquivo de realce, este campo decide qual deverá ser usado por padrão.

O código-fonte do recuador

Tendo definido o cabeçalho, esta seção explica como funciona a programação de recuadores em si. O esqueleto básico do código parece-se com o seguinte: 

// Necessário para as bibliotecas js do katepart, por exemplo range.js se você usar Range
require ("range.js");
  
caracteresAtivacao = "{}/:;";
function indent(linha, larguraRecuo, caractere)
{
    // invocado para cada linha nova (caractere == '\n') e todos os caracteres indicados na
    // variável global 'caracteresAtivacao'. Ao invocar o Ferramentas → Formatar recuo
    // a variável 'caractere' está em branco, isto é, caractere == ''.
    //
    // ver também: API de Programação
    return -2;
}

A função indent() tem três parâmetros:

  • linha: a linha que tem de ser recuada

  • larguraRecuo: o número de espaços correspondentes a cada recuo

  • caractere: ou um caractere de mudança de linha (ch == '\n'), algum dos caracteres de ativação indicados em caracteresAtivacao ou vazio, caso o usuário tenha invocado a ação Ferramentas → Alinhar.

O valor devolvido pela função indent() define como a linha será recuada. Se o valor devolvido for um número inteiro, é interpretado da seguinte forma:

  • valor devolvido -2: não fazer nada

  • valor devolvido -1: mantém o recuo (procura pela linha não-vazia anterior)

  • valor devolvido 0: números >= 0 definem a largura do recuo em espaços

Em alternativa, poderá ser devolvida uma lista com dois elementos:

  • return [ recuo, alinhamento ];

Nesse caso, o primeiro elemento é a profundidade de recuo, tendo o mesmo significado que os valores especiais. Contudo, o segundo elemento é um valor absoluto que representa uma coluna para o “alinhamento”. Se este valor for maior que o valor do recuo, a diferença representa um número de espaços a adicionar após o recuo do primeiro parâmetro. Caso contrário, o segundo número será ignorado. A utilização de tabulações e espaços nos recuos é normalmente referida como sendo um “modo misto”.

Considere o seguinte exemplo: Considerando que são usadas as tabulações para recuar, e que o tamanho da tabulação é de 4. Aqui, o <tab> representa uma tabulação e o '.' representa um espaço: 

1: <tab><tab>xpto("olá",
2: <tab><tab>......."mundo");

Ao recuar a linha 2, a função indent() devolve [8, 15]. Em função disso, são introduzidas duas tabulações para recuar até à coluna 8, e são introduzidos 7 espaços para alinhar o segundo parâmetro com o primeiro, de modo a permanecer alinhado, caso o arquivo seja visto com outro tamanho de tabulação.

Uma instalação padrão do KDE fornece o KatePart com vários módulos de recuo. O código-fonte correspondente em JavaScript poderá ser encontrado em $XDG_DATA_DIRS/katepart5/script/indentation.

No Windows® estes arquivos estão localizados em %USERPROFILE%\AppData\Local\katepart5\script\indentation. %USERPROFILE% que normalmente se expandem para C:\\Users\\usuário.

A criação de um módulo de recuo necessita do recarregamento dos scripts, de modo a ver se as alterações se comportam de forma adequada. Em vez de reiniciar o aplicativo, basta ir para a linha de comando e executar o comando reload-scripts.

Se você criar scripts úteis, considere a hipótese de contribuir com eles para o Projeto KatePart enviando uma solicitação de mesclagem para nosso projeto no GitLab.

Scripts de Linha de Comando

Nota

Uma funcionalidade semelhante a scripts de linha de comando também é fornecida no plugin de trechos. Este plugin pode fornecer um ponto de partida mais fácil, especialmente para pequenos scripts personalizados.

Como é difícil satisfazer as necessidades de todos, o KatePart tem suporte a algumas ferramentas auxiliares para manipular rapidamente o texto, usando para isso a linha de comando incorporada. Por exemplo, o comando sort está implementado como um script. Esta seção explica como criar arquivos *.js que estendem o KatePart com algumas funções auxiliares arbitrárias.

Os scripts de linha de comando estão localizados na mesma pasta que os scripts de recuo. Assim, como primeiro passo, crie um arquivo *.js novo, chamado utilitários.js na pasta pessoal local, em $XDG_DATA_HOME/katepart5/script/commands. Nesse sentido, a variável de ambiente XDG_DATA_HOME normalmente se expande para ~/.local ou ~/.local/share.

No Windows, esses arquivos estão localizados em %USERPROFILE%\AppData\Local\katepart5\script\commands. %USERPROFILE% geralmente se expande para C:\\Users\\usuário.

O Cabeçalho do Script de Linha de Comando

O cabeçalho de cada script de linha de comando é está incorporado como JSON no início do script no seguinte formato: 

var katescript = {
    "author": "Nome de exemplo <nome.exemplo@endereco.org>",
    "license": "LGPLv2+",
    "revision": 1,
    "kate-version": "5.1",
    "functions": ["ordenar", "descerLinhas"],
    "actions": [
        {   "function": "ordenar",
            "name": "Ordena o texto selecionado",
            "category": "Edição",
            "interactive": "false"
        },
        {   "function": "descerLinhas",
            "name": "Desce as linhas",
            "category": "Edição",
            "shortcut": "Ctrl+Shift+Down",
            "interactive": "false"
        }
    ]
}; // kate-script-header, deve estar no início do arquivo, sem comentários

Cada item será agora explicado em detalhes:

  • author [opcional]: O nome e a informação de contato do autor.

  • license [opcional]: Forma curta da licença, como por exemplo, BSD License ou LGPLv2.

  • revision [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado.

  • kate-version [obrigatório]: A versão mínima do KatePart necessária.

  • functions [obrigatório]: Uma lista JSON dos comandos do script.

  • actions [opcional]: Array em JSON de objetos JSON que definem as ações que aparecem no menu do aplicativo. São oferecidas informações detalhadas na seção Associar combinações de teclas.

Uma vez que o valor de functions é uma lista em JSON, um único script é capaz de conter um número arbitrário de comandos da linha de comando. Cada função está disponível através da linha de comando incorporada do KatePart.

O Código-Fonte do Programa

Todas as funções indicadas no cabeçalho terão de estar implementadas no programa. Por exemplo, o arquivo de programa do exemplo acima tem que implementar as duas funções ordenar e descerLinhas. Todas as funções têm a seguinte sintaxe: 

// bibliotecas necessárias do katepart js, por exemplo range.js se você usar Range
function <nome>(arg1, arg2, ...)
{
    // ... implementação, ver também: API de Programação
}

Os argumentos na linha de comando são passados à função como arg1, arg2, etc. Para poder indicar a documentação de cada comando, basta implementar a função 'help', como demonstrado a seguir: 

function help(cmd)
{
    if (cmd == "sort") {
        return i18n("Ordena o texto selecionado.");
    } else if (cmd == "...") {
        // ...
    }
}

Executar help sort na linha de comando, irá invocar esta função de ajuda com o argumento cmd igual ao comando indicado, como isto é, cmd == "sort". O KatePart irá assim apresentar o texto devolvido como documentação ao usuário. Certifique-se de traduzir os textos.

Criar um script para a linha de comando requer o recarregamento dos scripts, de modo a ver se as alterações funcionam apropriadamente. Em vez de reiniciar o aplicativo, basta mudar para a linha de comando e executar o comando reload-scripts.

Associar combinações de teclas

Para tornar os scripts acessíveis no menu do aplicativo e atribuir teclas de atalho, o script precisa fornecer um cabeçalho do script apropriado. No exemplo acima, ambas as funções ordenar e descerLinhas aparecem no menu, graças ao seguinte componente no cabeçalho do script: 

var katescript = {
    ...
    "actions": [
        {   "function": "ordenar",
            "name": "Ordena o texto selecionado",
            "icon": "",
            "category": "Edição",
            "interactive": "false"
        },
        {   "function": "descerLinhas",
            "name": "Desce as linhas",
            "icon": "",
            "category": "Edição",
            "shortcut": "Ctrl+Shift+Down",
            "interactive": "false"
        }
    ]
};

Os campos de uma ação são os seguintes:

  • function [obrigatório]: A função que deverá aparecer no menu Ferramentas → Scripts.

  • name [obrigatório]: O texto que aparece no menu do script.

  • icon [opcional]: O ícone aparece após ao texto no menu. Todos os nomes de ícones do KDE poderão ser usados aqui.

  • category [opcional]: Se for indicada uma categoria, o programa aparece num submenu.

  • shortcut [opcional]: A combinação de teclas indicada aqui é o atalho de teclado padrão. Por exemplo: Ctrl+Alt+T. Veja a documentação do Qt™ para mais detalhes.

  • interactive [opcional]: Se o script precisa de interação por parte do usuário na linha de comando, configure este valor como true (verdadeiro).

Se você criar scripts úteis, considere a hipótese de contribuir com eles para o Projeto KatePart enviando uma solicitação de mesclagem para nosso projeto no GitLab.

API de Programação

A API de criação de scripts aqui apresentada está disponível em todos os scripts, isto é, os scripts de recuo e os comandos do terminal. As classes Cursor e o Range são fornecidas por arquivos de bibliotecas em $XDG_DATA_DIRS/katepart5/libraries. Elas serão necessárias, caso queira usar algumas das funções Document ou View no seu script. Inclua a biblioteca necessária usando: 

// bibliotecas necessárias do katepart js, por exemplo range.js se você usar Range
require ("range.js");

Para ampliar a API padrão de scripts com suas funções e protótipos próprios, basta criar um arquivo novo na pasta de configuração local do KDE, em $XDG_DATA_HOME/katepart5/libraries e incluí-lo no seu script usando: 

require ("myscriptnamehere.js");

No Windows, esses arquivos estão localizados em %USERPROFILE%\AppData\Local\katepart5\libraries. %USERPROFILE% geralmente se expande para C:\\Users\\usuário.

Para estender os protótipos existentes, como o Cursor ou o Range, a forma recomendada é não modificar os arquivos *.js globais. Em vez disso, altere o protótipo do cursor.js em JavaScript, após o cursor.js que é incluído no seu script através do require.

Cursores e Intervalos

Como o KatePart é um editor de texto, sempre que possível, toda a API de criação de scripts é baseada em cursores e intervalos. Um cursor é uma simples dupla (linha, coluna) que representa uma posição de texto no documento. Um Range (Intervalo) corresponde a uma área de texto coberta desde uma posição inicial do cursor até outra posição de fim. A API é explicada em detalhes nas seções a seguir.

O Protótipo do Cursor
Cursor();

Construtor. Devolve um Cursor na posição (0, 0).

Exemplo: var cursor = new Cursor(); 

Cursor(int linha, int coluna);

Construtor. Devolve um Cursor na posição (linha, coluna).

Exemplo: var cursor = new Cursor(3, 42); 

Cursor(Cursor outro);

Construtor de cópia. Devolve uma cópia do cursor outro.

Exemplo: var copia = new Cursor(outro); 

Cursor Cursor.clone();

Devolve uma cópia do cursor.

Exemplo: var clone = cursor.clone(); 

Cursor.setPosition(int linha, int coluna);

Configura a posição do cursor em linha e coluna.

Desde: KDE 4.11 

bool Cursor.isValid();

Verifica se o cursor é válido. O cursor é inválido no caso em que a linha e/ou coluna sejam iguais a -1.

Exemplo: var valido = cursor.isValid(); 

Cursor Cursor.invalid();

Devolve um novo cursor inválido, localizado em (-1, -1).

Exemplo: var cursorInvalido = cursor.invalid(); 

int Cursor.compareTo(Cursor outro);

Compara este cursor com o cursor outro. Devolve

  • -1, se este cursor for localizado antes do cursor outro,

  • 0, se ambos os cursores forem iguais e

  • +1, se este cursor se localizar após o cursor outro.

bool Cursor.equals(Cursor outro);

Devolve true (verdadeiro), se este o cursor e o outro forem iguais, caso contrário devolve false (falso). 

String Cursor.toString();

Devolve o cursor como um texto no formato “Cursor(linha, coluna)”.

O Protótipo do Intervalo
Range();

Construtor. A invocação de new Range() devolve um intervalo Range de (0, 0) - (0, 0). 

Range(Cursor inicio, Cursor fim);

Construtor. A invocação de new Range(início, fim) devolve o intervalo (início, fim). 

Range(int linhaInicial, int colunaInicial, int linhaFinal, int colunaFinal);

Construtor. A invocação de new Range(linhaInicial, colunaInicial, linhaFinal, colunaFinal) devolve um intervalo Range de (linhaInicial, colunaInicial) até (linhaFinal, colunaFinal). 

Range(Range outro);

Construtor de cópia. Devolve uma cópia do intervalo Range outro. 

Range Range.clone();

Devolve uma cópia do intervalo.

Exemplo: var clone = intervalo.clone(); 

bool Range.isEmpty();

Devolve true (verdadeiro), se o cursor de início e de fim forem iguais.

Exemplo: var vazio = intervalo.isEmpty();

Desde: KDE 4.11 

bool Range.isValid();

Devolve true (verdadeiro), se tanto o cursor de início como o de fim forem válidos, caso contrário devolve false (falso).

Exemplo: var valido = intervalo.isValid(); 

Range Range.invalid();

Devolve o intervalo Range de (-1, -1) até (-1, -1). 

bool Range.contains(Cursor cursor);

Devolve true (verdadeiro) se este intervalo contiver a posição do cursor, caso contrário, devolve false (falso). 

bool Range.contains(Range outro);

Devolve true (verdadeiro) se este intervalo contiver o intervalo Range outro, caso contrário, devolve false (falso). 

bool Range.containsColumn(int coluna);

Devolve true (verdadeiro) se a coluna estiver no intervalo semiaberto [início.coluna, fim.coluna), caso contrário, devolve false (falso). 

bool Range.containsLine(int linha);

Devolve true (verdadeiro) se a linha estiver no intervalo semiaberto [início.linha, fim.linha), caso contrário, devolve false (falso). 

bool Range.overlaps(Range outro);

Devolve true (verdadeiro) se este intervalo e o intervalo outro compartilharem uma região em comum, caso contrário devolve false (falso). 

bool Range.overlapsLine(int linha);

Devolve true (verdadeiro) se a linha estiver no intervalo [início.linha, fim.linha], caso contrário devolve false (falso). 

bool Range.overlapsColumn(int coluna);

Devolve true (verdadeiro) se a coluna estiver no intervalo [início.coluna, fim.coluna], caso contrário devolve false (falso). 

bool Range.onSingleLine();

Devolve true (verdadeiro) se o intervalo inicia e termina na mesma linha, isto é, se Range.start.line == Range.end.line.

Desde: KDE 4.9 

bool Range.equals(Range outro);

Devolve true (verdadeiro) se este intervalo e o intervalo outro forem iguais, caso contrário devolve false (falso). 

String Range.toString();

Devolve o intervalo como uma string no formato “Range(Cursor(linha, coluna), Cursor(linha, coluna))”.

Funções globais

Esta seção apresenta todas as funções globais.

Arquivos de leitura e inclusão
String read(String arquivo);

Irá procurar pelo arquivo indicado em relação à pasta katepart5/script/files e irá devolver o seu conteúdo como texto. 

void require(String Arquivo);

Irá procurar pelo arquivo indicado em relação à pasta katepart5/script/libraries e avaliá-lo. O require está protegido internamente contra inclusões múltiplas do mesmo arquivos.

Desde: KDE 4.10

Depuração
void debug(String texto);

Imprime o texto no stdout, mais precisamente no console que lança a aplicação.

Tradução

Para um suporte regional completo, existem diversas funções para traduzir os textos nos programas, nomeadamente o i18n, o i18nc, o i18np e o i18ncp. Estas funções comportam-se exatamente como as funções de tradução do KDE.

As funções de tradução convertem os textos indicados ao sistema de traduções do KDE para o idioma usado no aplicativo. Os textos nos scripts que são desenvolvidos no âmbito do código oficial do KatePart são automaticamente extraídos e preparados para tradução. Em outras palavras, como desenvolvedor do KatePart, você não precisa que se preocupar com a extração e tradução. Contudo, a tradução só funciona dentro da infraestrutura do KDE, isto é, novos textos em scripts de terceiros, desenvolvidos fora do KDE, não são traduzidos. Dessa forma, considere contribuir com seus scripts para o Kate, para que seja possível obter uma tradução adequada. 

void i18n(String texto, arg1, ...);

Traduz o texto na língua usada pela aplicação. Os argumentos arg1, ..., são opcionais e usados para substituir os itens %1, %2, etc.

void i18nc(String contexto, String texto, arg1, ...);

Traduz o texto na língua usada pela aplicação. Além disso, o texto do contexto fica visível aos tradutores para que possam dar uma tradução mais adequada. Os argumentos arg1, ..., são opcionais e são usados para substituir os itens de substituição %1, %2, etc.

void i18np(String singular, String plural, int número, arg1, ...);

Traduz tanto o texto singular como o plural para a língua usada pela aplicação, dependendo do número indicado. Os argumentos arg1, ..., são opcionais e usados para substituir os itens de substituição %1, %2, etc.

void i18ncp(String contexto, String singular, String plural, intnúmero, arg1, ...);

Traduz tanto o texto singular como o plural para a língua usada pela aplicação, dependendo do número indicado. Adicionalmente, o texto do contexto é visível para as tradutores, para que possam fornecer uma tradução mais adequada. Os argumentos arg1, ..., são opcionais e são usados para substituir os itens %1, %2, etc.

A API do View

Sempre que um programa está sendo executado, existe uma variável global “view” que representa a área de edição ativa no momento. Segue-se uma lista com todas as funções disponíveis para o View. 

void view.copy()

Copia a seleção se houver uma, caso contrário, a linha atual se a opção [ ] Copiar/Recortar a linha atual se nenhuma seleção estiver definida.

Desde: KDE Frameworks™ 5.79

void view.cut()

Recorta a seleção se houver uma, caso contrário, a linha atual se a opção [ ] Copiar/Recortar a linha atual se nenhuma seleção estiver definida.

Desde: KDE Frameworks™ 5.79

void view.paste()

Cola o conteúdo da área de transferência.

Desde: KDE Frameworks™ 5.79

Cursor view.cursorPosition()

Devolve a posição atual do cursor na janela.

void view.setCursorPosition(int linha, int coluna);
void view.setCursorPosition(Cursor cursor);

Altera a posição atual do cursor para uma (linha, coluna) qualquer ou para o cursor indicado. 

Cursor view.virtualCursorPosition();

Devolve a posição virtual do cursor com cada tabulação a corresponder ao número indicado de espaços, dependente da largura de tabulação atual. 

void view.setVirtualCursorPosition(int linha, int coluna);
void view.setVirtualCursorPosition(Cursor cursor);

Altera a posição atual do cursor virtual para uma (linha, coluna) qualquer ou para o cursor indicado. 

String view.selectedText();

Devolve o texto selecionado. Se não tiver nenhum texto selecionado, o texto devolvido vem vazio. 

bool view.hasSelection();

Devolve true (verdadeiro) se a janela contiver algum texto selecionado, caso contrário, devolve false (falso). 

Range view.selection();

Devolve o intervalo de texto selecionado. O intervalo devolvido é inválido, caso não esteja selecionado nenhum texto. 

void view.setSelection(Range intervalo);

Altera o texto selecionado para o intervalo indicado. 

void view.removeSelectedText();

Remove o texto selecionado. Se a janela não tiver nenhuma seleção feita, isto não faz nada. 

void view.selectAll();

Seleciona todo o texto no documento. 

void view.clearSelection();

Limpa a seleção de texto atual, sem remover o texto. 

void view.setBlockSelection(bool on);

Liga/desliga o modo de seleção de blocos. 

bool view.blockSelection();

Devolve true (verdadeiro) se o modo de seleção de bloco estiver ligado, caso contrário, devolve false (falso). 

void view.align(Range intervalo);

Ajusta corretamente o recuo das linhas dentro do intervalo de acordo com as configurações de recuo atuais. 

void view.alignOn(Range intervalo, String padrão = "");

Alinha as linhas no intervalo na coluna especificada pela expressão regula padrão. Com um padrão vazio especificado, o alinhamento será feito no primeiro caractere não vazio. Se o padrão contiver uma captura, o recuo será feito na correspondência capturada.

Exemplos:

view.alignOn(document.documentRange(), '-'); irá inserir espaços antes do primeiro - de cada linha para alinhá-las todas na mesma coluna.

view.alignOn(document.documentRange(), ':\\s+(.)'); Irá inserir espaços antes do primeiro caractere não em branco que ocorrer após dois pontos para alinhá-los todos na mesma coluna.

object view.executeCommand(String comando,
                           String args,
                           Range intervalo);

Executa o comando de linha de comando comando com os argumentos opcionais args e o intervalo opcional intervalo. O objeto retornado object possui uma propriedade booleana object.ok que indica se a execução do comando comando foi bem-sucedida. Em caso de erro, a string object.status contém uma mensagem de erro.

Desde: KDE Frameworks™ 5.50

Range view.searchText(Range intervalo,
                      String padrão,
                      bool backwards = false);

Busca a primeira ocorrência do padrão em intervalo e retorna o intervalo correspondente. A busca é realizada de trás para frente se o parâmetro booleano opcional backwards estiver definido como true.

O intervalo retornado é inválido (consulte Range.isValid()) se padrão não for encontrado no intervalo.

Desde: KDE Frameworks™ 5.97

API do Document

Sempre que um script estiver em execução, existe um objeto global (variável) “document” representando o documento ativo atual. A seguir é apresentada uma lista de todas as funções disponíveis para o Document. 

String document.fileName();

Devolve o nome do arquivo do documento, ou então um texto vazio para as janelas de texto ainda por salvar. 

String document.url();

Devolve o URL completo do documento, ou então um texto vazio para as janelas de texto ainda por salvar. 

String document.mimeType();

Devolve o tipo MIME do documento, ou então o tipo MIME application/octet-stream se não for encontrado qualquer tipo MIME apropriado. 

String document.encoding();

Devolve a codificação usada atualmente para salvar o arquivo. 

String document.highlightingMode();

Devolve o modo de realce global usado para todo o documento. 

String document.highlightingModeAt(Cursor pos);

Devolve o modo de realce usado na posição do cursor indicada do documento. 

Array document.embeddedHighlightingModes();

Devolve uma lista com os modos de realce incorporados neste documento. 

bool document.isModified();

Devolve true (verdadeiro) se o documento tiver alguma alteração por salvar, caso contrário devolve false. 

String document.text();

Devolve o conteúdo inteiro do documento numa única sequência de texto. As mudanças de linha estão marcadas com o caractere de mudança de linha “\n”. 

String document.text(int daLinha, int daColuna, int paraLinha, int paraColuna);
String document.text(Cursor de, Cursor para);
String document.text(Range intervalo);

Devolve o texto no intervalo indicado. Recomenda-se que use a versão baseada nos cursores e nos intervalos, de modo a ter uma melhor visibilidade do código-fonte. 

String document.line(int linha);

Devolve a linha de texto indicada como uma sequência de texto. O texto devolvido fica em branco, caso a linha pedida esteja fora do intervalo. 

String document.wordAt(int linha, int coluna);
String document.wordAt(Cursor cursor);

Devolve a palavra na posição do cursor indicada. 

Range document.wordRangeAt(int linha, int coluna);
Range document.wordRangeAt(Cursor cursor);

Devolve o intervalo da palavra na posição indicada do cursor. O intervalo devolvido é inválido (ver Range.isValid()), caso a posição do texto esteja após o fim de uma linha. Se não existir nenhuma palavra no cursor indicado, é devolvido um intervalo vazio.

Desde: KDE 4.9 

String document.charAt(int linha, int coluna);
String document.charAt(Cursor cursor);

Devolve o caractere na posição do cursor indicada. 

String document.firstChar(int linha);

Devolve o primeiro caractere na linha que não seja um espaço em branco. O primeiro caractere encontra-se na coluna 0. Se a linha estiver em branco ou conter apenas espaços, a string devolvida será vazia. 

String document.lastChar(int linha);

Devolve o último caractere da linha indicada que não seja um espaço em branco. O primeiro caractere encontra-se na coluna 0. Se a linha estiver em branco ou só tiver espaços em branco, o texto devolvido vem vazio. 

bool document.isSpace(int linha, int coluna);
bool document.isSpace(Cursor cursor);

Devolve true (verdadeiro), se o caractere na posição indicada do cursor for um espaço em branco, caso contrário, devolve false (falso). 

bool document.matchesAt(int linha, int coluna, String texto);
bool document.matchesAt(Cursor cursor, String texto);

Devolve true (verdadeiro) se o texto indicado corresponder à posição indicada do cursor, caso contrário, devolve false (falso). 

bool document.startsWith(int linha, String texto, bool ignorarEspacos);

Devolve true (verdadeiro) se a linha começar por texto, caso contrário, devolve false (falso). O argumento ignorarEspacos controla se os espaços envolventes são ignorados ou não. 

bool document.endsWith(int linha, String texto, bool ignorarEspacos);

Devolve true (verdadeiro), caso a linha termine em texto, caso contrário devolve false (falso). O argumento ignorarEspacos controla se os espaços envolventes são ignorados. 

bool document.setText(String texto);

Altera o texto do documento por inteiro. 

bool document.clear();

Limpa o texto no documento por inteiro. 

bool document.truncate(int linha, int coluna);
bool document.truncate(Cursor cursor);

Trunca a linha indicada, na coluna ou posição do cursor indicadas. Devolve true (verdadeiro) em caso de sucesso ou false (falso) se a linha não estiver dentro do intervalo do documento. 

bool document.insertText(int linha, int coluna, String texto);
bool document.insertText(Cursor cursor, String texto);

Insere o texto na posição do cursor indicada. Devolve true, em caso de sucesso, ou false (falso), se o documento estiver apenas para leitura. 

bool document.removeText(int daLinha, int daColuna, int paraLinha, int paraColuna);
bool document.removeText(Cursor de, Cursor para);
bool document.removeText(Range intervalo);

Remove o texto no intervalo indicado. Devolve true (verdadeiro), em caso de sucesso, ou false (falso), se o documento estiver no modo apenas para leitura. 

bool document.insertLine(int linha, String texto);

Insere o texto na linha indicada. Devolve true (verdadeiro), em caso de sucesso, ou false (falso), caso o documento esteja apenas para leitura ou se a linha não estiver no intervalo do documento. 

bool document.removeLine(int linha);

Remove a linha de texto indicada. Devolve true (verdadeiro), em caso de sucesso, ou false (falso), caso o documento esteja no modo apenas para leitura ou se a linha não estiver no intervalo do documento. 

bool document.wrapLine(int linha, int coluna);
bool document.wrapLine(Cursor cursor);

Reparte a linha na posição indicada pelo cursor. Devolve true (verdadeiro) em caso de sucesso ou false (falso) se, por exemplo, a linha < 0.

Desde: KDE 4.9 

void document.joinLines(int linhaInicial, int linhaFinal);

Junta as linhas de linhaInicial até linhaFinal. Duas linhas de texto sucessivas estão sempre separadas por um espaço em branco. 

int document.lines();

Devolve o número de linhas do documento. 

bool document.isLineModified(int linha);

Devolve true (verdadeiro), se a linha contém dados que não foram salvos.

Desde: KDE 5.0 

bool document.isLineSaved(int linha);

Devolve true (verdadeiro), se a linha foi alterada, mas o documento foi salvo. Assim, a linha não contém dados não salvos.

Desde: KDE 5.0 

bool document.isLineTouched(int linha);

Devolve true (verdadeiro), se a linha contém dados que não foram salvos ou foi anteriormente alterado.

Desde: KDE 5.0 

bool document.findTouchedLine(int linhaInicial, bool abaixo);

Procura pela próxima linha tocada que comece na linha. A pesquisa é efetuada tanto para cima como para baixo, dependendo da direção de pesquisa indicada em baixo.

Desde: KDE 5.0 

int document.length();

Devolve o número de caracteres do documento. 

int document.lineLength(int linha);

Devolve o comprimento da linha. 

void document.editBegin();

Inicia um grupo de edição para agrupar operações a desfazer/refazer. Certifique-se de invocar sempre o editEnd() tantas vezes quanto invoca o editBegin(). A invocação do editBegin() usa um contador de referências interno, isto é, esta chamada pode ser encadeada. 

void document.editEnd();

Termina um grupo de edição. A última invocação do editEnd() (isto é, a correspondente à primeira chamada do editBegin()) termina o passo de edição. 

int document.firstColumn(int linha);

Devolve a primeira coluna não em branco para a linha indicada. Se só existirem espaços em branco na linha, o valor devolvido é -1. 

int document.lastColumn(int linha);

Devolve a última coluna que não esteja em branco para a linha indicada. Se só existirem espaços em branco na linha, o valor devolvido é -1. 

int document.prevNonSpaceColumn(int linha, int coluna);
int document.prevNonSpaceColumn(Cursor cursor);

Devolve a coluna com caracteres não-brancos que começa na posição de cursor indicada e pesquisa para trás. 

int document.nextNonSpaceColumn(int linha, int coluna);
int document.nextNonSpaceColumn(Cursor cursor);

Devolve a coluna com caracteres não-brancos que começa na posição de cursor indicada e pesquisa para a frente. 

int document.prevNonEmptyLine(int linha);

Devolve a primeira linha não-vazia que contém caracteres não-nulos, pesquisando depois para trás. 

int document.nextNonEmptyLine(int linha);

Devolve a primeira linha não-vazia que contém caracteres não-nulos, pesquisando depois para a frente. 

bool document.isInWord(String caractere, int atributo);

Devolve true (verdadeiro), caso o caractere e atributo indicados possam fazer parte de uma palavra, caso contrário devolve false (falso). 

bool document.canBreakAt(String caractere, int atributo);

Devolve true (verdadeiro) se o caractere indicado com o atributo indicado for adequado para mudar de linha, caso contrário devolve false. 

bool document.canComment(int atributoInicial, int atributoFinal);

Devolve true (falso), caso um intervalo que começa e termina com os atributos indicados possa ser comentado; caso contrário, devolve false (falso). 

String document.commentMarker(int atributo);

Devolve o marcador de comentários, usado em linhas únicas, para um determinado atributo. 

String document.commentStart(int atributo);

Devolve o marcador de início de comentários, usado em linhas múltiplas, para um determinado atributo. 

String document.commentEnd(int atributo);

Devolve o marcador de fim de comentários, usado em linhas múltiplas, para um determinado atributo. 

Range document.documentRange();

Devolve um intervalo que engloba todo o documento. 

Cursor documentEnd();

Devolve um cursor posicionado na última coluna da última linha do documento. 

bool isValidTextPosition(int linha, int coluna);
bool isValidTextPosition(Cursor cursor);

Devolve true (verdadeiro), se a posição atual do cursor estiver em uma posição de texto válida. Uma posição de texto é válida apenas se estiver localizada no início, no meio ou no fim de uma linha válida. Além disso, uma posição de texto é inválida se estiver localizada em um substituto Unicode.

Desde: KDE 5.0 

int document.attribute(int linha, int coluna);
int document.attribute(Cursor cursor);

Devolve o atributo na posição do cursor indicada. 

bool document.isAttribute(int linha, int coluna, int atributo);
bool document.isAttribute(Cursor cursor, int atributo);

Devolve true (verdadeiro), se o atributo na posição do cursor indicada for igual a atributo, caso contrário devolve false (falso). 

String document.attributeName(int linha, int coluna);
String document.attributeName(Cursor cursor);

Devolve o nome do atributo como um texto legível. Isto é igual ao nome itemData dos arquivos de realce de sintaxe. 

bool document.isAttributeName(int linha, int coluna, String nome);
bool document.isAttributeName(Cursor cursor, String nome);

Devolve true (verdadeiro), se o nome do atributo, numa dada posição do cursor, corresponder ao nome indicado, caso contrário devolve false (falso). 

String document.variable(String chave);

Devolve o valor da variável do documento identificada pela chave. Se a variável do documento não existir, o valor devolvido é um texto em branco. 

void document.setVariable(String chave, String valor);

Define o valor da variável do documento solicitada pela chave.

Veja também: Variáveis de documento do Kate

Desde: KDE 4.8 

int document.firstVirtualColumn(int linha);

Devolve a coluna virtual do primeiro caractere não-nulo na linha indicada, ou então -1 se a linha estiver em branco ou só tiver caracteres de espaços em branco. 

int document.lastVirtualColumn(int linha);

Devolve a coluna virtual do último caractere não-nulo na linha indicada, ou então -1 se a linha estiver em branco ou só tiver caracteres de espaços em branco. 

int document.toVirtualColumn(int linha, int coluna);
int document.toVirtualColumn(Cursor cursor);
Cursor document.toVirtualCursor(Cursor cursor);

Converte a posição do cursor “real” para uma posição virtual, retornando um int ou um objeto Cursor. 

int document.fromVirtualColumn(int linha, int colunaVirtual);
int document.fromVirtualColumn(Cursor cursorVirtual);
Cursor document.fromVirtualCursor(Cursor cursorVirtual);

Converte a posição virtual do cursor para uma posição do cursor “real”, retornando um int ou um objeto Cursor. 

Cursor document.anchor(int linha, int coluna, Char caractere);
Cursor document.anchor(Cursor cursor, Char caractere);

Pesquisa para trás pelo caractere indicado, começando na posição do cursor indicada. Por exemplo, se for passado o '(', como caractere, esta função irá devolver a posição do '(' de abertura. Isto implica uma contagem das referências, isto é, os outros '(...)' são ignorados. 

Cursor document.rfind(int linha, int coluna, String texto, int atributo = -1);
Cursor document.rfind(Cursor cursor, String texto, int atributo = -1);

Pesquisa para trás pelo texto indicado, com o atributo apropriado. O argumento atributo é ignorado se for igual a -1. O cursor devolvido é inválido, caso o texto não tenha sido encontrado. 

int document.defStyleNum(int linha, int coluna);
int document.defStyleNum(Cursor cursor);

Devolve o estilo padrão que é usado na posição do cursor indicada. 

bool document.isCode(int linha, int coluna);
bool document.isCode(Cursor cursor);

Devolve true (verdadeiro) se o atributo na posição do cursor indicada não for igual a todos os seguintes estilos: dsComment, dsString, dsRegionMarker, dsChar, dsOthers. 

bool document.isComment(int linha, int coluna);
bool document.isComment(Cursor cursor);

Devolve true se o atributo do caractere na posição do cursor for dsComment, caso contrário, devolve false. 

bool document.isString(int linha, int coluna);
bool document.isString(Cursor cursor);

Devolve true (verdadeiro) se o atributo do caractere na posição do cursor for dsString, caso contrário, devolve false (falso). 

bool document.isRegionMarker(int linha, int coluna);
bool document.isRegionMarker(Cursor cursor);

Devolve true (verdadeiro) se o atributo do caractere na posição do cursor for dsRegionMarker, caso contrário, devolve false (falso). 

bool document.isChar(int linha, int coluna);
bool document.isChar(Cursor cursor);

Devolve true (verdadeiro) se o atributo do caractere na posição do cursor for dsChar, caso contrário, devolve false (falso). 

bool document.isOthers(int linha, int coluna);
bool document.isOthers(Cursor cursor);

Devolve true (verdadeiro) se o atributo do caractere na posição do cursor for dsOthers, caso contrário, devolve false (falso). 

void document.indent(Range intervalo, int número);

Recua todas as linhas em intervalo por número de tabulações ou número vezes tabSize espaços, dependendo das preferências do usuário. O parâmetro número pode ser negativo.

A API do editor

Além da API de documento e visualização, existe uma API de editor geral que fornece funções para funcionalidades gerais de script do editor. 

String editor.clipboardText();

Retorna o texto que está atualmente na área de transferência global.

Desde: KDE Frameworks™ 5.50

String editor.clipboardHistory();

O editor mantém um histórico da área de transferência que contém até 10 entradas. Esta função retorna todas as entradas que estão atualmente no histórico da área de transferência.

Desde: KDE Frameworks™ 5.50

void editor.setClipboardText(String texto);

Define o conteúdo da área de transferência para texto. O texto será adicionado ao histórico da área de transferência.

Desde: KDE Frameworks™ 5.50