# Extendendo o &quantaplus;

Christopher
Hornbaker

    chrishornbaker@earthlink.net

Marcus
Gama

    marcus_gama@uol.com.br

Tradução

# Extendendo o &quantaplus;

Este capítulo descreve como personalizar o &quantaplus; para suas necessidades particulares e como você pode ajudar o &quantaplus; a ficar ainda melhor.

## Pacote de Edição de Tipo de Documento (&DTEP;)

Os Pacotes de Edição de Tipo de Documento (&DTEP;) são usados no &quantaplus; para adicionar suporte para marcação, linguagens de scripting e &CSS;. Eles permitem que o &quantaplus; forneça recursos de auto-complementação e nós de árvores. Sua simplicidade e flexibilidade são o que faz o &quantaplus; uma &IDE; rápida e amigável para desenvolvedores web. Eles são o que torna o &quantaplus; um ambiente produtivo e fácil de usar.

Os &DTEP;s vem em dois sabores: Família 1, que são para marcação, e Família 2 que são para scripting e &CSS;. Os &DTEP; são feitos de duas partes: a Pasta Tag e as Barras de Ferramentas. Pastas de Tag são compostas de dois tipos de arquivos: o description.rc e os arquivos TagXML, que carregam a extensão .tag. Barras de ferramentas são abas de botões orientadas à ícones e acessíveis (acima da janela de edição) que colocam texto em um documento mais rápido do que o usuário pode digitar.

Este documento descreve como criar arquivos TagXML, o description.rc e as barras de ferramentas. Em resumo, um &DTEP;.

Arquivos TagXML (.tag) definem tanto os atributos específicos de uma tag como a disposição e conteúdo do diálogo de propriedades que o &quantaplus; mostra para a tag. O arquivo description.rc fornece regras e informações sobre o &DTEP; propriamente dito. Barras de ferramentas fornecem uma maneira rápida de adicionar tags ao documento sem se preocupar com erros tais como de sintaxe.

### Empacotando

Pastas de Tag são somente isto: pastas. Elas são compostas somente do description.rc e arquivos TagXML. Pastas Tag carregam o nome da linguagem de marcação e versão, se aplicável. (Por exemplo, html-4.01-strict)

### TagXML

A tabela abaixo lista os elementos definidos na TagXML e declara se eles são necessários ou não. Apesar de nem todos serem necessários, é recomendável que você use o máximo que puder de modo que outros usuários possam ter uma experiência melhor e mais informações sobre como trabalhar com eles.

Elemento | Uso Padrão | Uso Caso
--- | --- | ---
TAGS | necessário | sempre
tag | necessário | sempre
label | opcional | necessário para criar um diálogo de propriedades
attr | opcional | necessário para definir um atributo
tooltip | opcional | necessário para que o diálogo de propriedades exiba uma dica
whatsthis | opcional | necessário que que o diálogo de propriedades exiba um O que é Isto
list | opcional | necessário que um atributo é do tipo lista
item | opcional | necessário que <lista > é usado
textlocation | opcional | sempre
location | opcional | necessário quando um rótulo é usado
text | opcional | necessário quando um rótulo é usado
children | opcional | lista de tags que podem aparecer dentro de uma tag sendo definida
child | necessário | uma entrada filha
stoppingtags | opcional | lista de tags que envia outra tag para o fim
stoppingtag | necessário | uma entrada stoppingtags

#### Descrições de Elemento TagXML

As seções a seguir descreverão, em detalhes, cada elemento. Tudo sobre onde eles podem ir, o que eles fazem lá, e apresentados de uma maneira fácil de seguir.

##### TAGS

Este é o elemento raiz de um documento TagXML. Ele deve aparecer em um documento somente uma vez. Ele pode conter a definição de múltiplas tags. Isto é um elemento tipo elemento-somente.

Pai(s) | Filho
--- | ---
NENHUM | tag

##### tag

Envoltório para tag que está sendo definida. Este é um elemento tipo elemento-somente.

Pai(s) | Filho
--- | ---
TAGS | label, attr, stoppingtags

