KGENDESIGNERPLUGI(1)

NOME
kgendesignerplugin - Gera 'plugins' de elementos gráficos para o Qt(TM) Designer.

SINOPSE

kgendesignerplugin [OPÇÕES...] ficheiro

DESCRIÇÃO

Os 'plugins' de elementos gráficos personalizados do Qt(TM) 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(TM) 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(TM) 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(TM) Designer).

Group
    O grupo sob o qual mostrar o elemento no Qt(TM) 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(TM) 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(TM) 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(TM) 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(TM) 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(TM) 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(TM) Designer para criar 'plugins' de itens gráficos personalizados.

PROBLEMAS

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

AUTORES

Richard Johnson <rjohnson@kde.org>
    Criador da documentação original.

Alex Merry <alexmerry@kde.org>
    Actualizou a documentação para as Plataformas 5 do KDE.

NOTAS

1.  bugs.kde.org
    http://bugs.kde.org