# Plataformas do &kde;: KDesignerPlugin

`kgendesignerplugin`

1

`kgendesignerplugin`

Gera 'plugins' de elementos gráficos para o &Qt; Designer.

    kgendesignerplugin OPÇÕES ficheiro

## Descrição

Os 'plugins' de elementos gráficos personalizados do &Qt; Designer normalmente seguem um padrão normal, sendo que as classes oferecidas pelo 'plugin' fornecem na sua maioria alguma informação estática, em conjunto com a função para criar uma instância, a qual será normalmente uma simples chamada ao construtor. O `kgendesignerplugin` permite aos programadores das bibliotecas que fornecem elementos novos a criação de um desses 'plugins', sem ter de cria todo o código acessório associado, oferecendo um ficheiro de descrição do tipo INI.

O `kgendesignerplugin` escolhe opções predefinidas para a maioria das definições, pelo que normalmente é necessária apenas alguma configuração mínima.

## Opções

`-o `ficheiro``

- O nome do ficheiro em C++ gerado. Se não for indicado, será usado o `stdout`.

`-n `nome-plugin``

- Fornecido para fins de compatibilidade. O valor por omissão da opção 'PluginName' no ficheiro de entrada.

`-g `grupo``

- Oferecido por razões de compatibilidade. O valor por omissão para a opção 'DefaultGroup' no ficheiro de entrada.

`--author`

- Mostra informações sobre o autor.

`--license`

- Mostra informações acerca da licença.

`-h, --help`

- Mostra um breve texto de ajuda.

`-v , --version`

- Mostra a informação da versão.

## Formato do Ficheiro

O ficheiro de entrada é um ficheiro de configuração do tipo INI (para ser mais específico, está no formato suportado pela plataforma KConfig) que descreve um conjunto de itens gráficos. Contém uma secção `[Global]`, que oferece informações gerais acerca do 'plugin', assim como uma secção para cada elemento que deverá ser incluído no 'plugin'.

A secção `[Global]` pode ter os seguintes elementos:

`DefaultGroup`

- O valor por omissão para o item `Group` nas secções das classes (por omissão: "`Custom`", a menos que seja usada a opção `-g`).

`Includes`

- Uma lista (separada por vírgulas) dos ficheiros de inclusão necessários (por omissão: vazio). Repare que os ficheiros de inclusão definidos posteriormente no ficheiro não deverão ser indicados aqui; em vez disso, este campo serve para os ficheiros de inclusão especiais para o uso próprio do 'plugin', como os das classes que possuem antevisões.

`PluginName`

- O nome da classe principal em C++ no 'plugin' (por omissão: "`WidgetsPlugin`", a menos que seja usada a opção `-n`).

Cada classe deverá ter a sua própria secção `[`ClassName`]`, a qual poderá incluir os seguintes elementos:

`CodeTemplate`

- O valor devolvido pela função `codeTemplate()` do 'plugin', o qual está marcado para "uso futuro" pelo &Qt; Designer (por omissão: vazio).

`ConstructorArgs`

- Os argumentos a passar ao construtor da classe indicada por `ImplClass`; estes deverão estar entre parêntesis (por omissão: "`(parent)`"). A única variável que é garantido estar disponível é a `parent`, que é o `QWidget`-pai passado pelo &Qt; Designer.

  Este item é ignorado se estiver definido o valor de `CreateWidget`.

`CreateWidget`

- O código necessário para criar uma instância do elemento gráfico (por omissão: usa o `new` para criar uma instância da classe indicada pelo item `ImplClass`, passando os argumentos definidos em `ConstructorArgs`). Veja as notas sobre o `ImplClass` e o `ConstructorArgs`.

`DomXML`

- Uma descrição da UI em XML do elemento gráfico (por omissão: o valor fornecido pelos ficheiros de inclusão do 'plugin' do &Qt; Designer).

`Group`

- O grupo sob o qual mostrar o elemento no &Qt; Designer (por omissão: o valor do elemento `DefaultGroup` na secção `[Global]`).

`IconName`