Atributo | Tipo | Valores | Padrão | Uso | Descrição
--- | --- | --- | --- | --- | ---
nome | string |  |  | necessário | Especifica o nome da tag que está sendo definida.
simples | booleano |  |  | opcional | Especifica se a tag precisa ou não de um fechamento de tag </(nometag) >.
type | string |  | xmltag | opcional | Especifica o tipo da tag que está sendo definida.
|  | xmltag |  |  | Tipo de tag é baseado-XML. (Família 1 somente.)
|  | property |  |  | Tipo da tag é relacionado ao &CSS;. (Família 2 somente.)
|  | function |  |  | Tipo da tag é uma função de script. Quando usado <attr > se torna argumentos da função. (Família 2 somente.)
|  | class |  |  | Tipo da tag é uma classe de script. (Família 2 somente.)
returnType | string |  | void | opcional | Especifica o tipo de retorno da tag que está sendo definida. (Família 2 somente.)
|  | void |  |  | Tipo da tag retorna void.
|  | int |  |  | Tipo da tag retorna inteiro.
|  | float |  |  | Tipo da tag retorna flutuante.
|  | long |  |  | Tipo da tag retorna longo.
|  | string |  |  | Tipo da tag retorna string.

##### label

Coloca um rótulo no diálogo. O texto especificado pela tag <texto >. Este é um elemento tipo elemento-somente.

Pai(s) | Filho
--- | ---
tag | text, location

##### attr

Define um atributo da tag. Este elemento ocorre uma vez para cada atributo. Ele define o nome e tipo do atributo. Ele contém também tags adicionais que especificam como este atributo deve ser exibido, etc. Este é um elemento tipo elemento-somente.

Pai(s) | Filho
--- | ---
tag | location, list, tooltip, whatsthis, textlocation

Atributo | Tipo | Valores | Padrão | Uso | Descrição
--- | --- | --- | --- | --- | ---
nome | string |  |  | necessário | Especifica o nome do atributo que está sendo definido.
type | string |  | input | necessário | Especifica o tipo de atributo que está sendo definido.
|  | input |  |  | Campo suporta entradas de texto livre (campo texto).
|  | check |  |  | O valor do campo é booleano (caixa de verificação).
|  | color |  |  | O valor do campo é uma cor.
|  | url |  |  | O valor do campo é uma &URL;. (Arquivo local para referir-se.)
|  | list |  |  | O valor do campo é um ítem de uma lista especificada.
status | string |  | opcional | necessário | Especifica se o argumento é ou não obrigatório. (Família 2 somente.)
|  | opcional |  |  | Argumento é opcional.
|  | necessário |  |  | Argumento é obrigatório.
|  | implied |  |  | Argumento é implicado.

##### tooltip

Define a dica para o campo no diálogo. Este elemento é somente-texto.

Atualmente somente texto plano é suportado (você não pode usar qualquer marcação).

Pai(s) | Filho
--- | ---
attr | NENHUM

##### whatsthis

Define a ajuda 'O que é Isso' para um campo no diálogo. Este elemento é somente-texto.

Atualmente somente texto plano é suportado (você não pode usar qualquer marcação).

Pai(s) | Filho
--- | ---
attr | NENHUM

##### list

Uma tag de contenção que agrupa juntos os ítens em uma lista. Isto pode aparecer somente uma vez para cada descrição de atributo. Este é um elemento tipo somente-elemento.

Pai(s) | Filho
--- | ---
attr | item

##### item

Define um ítem em uma lista. Este elemento é somente-texto.

Pai(s) | Filho
--- | ---
list | NENHUM

##### textlocation

Especifica a posição de um texto de atributo da tag dentro de um diálogo. Esta tag somente pode ocorrer uma vez para cada atibuto no diálogo (&ie; uma para cada tag <attr >). Este elemento é vazio.

Pai(s) | Filho
--- | ---
attr | NENHUM

Atributo | Tipo | Uso | Descrição
--- | --- | --- | ---
row | nonNegativeInteger | necessário | Especifica a linha na disposição do diálogo de um campo ou rótulo.
col | nonNegativeInteger | necessário | Especifica a coluna na disposição do diálogo de um campo ou rótulo.
rowspan | nonNegativeInteger | opcional | Especifica o número de linhas que um campo deve se extender.
colspan | nonNegativeInteger | opcional | Especifica o número de colunas que um campo deve se extender.

##### location

Especifica a posição e tamanho do campo no diálogo. Esta tag somente pode ocorrer uma vez para cada campo no diálogo (&ie; uma para cada tag <attr > e <label >). Este elemento é vazio.

Pai(s) | Filho
--- | ---
label, attr | NENHUM

