<chapter id="dev"> <chapterinfo> <authorgroup> <author >&TC.Hollingsworth; &TC.Hollingsworth.mail;</author> <othercredit role="translator" ><firstname >José</firstname ><surname >Pires</surname ><affiliation ><address ><email >zepires@gmail.com</email ></address ></affiliation ><contrib >Tradução</contrib ></othercredit > </authorgroup> </chapterinfo> <title >Melhorar o &kate;</title> <sect1 id="dev-intro"> <title >Introdução</title> <para >Como em qualquer editor de texto avançado, o &kate; oferece uma grande diversidade de formas para ampliar a sua funcionalidade. Poderá <link linkend="dev-scripting" >criar programa simples para adicionar funcionalidades com o JavaScript</link >, adicionar funcionalidades melhoradas ao componente de edição com os <link linkend="dev-part" >'Plugins' do Componente de Edição</link >, ou adicionar ainda mais funcionalidades ao editor propriamente dito com os <link linkend="dev-app" >'plugins' da aplicação &kate;, feitos em C++</link > ou <link linkend="dev-pate" >os 'plugins' do &pate;, feitos em Python</link >. Finalmente, assim que tiver melhorado o &kate;, está à vontade para <ulink url="http://kate-editor.org/join-us/" >se juntar a nós</ulink > e partilhar as suas melhorias com o mundo!</para> </sect1> <sect1 id="dev-scripting"> <title >Programar em JavaScript</title> <para >Desde o &kappname; 3.4, no &kde; 4.4, o componente de edição do &kappname; é facilmente extensível, através da criação de programas. A linguagem de programação é o ECMAScript (vulgarmente conhecido como JavaScript). O &kappname; suporta dois tipos de programas: os de indentação e os de linha de comandos. </para> <sect2 id="dev-scripting-indentation"> <title >Programas de Indentação</title> <para >Programas de indentação - também conhecidos por indentadores - formatam automaticamente o código-fonte enquanto escreve o texto. Por exemplo, depois de carregar na tecla Return, o nível de indentação costuma aumentar. </para> <para >As seguintes secções descrevem, passo-a-passo, como criar o esqueleto de um módulo de indentação simples. Como primeiro passo, crie um novo ficheiro <filename >*.js</filename >, chamado ⪚ <filename >javascript.js</filename > na pasta pessoal local <filename >$KDEHOME/share/apps/katepart/script/indentation</filename >. </para> <sect3 id="dev-scripting-indentation-header"> <title >O Cabeçalho do Programa de Indentação</title> <para >O cabeçalho do ficheiro <filename >javascript.js</filename > está incorporado num comentário e tem o seguinte formato <programlisting> /* kate-script * name: JavaScript * author: Nome de Exemplo <nome.exemplo@um.endereco.org> * license: BSD * revision: 1 * kate-version: 3.4 * type: indentation * required-syntax-style: javascript * indent-languages: javascript * priority: 0 * i18n-catalog: meu-catalogo * * Uma linha sem o símbolo ':' interrompe o processamento do cabeçalho. Isto é, poderá * adicionar mais algum texto aqui como, por exemplo, uma licença detalhada. */ </programlisting > Cada item será agora explicado em detalhe: <itemizedlist> <listitem ><para ><literal >kate-script</literal > [obrigatório]: Este texto tem de aparecer na primeira linha do ficheiro <filename >*.js</filename >, caso contrário o &kappname; irá ignorar o programa. </para ></listitem> <listitem ><para ><literal >name</literal > [obrigatório]: Este é o nome do modo de indentação que aparece no menu <menuchoice ><guimenu >Ferramentas</guimenu ><guimenuitem >Indentação</guimenuitem ></menuchoice > e na janela de configuração. </para ></listitem> <listitem ><para ><literal >author</literal > [opcional]: O nome e a informação de contacto do autor. </para ></listitem> <listitem ><para ><literal >license</literal > [opcional]: Forma curta da licença, como por exemplo BSD ou LGPLv3. </para ></listitem> <listitem ><para ><literal >revision</literal > [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado. </para ></listitem> <listitem ><para ><literal >kate-version</literal > [obrigatório]: A versão mínima do &kappname; necessária. </para ></listitem> <listitem ><para ><literal >required-syntax-style</literal > [opcional]: Uma lista, separada por vírgulas, dos estilos de realce de sintaxe obrigatórios. Isto é importante para os módulos de indentação que se baseiam em alguma informação específica de realce no documento. Se for indicado um estilo de sintaxe obrigatório, o módulo só ficará disponível quando estiver o realce apropriado seleccionado. Isto evita algum <quote >comportamento indefinido</quote > causado pela utilização da indentação sem o esquema de realce esperado. Por exemplo, a indentação de Ruby tira partido disto nos ficheiros <filename >ruby.js</filename > e <filename >ruby.xml</filename >. </para ></listitem> <listitem ><para ><literal >indent-languages</literal > [opcional]: Uma lista, separada por vírgulas, de estilos de sintaxe que este módulo consegue indentar correctamente, ⪚: c++, java. </para ></listitem> <listitem ><para ><literal >priority</literal > [opcional]: Se existirem vários módulos de indentação adequados para um determinado ficheiro de realce, este campo decide qual deverá ser usado por omissão. </para ></listitem> <listitem ><para ><literal >i18n-catalog</literal > [opcional]: Catálogo de mensagens adicional (ficheiro <literal >.po</literal >) carregado para a tradução de indentações de terceiros.</para ></listitem> </itemizedlist> </para> <para >O &kappname; lê todos os pares no formato <quote ><replaceable >chave</replaceable >:<replaceable >valor</replaceable ></quote > até que não consiga encontrar mais nenhum símbolo de ':'. Isto implica que o cabeçalho poderá conter texto arbitrário, como uma licença, tal como aparece no exemplo. </para> </sect3> <sect3 id="dev-scripting-indentation-body"> <title >O Código-Fonte da Indentação</title> <para >Tendo definido o cabeçalho, esta secção explica como é que funciona a programação de indentações em si. O esqueleto básico do código parece-se com o seguinte: <programlisting> require("range.js"); caracteresActivacao = "{}/:;"; function indent(linha, larguraIndentacao, carácter) { // invocado para cada linha nova (carácter == '\n') e todos os caracteres indicados na // variável global 'caracteresActivacao'. Ao invocar o <menuchoice ><guimenu >Ferramentas</guimenu ><guimenuitem >Alinhar</guimenuitem ></menuchoice> // a variável 'carácter' está em branco, i.e. carácter == ''. // // ver também: API de Programação return -2; } </programlisting > A função <function >indent()</function > tem três parâmetros: <itemizedlist > <listitem ><para ><literal >linha</literal >: a linha que tem de ser indentada</para ></listitem > <listitem ><para ><literal >larguraIndentacao</literal >: o número de espaços correspondentes a cada indentação</para ></listitem > <listitem ><para ><literal >carácter</literal >: ou um carácter de mudança de linha (<literal >ch == '\n'</literal >), algum dos caracteres de activação indicados em <literal >caracteresActivacao</literal > ou vazio, caso o utilizador tenha invocado a acção <menuchoice ><guimenu >Ferramentas</guimenu ><guimenuitem >Alinhar</guimenuitem ></menuchoice >.</para ></listitem > </itemizedlist > O valor devolvido pela função <function >indent()</function > define como é que a linha será indentada. Se o valor devolvido for um número inteiro, é interpretado da seguinte forma: <itemizedlist > <listitem ><para >valor devolvido <literal >-2</literal >: não fazer nada</para ></listitem > <listitem ><para >valor devolvido <literal >-1</literal >: mantém a indentação (procura pela linha não-vazia anterior)</para ></listitem > <listitem ><para >valor devolvido <literal > 0</literal >: números >= 0 definem a largura de indentação em espaços</para ></listitem > </itemizedlist > Em alternativa, poderá ser devolvida uma lista com dois elementos: <itemizedlist > <listitem ><para ><literal >return [ indentação, alinhamento ];</literal ></para ></listitem > </itemizedlist > Nesse caso, o primeiro elemento é a profundidade de indentação, tendo o mesmo significado que os valores especiais. Contudo, o segundo elemento é um valor absoluto que representa uma coluna para o <quote >alinhamento</quote >. Se este valor for maior que o valor de indentação, a diferença representa um número de espaços a adicionar após a indentação do primeiro parâmetro. Caso contrário, o segundo número será ignorado. A utilização de tabulações e espaços na indentação é normalmente referida como sendo um <quote >modo misto</quote >. </para> <para >Considere o seguinte exemplo: Assuma que usa as tabulações para indentar, e que o tamanho da tabulação é de 4. Aqui, o <tab> representa uma tabulação e o '.' representa um espaço: <programlisting> 1: <tab><tab>xpto("olá", 2: <tab><tab>......."mundo"); </programlisting > Ao indentar a linha 2, a função <function >indent()</function > devolve [8, 15]. Em função disso, são introduzidas duas tabulações para indentar 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 ficheiro seja visto com outro tamanho de tabulação. </para> <para >Uma instalação predefinida do &kde; fornece o &kappname; com vários módulos de indentação. O código-fonte correspondente em JavaScript poderá ser encontrado em <filename >$KDEDIR/share/apps/katepart/script/indentation</filename >. </para> <para >A criação de um módulo de indentação necessita que actualize os programas, de modo a ver se as alterações se comportam de forma adequada. Em vez de reiniciar a aplicação, basta ir para a linha de comandos e invocar o comando <command >reload-scripts</command >. </para> <para >Se criar programas úteis, por favor considere a hipótese de contribuir com eles para o Projecto do &kappname;, <ulink url="mailto:kwrite-devel@kde.org" >contactando para tal a lista de correio</ulink >. </para> </sect3> </sect2> <sect2 id="dev-scripting-command-line"> <title >Programas da Linha de Comandos</title> <para >Como é difícil satisfazer as necessidades de todos, o &kappname; suporta algumas ferramentas auxiliares para manipular rapidamente o texto, usando para tal a <link linkend="advanced-editing-tools-commandline" >linha de comandos incorporada</link >. Por exemplo, o comando <command >sort</command > está implementado como um programa. Esta secção explica como criar ficheiros <filename >*.js</filename > que melhoram o &kappname; com algumas funções auxiliares arbitrárias. </para> <para >Os programas da linha de comandos estão localizados na mesma pasta que os programas de indentação. Como tal, como primeiro passo, crie um ficheiro <filename >*.js</filename > novo, chamado <filename >utilitários.js</filename > na pasta pessoal local, em <filename >$KDEHOME/share/apps/katepart/script/commands</filename >. </para> <sect3 id="dev-scripting-command-line-header"> <title >O Cabeçalho do Programa da Linha de Comandos</title> <para >O cabeçalho de cada programa da linha de comandos está incorporado como um comentário e encontra-se no seguinte formato <programlisting> /* kate-script * author: Nome de Exemplo <nome.exemplo@um.endereco.org> * license: BSD * revision: 1 * kate-version: 3.4 * type: commands * functions: sort, format-paragraph * i18n-catalog: meu-catalogo * * Uma linha sem o símbolo ':' interrompe o processamento do cabeçalho. Isto é, poderá adicionar * algum texto opcional aqui como, por exemplo, uma licença detalhada. */ </programlisting > Cada um dos elementos será explicado em detalhe: <itemizedlist> <listitem ><para ><literal >kate-script</literal > [obrigatório]: Este texto tem de aparecer na primeira linha do ficheiro <filename >*.js</filename >, caso contrário o &kappname; irá ignorar o programa.</para ></listitem> <listitem ><para ><literal >author</literal > [opcional]: O nome e a informação de contacto do autor.</para ></listitem> <listitem ><para ><literal >license</literal > [opcional]: Forma curta da licença, como por exemplo BSD ou LGPLv3.</para ></listitem> <listitem ><para ><literal >revision</literal > [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado.</para ></listitem> <listitem ><para ><literal >kate-version</literal > [obrigatório]: A versão mínima do &kappname; necessária.</para ></listitem> <listitem ><para ><literal >functions</literal > [obrigatório]: Uma lista, separada por vírgulas, dos comandos do programa.</para ></listitem> <listitem ><para ><literal >i18n-catalog</literal > [opcional]: Catálogo de mensagens adicional (ficheiro <literal >.po</literal >) carregado para a tradução dos programas de terceiros.</para ></listitem> </itemizedlist> </para> <para >O &kappname; lê todos os pares no formato <quote ><replaceable >chave</replaceable >:<replaceable >valor</replaceable ></quote >, até que não consiga encontrar mais nenhum símbolo de dois-pontos. Isto implica que o cabeçalho possa conter algum texto arbitrário, como a licença que aparece no exemplo.O valor da chave 'functions' é uma lista, separada por vírgulas, de comandos para a linha de comandos. Isto significa que um único programa poderá conter um conjunto arbitrário de comandos. Cada uma das funções está disponível no &kappname; através da <link linkend="advanced-editing-tools-commandline" >linha de comandos incorporada</link >. </para> </sect3> <sect3 id="dev-scripting-command-line-body"> <title >O Código-Fonte do Programa</title> <para >Todas as funções indicadas no cabeçalho terão de estar implementadas no programa. Por exemplo, o ficheiro de programa do exemplo acima tem de implementar as duas funções <command >ordenar</command > e <command >formatar-paragrafo</command >. Todas as funções têm a seguinte sintaxe: <programlisting >// bibliotecas necessárias do Katepart, p.ex. o range.js se usar o Range require ("range.js"); function <nome>(arg1, arg2, ...) { // ... implementação, ver também: API de Programação } </programlisting> </para> <para >Os argumentos na linha de comandos são passados à função como <parameter >arg1</parameter >, <parameter >arg2</parameter >, etc. Para poder fornecer a documentação para cada comando, basta implementar a função '<function >help</function >' da seguinte forma: <programlisting> function help(comando) { if (comando == "ordenar") { return i18n("Ordena o texto seleccionado."); } else if (cmd == "...") { // ... } } </programlisting > Se executar <command >help ordenar</command > na linha de comandos, irá invocar esta função 'help' com o argumento <parameter >comando</parameter > configurado com o comando indicado, &ie; <parameter >comando == "ordenar"</parameter >. O &kappname; irá então apresentar o texto devolvido como documentação para o utilizador. Certifique-se que <link linkend="dev-scripting-api-i18n" >traduz os textos</link >. </para> <sect4 id="dev-scripting-command-line-shortcuts"> <title >Associar Combinações de Teclas</title> <para >Para poder atribuir atalhos de teclado, o programa terá de fornecer uma chamada chamada <literal >action</literal > da seguinte forma: <programlisting> function action(comando) { var a = new Object(); if (comando == "ordenar") { a.text = i18n("Ordenar o Texto Seleccionado"); a.icon = ""; a.category = ""; a.interactive = false; a.shortcut = ""; } else if (comando == "descerLinhas") { // repetir para a acção seguinte } return a; } </programlisting > O parâmetro <literal >comando</literal > da função indica qual o comando para o qual se pede o atalho de teclado respectivo. Existem vários campos que terá de indicar no objecto de JavaScript devolvido: <itemizedlist> <listitem ><para ><literal >a.text</literal > [obrigatório]: O texto que aparece no menu <guimenu >Ferramentas</guimenu > > <guimenu >Programas</guimenu >. Certifique-se que usa o <literal >i18n</literal > para as traduções.</para ></listitem> <listitem ><para ><literal >a.icon</literal > [opcional]: O ícone aparece a seguir ao texto no menu. Todos os nomes de ícones do &kde; poderão ser aqui usados.</para ></listitem> <listitem ><para ><literal >a.category</literal > [opcional]: Se for indicada uma categoria, o programa aparece num submenu. Certifique-se que usa o <literal >i18n</literal > para as traduções.</para ></listitem> <listitem ><para ><literal >a.interactive</literal > [opcional]: Se o programa precisa de interacção por parte do utilizador, configure este valor como <literal >true</literal > (verdadeiro).</para ></listitem> <listitem ><para ><literal >a.shortcut</literal > [opcional]: A combinação de teclas indicada aqui é o atalho de teclado predefinido. Por exemplo: Ctrl+Alt+T. Veja a <ulink url="http://qt-project.org/doc/qt-4.8/qt.html#Key-enum" >documentação do Qt</ulink > para mais detalhes.</para ></listitem> </itemizedlist> </para> <para >Criar um programa para a linha de comandos obriga a actualizar os programas, de modo a ver se as alterações funcionam apropriadamente. Em vez de reiniciar a aplicação, basta mudar para a linha de comandos e invocar o comando <command >reload-scripts</command >. </para> <para >Se criar programas úteis, por favor considere a hipótese de contribuir com eles para o Projecto do &kappname;, <ulink url="mailto:kwrite-devel@kde.org" >contactando para tal a lista de correio</ulink >. </para> </sect4> </sect3> </sect2> <sect2 id="dev-scripting-api"> <title >API de Programação</title> <para >A API de programação aqui apresentada está disponível em todos os programas, &ie; os programas de indentação e os comandos da consola. O <classname >Cursor</classname > e o <classname >Range</classname > são fornecidos através de ficheiros de bibliotecas no <filename >$KDEDIR/share/apps/katepart/libraries</filename >. Se quiser usá-los no seu programa, o que será necessário para usar algumas das funções do <classname >Document</classname > ou do <classname >View</classname >, inclua por favor a biblioteca necessária, usando: <programlisting >// bibliotecas em JS do katepart necessárias, p.ex. o "range.js" se usar o Range require ("range.js"); </programlisting> </para> <para >Para extender a API-padrão de programação com funções e protótipos próprio, basta criar um ficheiro novo na pasta de configuração local do &kde;, em <filename >$KDEHOME/share/apps/katepart/libraries</filename > e inclua-a no seu programa, usando: <programlisting >require ("nome-do-meu-programa.js"); </programlisting> </para> <para >Para extender os protótipos existentes, como o <classname >Cursor</classname > ou o <classname >Range</classname >, a forma recomendada é <emphasis >não</emphasis > modificar os ficheiros <filename >*.js</filename > globais. Em vez disso, altere o protótipo do <classname >Cursor</classname > em JavaScript, após o <filename >cursor.js</filename > que é incluído no seu programa com o <literal >require</literal >. </para> <sect3 id="dev-scripting-api-prototypes"> <title >Cursores e Intervalos</title> <para >Como o &kappname; é um editor de texto, toda a API de programação é baseada em cursores e intervalos, sempre que possível. Um cursor é um simples tuplo <literal >(linha, coluna)</literal > 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 detalhe nas secções seguintes. </para> <sect4 id="dev-scripting-api-cursors"> <title >O Protótipo do Cursor</title> <variablelist ><varlistentry> <term ><synopsis >Cursor(); </synopsis ></term> <listitem ><para >Construtor. Devolve um Cursor na posição <literal >(0, 0)</literal >.</para> <para >Exemplo: <function >var cursor = new Cursor();</function > </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Cursor(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Construtor. Devolve um Cursor na posição (linha, coluna). </para> <para >Exemplo: <function >var cursor = new Cursor(3, 42);</function > </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Cursor(<parameter >Cursor <replaceable >outro</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Construtor de cópia. Devolve uma cópia do cursor <replaceable >outro</replaceable >. </para> <para >Exemplo: <function >var copia = new Cursor(outro);</function > </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Cursor Cursor.clone(); </synopsis ></term> <listitem ><para >Devolve uma cópia do cursor.</para> <para >Exemplo: <function >var clone = cursor.clone();</function > </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Cursor.setPosition(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Configura a posição do cursor em <replaceable >linha</replaceable > e <replaceable >coluna</replaceable >.</para> <para >Desde: &kde; 4.11 </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Cursor.isValid(); </synopsis ></term> <listitem ><para >Verifica se o cursor é válido. O cursor é inválido no caso em que a linha e/ou coluna sejam iguais a <literal >-1</literal >. </para> <para >Exemplo: <function >var valido = cursor.isValid();</function > </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Cursor Cursor.invalid(); </synopsis ></term> <listitem ><para >Devolve um novo cursor inválido, localizado em <literal >(-1, -1)</literal >. </para> <para >Exemplo: <function >var cursorInvalido = cursor.invalid();</function > </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int Cursor.compareTo(<parameter >Cursor <replaceable >outro</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Compara este cursor com o cursor <replaceable >outro</replaceable >. Devolve <itemizedlist> <listitem ><para ><literal >-1</literal >, se este cursor for localizado antes do cursor <replaceable >outro</replaceable >,</para ></listitem> <listitem ><para ><literal >0</literal >, se ambos os cursores forem iguais e</para ></listitem> <listitem ><para ><literal >+1</literal >, se este cursor se localizar a seguir ao cursor <replaceable >outro</replaceable >.</para ></listitem> </itemizedlist> </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Cursor.equals(<parameter >Cursor <replaceable >outro</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se este o cursor e o <replaceable >outro</replaceable > forem iguais, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String Cursor.toString(); </synopsis ></term> <listitem ><para >Devolve o cursor como um texto no formato <quote ><literal >Cursor(linha, coluna)</literal ></quote >. </para ></listitem> </varlistentry ></variablelist> </sect4> <sect4 id="dev-scripting-api-ranges"> <title >O Protótipo do Intervalo</title> <variablelist ><varlistentry> <term ><synopsis >Range(); </synopsis ></term> <listitem ><para >Construtor. A invocação de <literal >new Range()</literal > devolve um intervalo Range de (0, 0) - (0, 0). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Range(<parameter >Cursor <replaceable >inicio</replaceable ></parameter >, <parameter >Cursor <replaceable >fim</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Construtor. A invocação de <literal >new Range(<replaceable >início</replaceable >, <replaceable >fim</replaceable >)</literal > devolve o intervalo (<replaceable >início</replaceable >, <replaceable >fim</replaceable >). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Range(<parameter >int <replaceable >linhaInicial</replaceable ></parameter >, <parameter >int <replaceable >colunaInicial</replaceable ></parameter >, <parameter >int <replaceable >linhaFinal</replaceable ></parameter >, <parameter >int <replaceable >colunaFinal</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Construtor. A invocação de <literal >new Range(<replaceable >linhaInicial</replaceable >, <replaceable >colunaInicial</replaceable >, <replaceable >linhaFinal</replaceable >, <replaceable >colunaFinal</replaceable >)</literal > devolve um intervalo Range de (<replaceable >linhaInicial</replaceable >, <replaceable >colunaInicial</replaceable >) até (<replaceable >linhaFinal</replaceable >, <replaceable >colunaFinal</replaceable >). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Range(<parameter >Range <replaceable >outro</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Construtor de cópia. Devolve uma cópia do intervalo Range <replaceable >outro</replaceable >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Range Range.clone(); </synopsis ></term> <listitem ><para >Devolve uma cópia do intervalo. </para> <para >Exemplo: <function >var clone = intervalo.clone();</function > </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Range.isEmpty(); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se tanto o cursor de início como o de fim forem iguais. </para> <para >Exemplo: <function >var vazio = intervalo.isEmpty();</function > </para> <para >Desde: &kde; 4.11 </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Range.isValid(); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se tanto o cursor de início como o de fim forem válidos, caso contrário devolve <literal >false</literal > (falso). </para> <para >Exemplo: <function >var valido = intervalo.isValid();</function > </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Range Range.invalid(); </synopsis ></term> <listitem ><para >Devolve o intervalo Range de (-1, -1) até (-1, -1). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Range.contains(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <constant >true</constant > (verdadeiro) se este intervalo contiver a posição do cursor, caso contrário devolve <constant >false</constant >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Range.contains(<parameter >Range <replaceable >outro</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se este intervalo contiver o intervalo Range <replaceable >outro</replaceable >, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Range.containsColumn(<parameter >int <replaceable >coluna</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se a <replaceable >coluna</replaceable > estiver no intervalo semi-aberto <literal >[início.coluna, fim.coluna)</literal >, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Range.containsLine(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro) se a <replaceable >linha</replaceable > estiver no intervalo semi-aberto <literal >[início.linha, fim.linha)</literal >, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Range.overlaps(<parameter >Range <replaceable >outro</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se este intervalo e o intervalo <replaceable >outro</replaceable > partilharem uma região em comum, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Range.overlapsLine(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se a <replaceable >linha</replaceable > estiver no intervalo <literal >[início.linha, fim.linha]</literal >, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Range.overlapsColumn(<parameter >int <replaceable >coluna</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se a <replaceable >coluna</replaceable > estiver no intervalo <literal >[início.coluna, fim.coluna]</literal >, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Range.onSingleLine(); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se o intervalo começar e acabar na mesma linha, &ie; se <replaceable >Range.start.line == Range.end.line</replaceable >. </para> <para >Desde: &kde; 4.9 </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool Range.equals(<parameter >Range <replaceable >outro</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se este intervalo e o intervalo <replaceable >outro</replaceable > forem iguais, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String Range.toString(); </synopsis ></term> <listitem ><para >Devolve o intervalo como um texto no formato <quote ><literal >Range(Cursor(linha, coluna), Cursor(linha, coluna))</literal ></quote >. </para ></listitem> </varlistentry ></variablelist> </sect4> </sect3> <sect3 id="dev-scripting-api-global"> <title >Funções Globais</title> <para >Esta secção apresenta todas as funções globais.</para> <sect4 id="dev-scripting-api-includes"> <title >Ler & Incluir os Ficheiros</title> <variablelist ><varlistentry> <term ><synopsis >String read(<parameter >String <replaceable >ficheiro</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Irá procurar pelo <replaceable >ficheiro</replaceable > indicado em relação à pasta <literal >katepart/script/files</literal > e irá devolver o seu conteúdo como texto. </para ></listitem> </varlistentry ></variablelist> <variablelist ><varlistentry> <term ><synopsis >void require(<parameter >String <replaceable >ficheiro</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Irá procurar pelo <replaceable >ficheiro</replaceable > indicado em relação à pasta <literal >katepart/script/libraries</literal > e este será avaliado. O <literal >require</literal > está protegido internamente contra inclusões múltiplas do mesmo <replaceable >ficheiro</replaceable >. </para> <para >Desde: &kde; 4.10 </para> </listitem> </varlistentry ></variablelist> </sect4> <sect4 id="dev-scripting-api-debug"> <title >Depuração</title> <variablelist ><varlistentry> <term ><synopsis >void debug(<parameter >String <replaceable >texto</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Imprime o <replaceable >texto</replaceable > no <literal >stdout</literal >, mais precisamente na consola que lança a aplicação. </para ></listitem> </varlistentry ></variablelist> </sect4> <sect4 id="dev-scripting-api-i18n"> <title >Tradução</title> <para >Para um suporte regional completo, existem diversas funções para traduzir os textos nos programas, nomeadamente o <literal >i18n</literal >, o <literal >i18nc</literal >, o <literal >i18np</literal > e o <literal >i18ncp</literal >. Estas funções comportam-se exactamente como as <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n" > funções de tradução do &kde;</ulink >. </para> <para >As funções de tradução convertem os textos indicados ao sistema de traduções do &kde; para a língua usada na aplicação. Os textos nos programas que são desenvolvidos no âmbito do código oficial do &kappname; são automaticamente extraídos e preparados para traduções. Por outras palavras, como programador do &kappname;, não terá de se preocupar com a extracção e tradução das mensagens. Contudo, para programas de terceiros, desenvolvidos fora do &kde;, terá de extrair e traduzir você mesmo a as mensagens. Em conjunto com os seus programas, terá de distribuir também um catálogo de traduções que inclui todos os textos traduzidos. Para além disso, o cabeçalho do seu programa terá de indicar explicitamente o catálogo a carregar com a indicação do <literal >i18n-catalog</literal >. </para> <variablelist ><varlistentry> <term ><synopsis >void i18n(<parameter >String <replaceable >texto</replaceable ></parameter >, <replaceable >arg1</replaceable >, ...); </synopsis ></term> <listitem ><para >Traduz o <replaceable >texto</replaceable > na língua usada pela aplicação. Os argumentos <replaceable >arg1</replaceable >, ..., são opcionais e usados para substituir os itens <literal >%1</literal >, <literal >%2</literal >, etc.</para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >void i18nc(<parameter >String <replaceable >contexto</replaceable ></parameter >, <parameter >String <replaceable >texto</replaceable ></parameter >, <replaceable >arg1</replaceable >, ...); </synopsis ></term> <listitem ><para >Traduz o <replaceable >texto</replaceable > na língua usada pela aplicação. Para ale´m disso, o texto do <replaceable >contexto</replaceable > fica visível aos tradutores para que possam dar uma tradução mais adequada. Os argumentos <replaceable >arg1</replaceable >, ..., são opcionais e são usados para substituir os itens de substituição <literal >%1</literal >, <literal >%2</literal >, etc.</para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >void i18np(<parameter >String <replaceable >singular</replaceable ></parameter >, <parameter >String <replaceable >plural</replaceable ></parameter >, <parameter >int <replaceable >número</replaceable ></parameter >, <replaceable >arg1</replaceable >, ...); </synopsis ></term> <listitem ><para >Traduz tanto o texto <replaceable >singular</replaceable > como o <replaceable >plural</replaceable > para a língua usada pela aplicação, dependendo do <replaceable >número</replaceable > indicado. Os argumentos <replaceable >arg1</replaceable >, ..., são opcionais e usados para substituir os itens de substituição <literal >%1</literal >, <literal >%2</literal >, etc.</para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >void i18ncp(<parameter >String <replaceable >contexto</replaceable ></parameter >, <parameter >String <replaceable >singular</replaceable ></parameter >, <parameter >String <replaceable >plural</replaceable ></parameter >, <parameter >int <replaceable >número</replaceable ></parameter >, <replaceable >arg1</replaceable >, ...); </synopsis ></term> <listitem ><para >Traduz tanto o texto <replaceable >singular</replaceable > como o <replaceable >plural</replaceable > para a língua usada pela aplicação, dependendo do <replaceable >número</replaceable > indicado. Adicionalmente, o texto do <replaceable >contexto</replaceable > é visível para as tradutores, para que possam fornecer uma tradução mais adequada. Os argumentos <replaceable >arg1</replaceable >, ..., são opcionais e são usados para substituir os itens <literal >%1</literal >, <literal >%2</literal >, etc.</para ></listitem> </varlistentry ></variablelist> </sect4> </sect3> <sect3 id="dev-scripting-api-view"> <title >A API do View</title> <para >Sempre que um programa está a ser executado, existe uma variável global <quote ><literal >view</literal ></quote > que representa a área de edição activa no momento. Segue-se uma lista com todas as funções disponíveis para o View. <variablelist ><varlistentry> <term ><synopsis ><function >Cursor view.cursorPosition()</function > </synopsis ></term> <listitem ><para >Devolve a posição actual do cursor na janela.</para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >void view.setCursorPosition(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); void view.setCursorPosition(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Altera a posição actual do cursor para uma (linha, coluna) qualquer ou para o cursor indicado. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Cursor view.virtualCursorPosition(); </synopsis ></term> <listitem ><para >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 actual. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >void view.setVirtualCursorPosition(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); void view.setVirtualCursorPosition(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Altera a posição actual do cursor virtual para uma (linha, coluna) qualquer ou para o cursor indicado. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String view.selectedText(); </synopsis ></term> <listitem ><para >Devolve o texto seleccionado. Se não estiver nenhum texto seleccionado, o texto devolvido vem vazio. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool view.hasSelection(); </synopsis ></term> <listitem ><para >Devolve <constant >true</constant > (verdadeiro) se a janela contiver algum texto seleccionado, caso contrário devolve <constant >false</constant >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Range view.selection(); </synopsis ></term> <listitem ><para >Devolve o intervalo de texto seleccionado. O intervalo devolvido é inválido, caso não esteja seleccionado nenhum texto. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >void view.setSelection(<parameter >Range <replaceable >intervalo</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Altera o texto seleccionado para o intervalo indicado. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >void view.removeSelectedText(); </synopsis ></term> <listitem ><para >Remove o texto seleccionado. Se a janela não tiver nenhuma selecção feita, isto não faz nada. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >void view.selectAll(); </synopsis ></term> <listitem ><para >Selecciona o texto por inteiro no documento. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >void view.clearSelection(); </synopsis ></term> <listitem ><para >Limpa a selecção de texto actual, sem remover o texto. </para ></listitem> </varlistentry ></variablelist> </para> </sect3> <sect3 id="dev-scripting-api-document"> <title >A API do Document</title> <para >Sempre que está a executar um programa, existe uma variável global <quote ><literal >document</literal ></quote > que representa o documento activo no momento. Segue-se uma lista com todas as funções disponíveis para o Document. <variablelist ><varlistentry> <term ><synopsis >String document.fileName(); </synopsis ></term> <listitem ><para >Devolve o nome do ficheiro do documento, ou então um texto vazio para as janelas de texto ainda por gravar. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.url(); </synopsis ></term> <listitem ><para >Devolve o URL completo do documento, ou então um texto vazio para as janelas de texto ainda por gravar. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.mimeType(); </synopsis ></term> <listitem ><para >Devolve o tipo MIME do documento, ou então o tipo <literal >application/octet-stream</literal > se não for encontrado qualquer tipo MIME apropriado. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.encoding(); </synopsis ></term> <listitem ><para >Devolve a codificação usada actualmente para gravar o ficheiro. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.highlightingMode(); </synopsis ></term> <listitem ><para >Devolve o modo de realce global usado para todo o documento. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.highlightingModeAt(<parameter >Cursor <replaceable >posição</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve o modo de realce usado na posição do cursor indicada do documento. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Array document.embeddedHighlightingModes(); </synopsis ></term> <listitem ><para >Devolve uma lista com os modos de realce incorporados neste documento. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.isModified(); </synopsis ></term> <listitem ><para >Devolve <constant >true</constant > (verdadeiro) se o documento tiver algumas alterações por gravar, caso contrário devolve <constant >false</constant >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.text(); </synopsis ></term> <listitem ><para >Devolve o conteúdo inteiro do documento numa única sequência de texto. As mudanças de linha estão marcadas com o carácter de mudança de linha <quote ><literal >\n</literal ></quote >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.text(<parameter >int <replaceable >daLinha</replaceable ></parameter >, <parameter >int <replaceable >daColuna</replaceable ></parameter >, <parameter >int <replaceable >ateLinha</replaceable ></parameter >, <parameter >int <replaceable >ateColuna</replaceable ></parameter >); String document.text(<parameter >Cursor <replaceable >de</replaceable ></parameter >, <parameter >Cursor <replaceable >ate</replaceable ></parameter >); String document.text(<parameter >Range <replaceable >intervalo</replaceable ></parameter >); </synopsis ></term> <listitem ><para >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. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.line(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >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. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.wordAt(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); String document.wordAt(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve a palavra na posição do cursor indicada. </para ></listitem> </varlistentry> <varlistentry> <term> <synopsis >Range document.wordRangeAt(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); Range document.wordRangeAt(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis> </term> <listitem ><para >Devolve o intervalo da palavra na posição indicada do cursor. O intervalo devolvido é inválido (ver com 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. </para> <para >Desde: &kde; 4.9 </para> </listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.charAt(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); String document.charAt(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve o carácter na posição do cursor indicada. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.firstChar(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve o primeiro carácter da <replaceable >linha</replaceable > indicada que não seja um espaço em branco. O primeiro carácter encontra-se na coluna 0. Se a linha estiver em branco ou só tiver espaços em branco, o texto devolvido vem vazio. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.lastChar(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve o último carácter da <replaceable >linha</replaceable > indicada que não seja um espaço em branco. O primeiro carácter encontra-se na coluna 0. Se a linha estiver em branco ou só tiver espaços em branco, o texto devolvido vem vazio. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.isSpace(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); bool document.isSpace(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se o carácter na posição indicada do cursor for um espaço em branco, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.matchesAt(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >, <parameter >String <replaceable >texto</replaceable ></parameter >); bool document.matchesAt(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >, <parameter >String <replaceable >texto</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro) se o <replaceable >texto</replaceable > indicado corresponder à posição indicada do cursor, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.startsWith(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >String <replaceable >texto</replaceable ></parameter >, <parameter >bool <replaceable >ignorarEspacos</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro) se a linha começar por <replaceable >texto</replaceable >, caso contrário devolve <literal >false</literal > (falso). O argumento <replaceable >ignorarEspacos</replaceable > controla se os espaços envolventes são ignorados ou não. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.endsWith(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >String <replaceable >texto</replaceable ></parameter >, <parameter >bool <replaceable >ignorarEspacos</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), caso a linha termine em <replaceable >texto</replaceable >, caso contrário devolve <literal >false</literal > (falso). O argumento <replaceable >ignorarEspacos</replaceable > controla se os espaços envolventes são ignorados. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.setText(<parameter >String <replaceable >texto</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Altera o texto do documento por inteiro. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.clear(); </synopsis ></term> <listitem ><para >Limpa o texto no documento por inteiro. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.truncate(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); bool document.truncate(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Trunca a linha indicada, na coluna ou posição do cursor indicadas. Devolve <literal >true</literal > (verdadeiro) em caso de sucesso ou <literal >false</literal > (falso) se a linha não estiver dentro do intervalo do documento. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.insertText(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >, <parameter >String <replaceable >texto</replaceable ></parameter >); bool document.insertText(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >, <parameter >String <replaceable >texto</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Insere o <replaceable >texto</replaceable > na posição do cursor indicada. Devolve <literal >true</literal >, em caso de sucesso, ou <literal >false</literal > (falso), se o documento estiver apenas para leitura. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.removeText(<parameter >int <replaceable >daLinha</replaceable ></parameter >, <parameter >int <replaceable >dacoluna</replaceable ></parameter >, <parameter >int <replaceable >ateLinha</replaceable ></parameter >, <parameter >int <replaceable >ateColuna</replaceable ></parameter >); bool document.removeText(<parameter >Cursor <replaceable >de</replaceable ></parameter >, <parameter >Cursor <replaceable >ate</replaceable ></parameter >); bool document.removeText(<parameter >Range <replaceable >intervalo</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Remove o texto no intervalo indicado. Devolve <literal >true</literal > (verdadeiro), em caso de sucesso, ou <literal >false</literal > (falso), se o documento estiver no modo apenas para leitura. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.insertLine(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >String <replaceable >texto</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Insere o texto na linha indicada. Devolve <literal >true</literal > (verdadeiro), em caso de sucesso, ou <literal >false</literal > (falso), caso o documento esteja apenas para leitura ou se a linha não estiver no intervalo do documento. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.removeLine(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Remove a linha de texto indicada. Devolve <literal >true</literal > (verdadeiro), em caso de sucesso, ou <literal >false</literal > (falso), caso o documento esteja no modo apenas para leitura ou se a linha não estiver no intervalo do documento. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.wrapLine(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); bool document.wrapLine(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Reparte a linha na posição indicada pelo cursor. Devolve <literal >true</literal > (verdadeiro) em caso de sucesso ou <literal >false</literal > (falso) se ⪚ a linha < 0. </para> <para >Desde: &kde; 4.9 </para> </listitem> </varlistentry> <varlistentry> <term ><synopsis >void document.joinLines(<parameter >int <replaceable >linhaInicial</replaceable ></parameter >, <parameter >int <replaceable >linhaFinal</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Junta as linhas de <replaceable >linhaInicial</replaceable > até <replaceable >linhaFinal</replaceable >. Duas linhas de texto sucessivas estão sempre separadas por um espaço em branco. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.lines(); </synopsis ></term> <listitem ><para >Devolve o número de linhas do documento. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.length(); </synopsis ></term> <listitem ><para >Devolve o número de caracteres do documento. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.lineLength(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve o comprimento da <replaceable >linha</replaceable >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >void document.editBegin(); </synopsis ></term> <listitem ><para >Inicia um grupo de edição para agrupar operações a desfazer/refazer. Certifique-se que invoca sempre o <function >editEnd()</function > tantas vezes como invoca o <function >editBegin()</function >. A invocação do <function >editBegin()</function > usa um contador de referências interno, &ie; esta chamada pode ser encadeada. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >void document.editEnd(); </synopsis ></term> <listitem ><para >Termina um grupo de edição. A última invocação do <function >editEnd()</function > (&ie;, a correspondente à primeira chamada do <function >editBegin()</function >) termina o passo de edição. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.firstColumn(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve a primeira coluna não em branco para a <replaceable >linha</replaceable > indicada. Se só existirem espaços em branco na linha, o valor devolvido é <literal >-1</literal >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.lastColumn(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve a última coluna que não esteja em branco para a <replaceable >linha</replaceable > indicada. Se só existirem espaços em branco na linha, o valor devolvido é <literal >-1</literal >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.prevNonSpaceColumn(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); int document.prevNonSpaceColumn(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve a coluna com caracteres não-brancos que começa na posição de cursor indicada e pesquisa para trás. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.nextNonSpaceColumn(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); int document.nextNonSpaceColumn(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve a coluna com caracteres não-brancos que começa na posição de cursor indicada e pesquisa para a frente. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.prevNonEmptyLine(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve a primeira linha não-vazia que contém caracteres não-nulos, pesquisando depois para trás. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.nextNonEmptyLine(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve a primeira linha não-vazia que contém caracteres não-nulos, pesquisando depois para a frente. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.isInWord(<parameter >String <replaceable >carácter</replaceable ></parameter >, <parameter >int <replaceable >atributo</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), caso o <replaceable >carácter</replaceable > e <replaceable >atributo</replaceable > indicados possam fazer parte de uma palavra, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.canBreakAt(<parameter >String <replaceable >carácter</replaceable ></parameter >, <parameter >int <replaceable >atributo</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <constant >true</constant > (verdadeiro) se o <replaceable >carácter</replaceable > indicado com o <replaceable >atributo</replaceable > indicado for adequado para mudar de linha, caso contrário devolve <constant >false</constant >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.canComment(<parameter >int <replaceable >atributoInicial</replaceable ></parameter >, <parameter >int <replaceable >atributoFinal</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (falso), caso um intervalo que começa e termina com os atributos indicados possa ser comentado; caso contrário, devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.commentMarker(<parameter >int <replaceable >atributo</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve o marcador de comentários, usado em linhas únicas, para um determinado <replaceable >atributo</replaceable >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.commentStart(<parameter >int <replaceable >atributo</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve o marcador de início de comentários, usado em linhas múltiplas, para um determinado <replaceable >atributo</replaceable >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.commentEnd(<parameter >int <replaceable >atributo</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve o marcador de fim de comentários, usado em linhas múltiplas, para um determinado <replaceable >atributo</replaceable >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.attribute(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); int document.attribute(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve o atributo na posição do cursor indicada. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.isAttribute(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >, <parameter >int <replaceable >atributo</replaceable ></parameter >); bool document.isAttribute(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >, <parameter >int <replaceable >atributo</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se o atributo na posição do cursor indicada for igual a <replaceable >atributo</replaceable >, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.attributeName(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); String document.attributeName(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve o nome do atributo como um texto legível. Isto é igual ao nome <literal >itemData</literal > dos ficheiros de realce de sintaxe. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.isAttributeName(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >, <parameter >String <replaceable >nome</replaceable ></parameter >); bool document.isAttributeName(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >, <parameter >String <replaceable >nome</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro), se o nome do atributo, numa dada posição do cursor, corresponder ao <replaceable >nome</replaceable > indicado, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.variable(<parameter >String <replaceable >chave</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve o valor da variável do documento identificada pela <replaceable >chave</replaceable >. Se a variável do documento não existir, o valor devolvido é um texto em branco. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >String document.setVariable(<parameter >String <replaceable >chave</replaceable ></parameter >, <parameter >String <replaceable >valor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Altera o valor da variável do documento identificada pela <replaceable >chave</replaceable >. Devolve o valor da variável alterada. </para> <para >Ver também: <link linkend="config-variables" >Variáveis de documento do Kate</link > </para> <para >Desde: &kde; 4.8 </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.firstVirtualColumn(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve a coluna virtual do primeiro carácter não-nulo na linha indicada, ou então <literal >-1</literal > se a linha estiver em branco ou só tiver caracteres de espaços em branco. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.lastVirtualColumn(<parameter >int <replaceable >linha</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve a coluna virtual do último carácter não-nulo na linha indicada, ou então <literal >-1</literal > se a linha estiver em branco ou só tiver caracteres de espaços em branco. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.toVirtualColumn(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); int document.toVirtualColumn(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); Cursor document.toVirtualCursor(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Converte a posição do cursor <quote >real</quote > para uma posição virtual, devolvendo um objecto inteiro ou um Cursor. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.fromVirtualColumn(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >colunaVirtual</replaceable ></parameter >); int document.fromVirtualColumn(<parameter >Cursor <replaceable >cursorVirtual</replaceable ></parameter >); Cursor document.fromVirtualCursor(<parameter >Cursor <replaceable >cursorVirtual</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Converte a posição virtual do cursor para uma posição do cursor <quote >real</quote >, devolvendo um objecto inteiro ou um Cursor. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Cursor document.anchor(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >, <parameter >Char <replaceable >carácter</replaceable ></parameter >); Cursor document.anchor(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >, <parameter >Char <replaceable >carácter</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Pesquisa para trás pelo carácter indicado, começando na posição do cursor indicada. Por exemplo, se for passado o '(', como carácter, esta função irá devolve a posição do '(' de abertura. Isto implica uma contagem das referências, &ie; os outros '(...)' são ignorados. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >Cursor document.rfind(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >, <parameter >String <replaceable >texto</replaceable ></parameter >, <parameter >int <replaceable >atributo</replaceable > = -1</parameter >); Cursor document.rfind(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >, <parameter >String <replaceable >texto</replaceable ></parameter >, <parameter >int <replaceable >atributo</replaceable > = -1</parameter >); </synopsis ></term> <listitem ><para >Pesquisa para trás pelo texto indicado, com o <replaceable >atributo</replaceable > apropriado. O argumento <replaceable >atributo</replaceable > é ignorado se for igual a <literal >-1</literal >. O cursor devolvido é inválido, caso o texto não tenha sido encontrado. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >int document.defStyleNum(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); int document.defStyleNum(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve o estilo predefinido que é usado na posição do cursor indicada. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.isCode(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); bool document.isCode(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro) se o atributo na posição do cursor indicada não for igual a todos os seguintes estilos: <literal >dsComment</literal >, <literal >dsString</literal >, <literal >dsRegionMarker</literal >, <literal >dsChar</literal >, <literal >dsOthers</literal >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.isComment(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); bool document.isComment(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > se o atributo do carácter na posição do cursor for <literal >dsComment</literal >; caso contrário devolve <literal >false</literal >. </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.isString(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); bool document.isString(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro) se o atributo do carácter na posição do cursor for <literal >dsString</literal >, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.isRegionMarker(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); bool document.isRegionMarker(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro) se o atributo do carácter na posição do cursor for <literal >dsRegionMarker</literal >, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.isChar(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); bool document.isChar(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro) se o atributo do carácter na posição do cursor for <literal >dsChar</literal >, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry> <varlistentry> <term ><synopsis >bool document.isOthers(<parameter >int <replaceable >linha</replaceable ></parameter >, <parameter >int <replaceable >coluna</replaceable ></parameter >); bool document.isOthers(<parameter >Cursor <replaceable >cursor</replaceable ></parameter >); </synopsis ></term> <listitem ><para >Devolve <literal >true</literal > (verdadeiro) se o atributo do carácter na posição do cursor for <literal >dsOthers</literal >, caso contrário devolve <literal >false</literal > (falso). </para ></listitem> </varlistentry ></variablelist> </para> </sect3> </sect2> </sect1> <sect1 id="dev-part"> <title >Extensões do Componente de Edição</title> <para >As <link linkend="editor-component-plugins" >Extensões do Componente de Edição</link > ampliam o KatePart, o componente de Edição de Texto Avançada que é usado em muitas aplicações do &kde;, como o &kate;, o &kwrite;, o Kile e o KDevelop. A criação de um 'plugin' do componente de edição permitir-lhe-á ampliar a funcionalidade do editor em qualquer um destes programas.</para> <para >Para começar, veja o <ulink url="http://techbase.kde.org/Development/Tutorials/Kate/KTextEditor_Plugins" >Tutorial do 'Plugin' do KTextEditor na Base Técnica do &kde;</ulink >. Para saber ainda mais, veja o <ulink url="http://techbase.kde.org/Development/Tutorials/Kate/KTextEditor_Plugins_Advanced" >Tutorial Avançado</ulink >, também na Base Técnica.</para> <para >Poderá encontrar a <ulink url="http://api.kde.org/4.10-api/kdelibs-apidocs/interfaces/ktexteditor/html/" > documentação completa da API na Referência de API's do &kde;</ulink >.</para> </sect1> <sect1 id="dev-app"> <title >'Plugins' da Aplicação &kate; (C++)</title> <para >Os <link linkend="kate-application-plugins" >'Plugins' da Aplicação Kate</link > melhoram as funcionalidades do editor &kate; propriamente dito, de forma que imaginar, usando a mesma linguagem de programação em que o &kate; é feito - o C++.</para> <para >Para começar, veja o <ulink url="http://kate-editor.org/2004/01/06/writing-a-kate-plugin/" >tutorial de criação de um 'plugin' do &kate; na página Web do &kate;</ulink >. Também existe um <ulink url="http://quickgit.kde.org/?p=kate.git&a=tree&f=addons%2Fkate%2Fhelloworld" >'plugin' de exemplo <quote >Olá mundo!</quote > clássico, que vem incluído no código-fonte do &kate;</ulink >.</para> </sect1> <sect1 id="dev-pate"> <title >'Plugins' em Python do &pate;</title> <para >Os <link linkend="pate" >'Plugins' do &pate;</link > também lhe permitem aumentar a funcionalidade do &kate; de qualquer forma que desejar, usando a linguagem de programação Python.</para> <para >Para começar, veja o <ulink url="http://kate-editor.org/2012/07/01/python-plugin-developer-guide-part-1/" > guia de desenvolvimento de 'plugins' em Python na página Web do &kate;</ulink >.</para> <para >Também poderá aceder à referência da API no ecrã de <link linkend="pate-config" >Configuração do &pate;</link >.</para> </sect1> </chapter>