- O ficheiro de imagem ou o nome do ícone-padrão a usar como ícone para este elemento na lista de elementos gráficos do &Qt; Designer (por omissão: um ficheiro PNG com o nome da secção, sem quaisquer dois-pontos duplos, na pasta "pics" de um ficheiro de recursos compilado; por exemplo, `:/pics/Xpto.png` na secção `[Xpto]`, ou `:/pics/XptoOla.png` na secção `[Xpto::Ola]`).

`ImplClass`

- A classe que deverá ser usada para criar uma instância do elemento para o usar no &Qt; Designer (por omissão: o nome da secção). Lembre-se que esta não tem de ser a classe que seria criada para uma aplicação final: isso é determinado pelo `DomXML`.

  Este item é ignorado se estiver definido o valor de `CreateWidget`.

`IncludeFile`

- O ficheiro que deverá ser incluído para usar este item gráfico (por omissão: a versão em minúsculas do nome da secção, retirando todos os dois-pontos e adicionando o texto ".h"; por exemplo, `xpto.h` na secção `[Xpto]`, ou `xptoola.h` na secção `[Xpto::Ola]`).

`IsContainer`

- Se este elemento poderá conter ou não outros elementos (por omissão: `false`).

`ToolTip`

- A dica a mostrar quando passar o cursor do rato sobre o elemento na lista de elementos gráficos no &Qt; Designer (por omissão: o nome da secção, com o texto " Widget" adicionado; por exemplo, `XPTO Widget` na secção `[XPTO]`).

`WhatsThis`

- O texto 'O que é Isto?' associado com o elemento no &Qt; Designer (por omissão: o nome da secção, com o texto " Widget" adicionado; por exemplo, `XPTO Widget` na secção `[XPTO]`).

## Exemplos

O ficheiro de descrição mais simples poderá ser algo do tipo

    [XPTO]
    ToolTip=Mostra elementos XPTO
    [Bar]
    ToolTip=Editor de barras

Repare que cada classe deverá ter pelo menos uma chave definida (`ToolTip` foi usado neste exemplo), caso contrário será ignorada.

Normalmente, irá querer alterar pelo menos o texto visível para o utilizador, o que corresponde aos itens `ToolTip`, `WhatsThis` e `Group`. Para além disso, definir o nome do 'plugin' poderá ser uma boa ideia para evitar possíveis conflitos de símbolos e para não confundir os depuradores (tanto a aplicação de depuração como a pessoa que efectua a mesma):

    [Global]
    PluginName=ElementosXPTO
    DefaultGroup=Visualização

    [XPTO]
    ToolTip=Mostra ursos
    WhatsThis=Um item de imagens que mostra ursos a dançar

    [Ola]
    ToolTip=Editor de barras
    WhatsThis=Uma interface de edição para barras para ursos
    Group=Edição

Poderão ser necessários ficheiros mais complexos, caso tenha classes com espaços de nomes ou opções extra que seja necessário passar aos construtores, como por exemplo:

    [Global]
    PluginName=ElementosXpto
    DefaultGroup=XPTO

    [XPTO::Ola]
    ToolTip=Mostra barras
    WhatsThis=Um elemento que mostra elementos de uma determinada forma
    IncludeFile=xpto/ola.h
    IconName=:/antevisoes/ola.png

    [XPTO::Ola2]
    IncludeFile=xpto/ola2.h
    ConstructorArgs=(XPTO::Ola2::UmaOpcao, parent)
    Group=XPTO (Especial)
    IsContainer=true
    IconName=:/antevisoes/ola2.png

Em alguns casos, os itens gráficos especialmente complexos poderão necessitar de uma implementação de uma "classe de antevisão" para usar no &Qt; Designer; esta poderá ser uma sub-classe do elemento real que simplesmente faz mais algumas configurações adicionais, ou poderá então ser uma implementação completamente diferente.

    [Global]
    Includes=xpto-antevisoes.h

    [ElementoBonito]
    ImplClass=ElementoBonitoAntevisao

## Veja Também

http://qt-project.org/doc/qt-5/designer-creating-custom-widgets.html

- A documentação do &Qt; Designer para criar 'plugins' de itens gráficos personalizados.

## Problemas

Use por favor o bugs.kde.org para comunicar os erros; não os envie directamente para os autores por e-mail.