Atributo | Tipo | Uso | Descrição
--- | --- | --- | ---
row | nonNegativeInteger | necessário | Especifica a linha na disposição do diálogo de um campo ou rótulo.
col | nonNegativeInteger | necessário | Especifica a coluna na disposição do diálogo de um campo ou rótulo.
rowspan | nonNegativeInteger | opcional | Especifica o número de linhas que um campo deve se extender.
colspan | nonNegativeInteger | opcional | Especifica o número de colunas que um campo deve se extender.

##### text

Define o texto para um rótulo ou caixa de verificação. Este elemento é somente-texto.

Pai(s) | Filho
--- | ---
label, attr | NENHUM

##### children

Define uma lista de elementos que podem aparecer dentro da tag que está sendo especificada. Este elemento é um elemento tipo elemento-somente.

Pai(s) | Filho
--- | ---
tag | child

##### child

Define uma tag filha. Este elemento é vazio.

Pai(s) | Filho
--- | ---
children | NENHUM

Atributo | Tipo | Uso | Descrição
--- | --- | --- | ---
nome | string | necessário | Especifica uma tag que pode aparecer dentro de uma determinada tag.

##### stoppingtags

Define uma lista de elemento que forçam o fim da tag. Este elemento é um elemento tipo elemento-somente.

Pai(s) | Filho
--- | ---
tag | stoppingtag

##### stoppingtag

Define uma tag de parada. Este elemento é vazio.

Pai(s) | Filho
--- | ---
stoppingtags | NENHUM

Atributo | Tipo | Uso | Descrição
--- | --- | --- | ---
nome | string | necessário | Especifica que tags forçam o fim de outra tag.

#### Uso do TagXML

Todos os arquivos TagXML devem iniciar com a declaração &XML;: <?xml version="1.0" encoding="UTF-8"?> e devem estar corretamente aninhado e fechado.

Espaços não afetam nada, mas observe os caracteres & e <. Eles devem ser substituídos por &amp; e &lt; respectivamente em elementos como <tooltip >, <whatsthis >, e <text >. Não fazer isto não causará travamentos, mas você terá pedaços do seu trabalho desaparecendo neste caso.

#### Validação do TagXML

Para validar seus arquivos TagXML, simplesmente clique no menu Ferramentas do &quantaplus; e selecione Validar TagXML. Um diálogo será apresentado e você precisará somente seguir as orientações fornecidas.

Este recurso atualmente não está presente. Atualmente a validação ocorre quando os arquivos TagXML são carregados no &quantaplus;.

#### Exemplos de TagXML

##### Família 1

O exemplo a seguir mostrará um arquivo TagXML da Família 1 válido. Este arquivo procura descrever o elemento <schema > do Esquema do &W3C; &XML;. O nome do arquivo para este arquivo TagXML será schema.tag. Simples, não?

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE TAGS>
    <TAGS>
     <tag name="schema">
      <label>
       <text
    >id</text>
       <location col="0" row="0"/>
      </label>
      <attr name="id" type="input">
       <tooltip
    >Um ID único para o elemento.</tooltip>
       <whatsthis
    >Um ID único para o elemento.</whatsthis>
       <location col="1" row="0"/>
      </attr>

      <label>
       <text
    >version</text>
       <location col="0" row="1"/>
      </label>
      <attr name="version" type="input">
       <tooltip
    >Versão do esquema.</tooltip>
       <whatsthis
    >Versão do esquema.</whatsthis>
       <location col="1" row="1"/>
      </attr>

      <label>
       <text
    >targetNamespace</text>
       <location col="0" row="2"/>
      </label>
      <attr name="targetNamespace" type="input">
       <tooltip
    >Referência de &URI; do espaço de nomes para este esquema.</tooltip>
       <whatsthis
    >Referência de &URI; do espaço de nomes para este esquema.</whatsthis>
       <location col="1" row="2"/>
      </attr>

      <label>
       <text
    >xmlns</text>
       <location col="0" row="3"/>
      </label>
      <attr name="xmlns" type="input">
       <tooltip
    >Referência de &URI; do espaço de nomes para uso neste esquema.
       Se nenhum prefixo é usado, então componentes deste espaço de nomes podem ser usados sem qualificação.</tooltip>
       <whatsthis
    >Referência de &URI; do espaço de nomes para uso neste esquema.
       Se nenhum prefixo é usado, então componentes deste espaço de nomes podem ser usados sem qualificação.</whatsthis>
       <location col="1" row="3"/>
      </attr>

      <label>
       <text
    >attributeFormDefault</text>
       <location col="0" row="4"/>
      </label>
      <attr name="attributeFormDefault" type="list">
       <items>
        <item
    >qualified</item>
        <item
    >unqualified</item>
       </items>
       <tooltip
    >Forma padrão para todos os atributos dentro deste esquema.</tooltip>
       <whatsthis
    >Forma padrão para todos os atributos dentro deste esquema.</whatsthis>
       <location col="1" row="4"/>
      </attr>

      <label>
       <text
    >elementFormDefault</text>
       <location col="0" row="5"/>
      </label>
      <attr name="elementFormDefault" type="list">
       <items>
        <item
    >qualified</item>
        <item
    >unqualified</item>
       </items>
       <tooltip
    >Forma padrão para todos os atributos dentro deste esquema.</tooltip>
       <whatsthis
    >Forma padrão para todos os atributos dentro deste esquema.</whatsthis>
       <location col="1" row="5"/>
      </attr>

      <label>
       <text
    >blockDefault</text>
       <location col="0" row="6"/>
      </label>
      <attr name="blockDefault" type="input">
       <location col="1" row="6"/>
      </attr>

      <label>
       <text
    >finalDefault</text>
       <location col="0" row="7"/>
      </label>
      <attr name="finalDefault" type="input">
       <location col="1" row="7"/>
      </attr>
     </tag>
    </TAGS>

##### Família 2

O exemplo a seguir mostrará um arquivo TagXML da Família 2 válido. Este arquivo procura descrever a função de sobrecarga do &PHP;. O nome do arquivo para este arquivo TagXML será overload.tag.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE tags>
    <tags>
      <tag name="overload" type="function" returnType="void">
    <attr name="class_name" type="string" status="optional"/>
      </tag>
    </tags>

### description.rc

O arquivo description.rc é também muito simples. Nem tudo que é mostrado a seguir precisa ser usado. A estrutura básica do arquivo description.rc é a que se segue.

#### Estrutura da Família 1

    [General] - Generic information.
    Version = Use 1 para o &quantaplus; versão <=3.1.2 e 2 para qualquer versão posterior.
    Name = String de definição DTD. (-//&W3C;//DTD HTML 4.01 Transitional//EN)
    NickName = O nome bonito do DTD. (HTML 4.01 Transitional). Se não definido, Name é
    usado como NickName.
    &URL; = &URL; que aponta para a definição DTD. (http://www.w3.org/TR/html4/loose.dtd)
    DoctypeString = O string que deve aparecer na declaração !DOCTYPE.
    (HTML PUBLIC "-//&W3C;//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd")
    Inherits = O nome do DTD a partir de onde este DTD deriva suas tags. (-//&W3C;//DTD HTML 4.01//EN)
    DefaultExtension = Novos arquivos são criados com esta extensão. (html)
    Groups = A lista dos grupos de atributos comuns, que podem ser apresentados em mais de uma tag.
    (Core, I18n, Script) Veja abaixo. (Group1, Group2...)
    NumOfPages = Quantas páginas um diálogo de tag possui, além da página contendo os
    atributos definidos no arquivo de tag? Veja abaixo. (Page1,...)
    CaseSensitive = Sensibilidade à caixa do DTD. (true|false)
    Family = 1 Este tipo de DTEP é da família 1, uma vez que é uma marcação.

    [Toolbars] - Informações sobre as barras de ferramentas do DTEP.
    Location = O nome da pasta dentro de $KDEDIR($KDEHOME)/share/apps/quanta/toolbars
    onde as barras de ferramentes para este DTEP estão.
    Names = A lista de nomes de arquivos de barras de ferramentas, sem a extensão .toolbar.tgz, que
    são carregadas para este DTEP a partir da pasta acima.

    [Group1] - Subsituir com um dos Grupos listados abaixo.
    Attributes = A lista de atributos para este grupo. Atualmente, todos os atributos listados são
     tratados como strings.
    Exemplo:
    [Core]
    Attributes = id, class, style, title

    [Page1] - Descrição de uma página do editor de tag.
    Title = O título desta página no diálogo de edição de tag.
    Groups = Lista de grupos que aparecem nesta página. (Core, I18n)

    [Extra rules] - Algumas regras que não cabem em outros lugares.
    BooleanAttributes = (simple|complex)
    Exemplo para simple: <tag booleanAttr
    >.
    Exemplo para complex: <tag booleanAttr="1"
    > ou <tag booleanAttr="true">
    Single Tag Style = (html|XML)
    Exemplo para html: <single_tag>
    Exemplo para XML:  <single_tag />
    StructGroupsCount = O número de grupos estruturados. Veja abaixo.
    MinusAllowedInWords = Se true "isto-é-uma-palavra" é tratado como uma palavra. Caso contrário,
    é tratado como 4 palavras.
    TagAutoCompleteAfter = CHAR. A caixa de auto-complementação surge automaticamente
    uma vez que este CHAR é inserido ou ESPAÇO é pressionado após este CHAR. Para a família 1 de DTEP,
    isto é normalmente "<" O texto "none" ao invés de um CHAR especifcando que a
    caixa de complementação de tag não deve surgir automaticamente, somente se o usuário solicitá-la.
    AttributeSeparator = CHAR. Este CHAR significa que o nome do atributo terminou.
    Isto é " para DTEPs XML.
    TagSeparator = CHAR. Similar ao acima.

    [StructGroup_1] - Definição da estrutura do grupo 1.
    Name = O texto que aparece se existirem tags corresponder a este grupo de configurações.
    No_Name = O texto que aparece se NENHUMA tag correspoder a este grupo de configurações.
    Icon = O nome do ícone que aparece antes e acima do texto.
    Tag = tagname(attribute1, attribute2, ...). Tags com nome tagname aparecerão
    sob este grupo. O ítem texto será "attribute1_value | attribute2_value | ..."
    Atualmente somente uma tag pode ser listada aqui.
    HasFileName = (true|false) True, se o texto do ítem (acima do valor do atributo) contém um nome de arquivo.
    FileNameRx = Expressão regular usada para remover caracteres desnecessários do texto do ítem.

    [Parsing rules] - Regras usadas ao analisar o documento.
    SpecialAreas = Os strings de início e fim de áreas especiais, separados por uma vírgula
    Áreas especiais que não serão analisadas de acordo com estas regras deste DTEP, mas com as suas próprias regras.
    Uma área especial que pode ser um DTEP de outra família, um comentário, ou algo para este fim.
    Eg. <!-- -->
    SpecialAreaNames = Lista separada por vírgulas dos nomes das áreas especiais. Por exemplo: comment
    SpecialTags = tagname(attributename) - Especifica uma tag que define o início de uma área especial.
    MayContain = Lista separada por vírgulas de DTEPS da família 2 que pode estar presentes no documento.
    (php, css)

#### Estrutura da Família 2

    [General] - Informações Gerais.
    Version = Use 1 para o &quantaplus; versão <=3.1.2 e 2 para qualquer versão posterior.
    Name = O próprio nome
    NickName = Como todos os chamam. Se não definido, Name é usado como NickName.
    Inherits = O nome do DTEP a partir de onde este DTEP herda tags. (O Name, não o NickName)
    DefaultExtension = Novos arquivos serão criados com esta extensão. (php)
    NumOfPages = 0   Sempre zero porque não existe um diálogo de edição de tag para
    DTEPs da Família 2.
    CaseSensitive = Sensibilidade à caixa do DTEP. (true|false)
    Family = 2 Este tipo de DTEP é da família 2, uma vez que não é marcação.

    [Toolbars] - Informações sobre as barras de ferramentas do DTEP.
    Location = O nome da pasta dentro de $KDEDIR($KDEHOME)/share/apps/quanta/toolbars
    onde as barras de ferramentas do DTEP estão.
    Names = A lista de nomes de arquivos de barras de ferramentas, menos a extensão .toolbar.tgz, que
    serão carregados para este DTEP a partir da pasta acima.

    [Extra rules] - Algumas regras que não cabem em outros lugares.
    BooleanAttributes = (simple|complex)
    Exemplo para simple: <tag booleanAttr
    >.
    Exemplo para complex: <tag booleanAttr="1"
    > or <tag booleanAttr="true">
    StructGroupsCount = O número de grupos estruturados. Veja abaixo.
    MinusAllowedInWords = Se true "isto-é-uma-palavra" é tratado como uma palavra. Caso contrário,
    isto é tratado como 4 palavras.
    TagAutoCompleteAfter = CHAR. A caixa de auto-complementação é apresentada automaticamente
    uma vez que este CHAR seja inserido ou ESPAÇO seja pressionado após este CHAR. Para DTEP dafamília 1,
    isto é normalmente "<" O texto "none" ao invés de CHAR especifica que a caixa
    de complementação de tag não deve aparecer automaticamente, somente se o usuário solicitá-la.
    AttributeSeparator = CHAR. Este CHAR significa que o nome do atributo foi terminado.
    Isto é " para DTEPs XML.
    TagSeparator = CHAR. Similar ao acima.
    AttributeAutoCompletionAfter = CHAR. Similar ao TagAutoCompletionAfter, mas
    para atributos do tag. Isto é "(" por padrão e ":" para CSS.

    [StructGroup_1] - Definição para o grupo estruturado 1.
    Name = O texto que aparece se existirem tags correspondentes às configurações deste grupo.
    No_Name = O texto que aparece se não existir NENHUM tag correspondente às configurações deste grupo.
    Icon = O nome do ícone que aparece antes do texto acima.
    Tag = tagname(attribute1, attribute2, ...). Tags com nome tagname aparecerão
    sob este grupo. O texto do ítem será "attribute1_value | attribute2_value | ..."
    Atualmente somente uma tag pode ser listada aqui.
    HasFileName = (true|false) True, se o texto do ítem (valores de atributo acima) contém um nome de arquivo.
    FileNameRx = Expressão regular usada para remover caracteres desnecessários do texto do ítem.
    SearchRx = expressão regular usada para encontrar áreas de texto em DTEP da Família 2, as quais
    surgirão deste grupo
    ClearRx = expressão regular usada para limpar caracteres/texto indesejável di resultado da busca acima.
    O string limpo aparecerá na árvore de estrutura.

    [Parsing rules] - Regras usadas ao analisar o documento.
    SpecialAreas = O string de início e fim de áreas especiais, separados por vírgula.
    Áreas especiais não são analisadas de acordo com as regras deste DTEP, e sim com suas próprias regras.
    Uma área especial pode ser um DTEP de outra família, um comentário, ou algo que não tenha efeito.
    Por exemplo. <!-- -->
    SpecialAreaNames = Lista separada por vírgulas dos nomes de área especial acima. Por exemplo. comment
    SpecialTags = tagname(attributename) - Especifica uma tag que define o início da área especial.
    AreaBorders = Lista separada por vírgulas das bordas da área que encapsula este DTEP Família 2. No
    caso do PHP, isto é: <? ?>, <* *
    >, <% %>
    Tags = tagname(attribute). Se o DTD parente possui uma tag com tagname e
    o valor do atributo desta tag é igual ao nome do DTD, a área de tag
    analisada de acordo com as regras deste DTD.
    Comments = lista separada por vírgulas das bordas de área para comentários. EOL significa, do inglês, fim-de-linha.
    Por exemplo: // EOL, /* */
    StructKeywords = Lista separadas por ponto e vírgula da palavras chaves de estrutura. Estruturas são tratadas
    como novos nós na árvore de estrutura.
    StructBeginStr = Um string especiicando o início da estrutura (como {)
    StructEndStr = Um string specificando o fim da estrutura (como })
    StructRx = Expressão regular contendo o início ou o fim da área da estrutura.
    Por exemplo. \\{ | \\} (a borda da área da estrutura pode ser { ou })

## Criando Barras de Ferramentas

O texto a seguir mostrará como criar barras de ferramentas para um &DTEP;. Barras de ferramentas são elementos gráficos que possuem ações atribuídas. Ações, no &quantaplus;, são a base para todas as outras extensões que o &quantaplus; possui e possuirá no futuro. O mesmo mecanismo que define uma ação no &quantaplus; habilita a auto-completamentação e diálogos de tag. Com ações, o limite do que você pode fazer é virtualmente infinito. Para entender através de um exemplo, nós usaremos &HTML; arrumado em nossas páginas web.

### Do Zero para o Completo

Para inciar, você precisará criar uma barra de ferramentas de usuário. Selecione Barras de Ferramentas Adicionar Barra de Ferramentas de Usuário.

Se existirem muitas tags para a linguagem de marcação, é recomendável que você divida as tags em grupos lógicos. Você precisará criar uma nova barra de ferramentas de usuário para cada grupo. Neste caso, não existem muitas, por isso nós iremos criar uma barra de ferramentas e nomeá-la com o nome da marcação.

Uma vez que todas as suas barras de ferramentas estejam criadas, você deve adicioná-as e configurar as ações. Para fazer isto, selecione Configurações Configurar Ações .

As partes desta janelas são bem objetivas. Pressione o botão Nova ação na base da janela para entrar no modo de edição.

Preencha todos os campos necessários e adicione a tag para a(s) barra(s) de ferramentas apropriada(s).

Complete o resto e,se a tag tiver atributos e você planeja sempre usá-los, habilite a caixa Executar o diálogo "Editar tag" se disponível de modo que você seja questionado sempre que a ação é usada.

Você deve agora ter algo como o seguinte.

Pressione o botão Aplicar e você verá a ação adicionada à(s) barra(s) de ferramentas selecionada(s).

Opa! Este ícone é terrível. Como eu mesmo e os outros associarão este ícone com aquela ação? Vamos substituí-lo antes de surgirem problemas.

Para criar um ícone que descreva mais precisamente aquela ação, nós iremos usar o &kiconedit;. Selecione-o a partir do &kmenu;, Gráficos Mais Programas (ou onde a sua distribuição o tenha colocado).

O padrão do &kiconedit; é o tamanho de 32x32 pixéis, mas nós precisamos de 22x22. Para mudar isto, selecione Editar Redimensionar .

Tenha em mente que você está criando um ícone que ajudará não somente você a lembrar-se que ação ele faz, mas também outros usuários do &DTEP;.

Uma vez que a tag para qual eu estou criando o ícone é chamada iniciar, eu decidi criar um Sinal de iniciar. Use a cor verde (verde é frequentemente interpretado como ir, iniciar, ou proceder), ou, pelo menos, apresente um mensagem ara o usuário que clicar nesta ação colocará uma tag <iniciar> no documento atual.

Agora que eu terminei a criação do ícone, eu o salvarei.

Uma vez que você tenha terminado a criação do(s) ícone(s), você deve associá-lo com a ação. Para fazer isto, abra Configurações Configurar Ações novamente (no &quantaplus;) e selecione a ação a qual deseja associar o ícone. Ao lado do campo Texto, você verá um botão; clique-o.

Selecione Outros Ícones e então clique o botão Navegar.

Vá para a pasta na qual você salvou o ícone, selecione o ícone e clique OK.

Pressione o botão Aplicar e continue a fazer o mesmo com as outras tags, se for o caso, ou clique em OK para terminar.

Vamos dizer que você deseje adicionar algumas funções comuns do &quantaplus; na sua barra de ferramentas ou talvez ache que sua barra de ferramentas poderia ser melhor organizada de uma maneira diferente, com alguns separadores para agrupar ações. Abra o diálogo Configurar Barras de Ferramentas acessando Configurações Configurar Barras de Ferramentas . Certifique-se de que sua barra de ferramentas está selecionada.

Eu irei escolher o separador (topo da coluna da esquerda) para a minha barra de ferramentas. Uma vez que você tenha selecionado o ítem que deseja adicionar a sua barra de ferramentas, pressione o botão de seta para direita. Isto adicionará o ítem a sua barra de ferramentas.

Eu acho que gostaria de ter uma maneira rápida de acessar a Previsão do Konqueror. Eu selecionarei este ítem e o adicionarei à barra de ferramentas.

Observe como o separador auxiliar no agrupamento. Alguém que não conheça minha barra de ferramentas poderá pensar que o botão do &konqueror; foi colocado como ou em oposição ao botão iniciar.

Aplique suas mudanças e, quando tiver concluído, pressione OK para terminar.

Ah, veja a nova e fantástica barra de ferramentas! Muito mais manipulável agora.

Lembre de testar sua barra de ferramentas, clicando em todos os butões, de modo que você saiba se a saída é correta.

Agora para salvar a barra de ferramentas, nós selecionaremos Barras de Ferramentas Salvar Barras de Ferramentas Salvar como Barra de Ferramentas Local .

Salve-a para a pasta correta. Uma vez que NeXML não existe, eu simplesmente a terei na pasta de nível superior, mas sua barra de ferramentas deve ser salva para a pasta correta. Certifique-se de ajustar seu description.rc para fazer com que ela seja carregada quando um novo arquivo do tipo especificado seja criado.

## Criando Sua Própria Documentação

Robert
Nickel

    robert@artnickel.com

Marcus
Gama

    marcus_gama@uol.com.br

Tradução

## Criando Sua Própria Documentação

Provavelmente as adições mais notáveis ao &quantaplus; para o usuário em geral serão as adições de documentação para linguagens de marcação ou script que você mais gosta. Para este fim, este capítulo explanará como eu criei a árvore de documentação do &PHP; para meu uso pessoal.

Antes de iniciar a criação de sua própria documentação, você pode desejar verificar o repositório do &quantaplus; para ver se alguém já fez isto para você.

Existem duas fases para este processo. Primeiro, você deve obter a documentação existente para a linguagem de marcação/script/&etc; que você deseja. Segundo, você deve criar o arquivo `docrc`. O primeiro depende de você, o segundo será abordado aqui.

A forma geral do arquivo docrc é a seguinte:

    #KDE Config File
    [Tree]
    Doc dir=caminho, relativo a este arquivo, dos arquivos de documentação html &eg; php42/
    #top level elements
    Top Element=Sua descrição desyes documentos
    > &eg; documentação do &PHP; 4.2

    Section 1=Section1.html
    Section 2=#Sec2.1,#Sec2.2,#Sec2.3
    Sec2.1=Sec2.1.html
    Sec2.2=Sec2.2.html
    Sec2.3=Sec2.3.html
    ...

    [Context]
    ContextList=func1,func2,tag1,tag2,tag3
    func1=func1.html
    func2=func2.html
    tag1=tag1.html
    tag2=tag2.html
    tag3=tag3.html

O `docrc` é dividido em duas seções: Tree e Context.

A seção Tree define o aspecto da apresentação da documentação na aba de documentação. Por exemplo, você verá que nos documentos você terá algo como i&PHP;sto:

Relacionado com o mostrado acima, meu `docrc` do &PHP; se parece com isto:

    #KDE Config File

    [Tree]

    Doc dir=php42/

    #top level elements
    Top Element=Documentação PHP 4.2

    Documentação PHP 4.2=Índice,#Iniciando,#Referência de Linguagem

    Índice=index.html

    Iniciando=Introdução, ...
    Introdução=introduction.html
    ...

    Referência de Linguagem=Sintaxe básica, ...
    Sintaxe básica=language.basic-syntax.html
    ...

Observe o `#` na frente do Iniciando e Referência de Linguagem. Ele indica que estes são sub-recipientes na árvore e tem seu próprio conteúdo. Eu não acredito que existe um limite de profundidade aqui (isto deve ser feito de acordo com seu bom senso) — use seu julgamento.

Para o Índice, você observará que ele se referencia diretamente a um arquivo (e consequentemente mostra acima na base da visão de árvore — diretórios primeiro|).

Espaços não afetam nada, mas observe os caracteres & e <. Eles devem ser separados por &amp; e &lt; respectivamente em todos os arquivos de recursos do &quantaplus; baseados em &XML;.

A seção Context é a seção do arquivo docrc que é usada para facilitar a ajuda sensível ao contexto. Por exemplo, você esté escrevendo um script e você gostaria de ve&PHP;r a documentação para a função `mysql_fecth_array`. Você simplesmente destaca a função e então pressiona &Ctrl;H para ajuda de contexto. A documentação do `mysql_fetch_array` será imediatamente exibida. Existem apenas dois tipos de entrada aqui: a ContextList e as linhas de associação de arquivo.

ContextList

  Realmente simples, isto é apenas uma lista separada por vírgulas dos itens de contexto que você deseja tornar disponíveis (para o &PHP;, estes são as funções do &PHP;).

Linhas de associação de arquivos

  Estas seguem a forma item de contexto=página do doc html. &eg; acos=function.acos.html

Um exemplo abaixo da versão da seção Context do meu `docrc` é o seguinte:

    #Keywords for context help
    [Context]
    ContextList=abs,acos,acosh,addcslashes,addslashes,...

    abs=function.abs.html
    acos=function.acos.html
    acosh=function.acosh.html
    addcslashes=function.addcslashes.html
    addslashes=function.addslashes.html
    ...

Agora você pode salvar seu arquivo `docrc`, salve-o no `$`HOME`/.kde/share/apps/quanta/doc` ou `$`KDEDIR`/share/apps/quanta/doc` para uso local ou global respectivamente. Então crie uma pasta (a especificada em seu arquivo `docrc`) no mesmo diretório do seu `docrc` e copie suas páginas &HTML; nele.

Você precisará reiniciar o &quantaplus; e então você verá seus documentos.

Uma vez que você tenha certeza de que eles são bons e podem ser compartilhados, envie seu `docrc` com uma descrição de qualquer informação pertinente sobre que documentos você usou para o repositório do &quantaplus; para uso pela comunidade do &quantaplus;. Você não ficará rico, mas se sentirá bem em saber que contribuiu para a melhor plataforma de desenvolvimento web do mundo.