<?xml version="1.0" ?>
<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
"dtd/kdedbx45.dtd" [
<!ENTITY % Brazilian-Portuguese "INCLUDE">
]>

<refentry lang="&language;">

<refentryinfo>
  <title
>&kde; Frameworks: KDesignerPlugin</title>
  <author
><firstname
>Richard</firstname
> <surname
>Johnson</surname
> <contrib
>Escreveu a documentação original.</contrib>
    <affiliation>
      <address
><email
>rjohnson@kde.org</email
></address>
    </affiliation>
  </author>
  <author
><firstname
>Alex</firstname
> <surname
>Merry</surname
> <contrib
>Atualizou a documentação para o &kde; Frameworks 5.</contrib>
    <affiliation>
      <address
><email
>alexmerry@kde.org</email
></address>
    </affiliation>
  </author>
  <date
>28/05/2014</date>
  <releaseinfo
>Frameworks 5.0</releaseinfo>
  <productname
>KDE Frameworks</productname>
</refentryinfo>

<refmeta>
  <refentrytitle
><command
>kgendesignerplugin</command
></refentrytitle>
  <manvolnum
>1</manvolnum>
</refmeta>



<refnamediv>
  <refname
><command
>kgendesignerplugin</command
></refname>
  <refpurpose
>Gera plugins de widgets para o &Qt; Designer. </refpurpose>
</refnamediv>



<refsynopsisdiv>
  <cmdsynopsis
><command
>kgendesignerplugin</command
> <group choice="opt" rep="repeat"
><replaceable class="option"
>OPÇÕES</replaceable
></group
> <arg choice="plain"
><replaceable
>arquivo</replaceable
></arg
> </cmdsynopsis>
</refsynopsisdiv>



<refsect1>
  <title
>Descrição</title>
  <para
>Os plugins de widgets 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 <command
>kgendesignerplugin</command
> permite aos desenvolvedores das bibliotecas que fornecem novos widgets, a criação de um desses plugins, sem a necessidade de criar todo o código acessório associado, oferecendo um arquivo de descrição do tipo INI. </para>

  <para
>O <command
>kgendesignerplugin</command
> escolhe opções predefinidas para a maioria das definições, sendo necessária apenas alguma configuração mínima. </para>
</refsect1>



<refsect1>
  <title
>Opções</title>
  <variablelist>
    <varlistentry>
      <term
><option
>-o <replaceable
>arquivo</replaceable
></option
></term>
      <listitem>
        <para
>O nome do arquivo em C++ gerado. Se não for indicado, será usado o <varname
>stdout</varname
>. </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term
><option
>-n <replaceable
>nome-plugin</replaceable
></option
></term>
      <listitem>
        <para
>Fornecido para fins de compatibilidade. O valor padrão da opção 'PluginName' no arquivo de entrada. </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term
><option
>-g <replaceable
>grupo</replaceable
></option
></term>
      <listitem>
        <para
>Fornecido para fins de compatibilidade. O valor padrão da opção 'DefaultGroup' no arquivo de entrada. </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term
><option
>--author</option
></term>
      <listitem>
        <para
>Mostra informações sobre o autor.</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term
><option
>--license</option
></term>
      <listitem>
        <para
>Mostra informações sobre a licença.</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term
><option
>-h, --help</option
></term>
      <listitem>
        <para
>Mostra um breve texto de ajuda.</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term
><option
>-v, --version</option
></term>
      <listitem>
        <para
>Mostra informações sobre a versão.</para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>



<refsect1>
  <title
>Formato do arquivo</title>
  <para
>O arquivo de entrada é um arquivo de configuração do tipo INI (para ser mais específico, está no formato suportado pelo framework KConfig) que descreve um conjunto de widgets. Contém uma seção <literal
>[Global]</literal
>, que oferece informações gerais sobre o plugin, assim como uma seção para cada widget que deverá ser incluído no plugin. </para>

  <para
>A seção <literal
>[Global]</literal
> pode ter os seguintes itens: <variablelist>
      <varlistentry>
        <term
><varname
>DefaultGroup</varname
></term>
        <listitem>
          <para
>O valor padrão para o item <varname
>Group</varname
> nas seções das classes (padrão: "<literal
>Custom</literal
>", a menos que seja usada a opção <option
>-g</option
>). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>Includes</varname
></term>
        <listitem>
          <para
>Uma lista (separada por vírgulas) dos arquivos de inclusão necessários (padrão: em branco). Repare que os arquivos de cabeçalho dos widgets definidos posteriormente no arquivo não devem ser indicados aqui. Em vez disso, este campo serve para arquivos de cabeçalho especiais para uso do próprio plugin, como os das classes que fornecem visualizações. </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>PluginName</varname
></term>
        <listitem>
          <para
>Nome da classe principal em C++ no plugin (padrão: "<literal
>WidgetsPlugin</literal
>", a menos que seja usada a opção <option
>-n</option
>). </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </para>

  <para
>Cada classe deverá ter a sua própria seção <literal
>[<replaceable
>ClassName</replaceable
>]</literal
>, a qual poderá incluir os seguintes itens: <variablelist>
      <varlistentry>
        <term
><varname
>CodeTemplate</varname
></term>
        <listitem>
          <para
>O valor devolvido pela função <code
>codeTemplate()</code
> do plugin, o qual está marcado para "uso futuro" pelo &Qt; Designer (padrão: em branco). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>ConstructorArgs</varname
></term>
        <listitem>
          <para
>Os argumentos para passar ao construtor da classe indicada por <literal
>ImplClass</literal
>; estes devem estar entre parênteses (padrão: "<literal
>(parent)</literal
>"). A única variável que está com certeza disponível é a <varname
>parent</varname
>, que é o <code
>QWidget</code
>pai passado pelo &Qt; Designer. </para>
          <para
>Este item é ignorado se estiver definido como <literal
>CreateWidget</literal
>. </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>CreateWidget</varname
></term>
        <listitem>
          <para
>O código necessário para criar uma instância do widget (padrão: usa o <code
>new</code
> para criar uma instância da classe indicada pelo item <literal
>ImplClass</literal
>, passando os argumentos definidos em <literal
>ConstructorArgs</literal
>). Veja as notas sobre o <literal
>ImplClass</literal
> e o <literal
>ConstructorArgs</literal
>. </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>DomXML</varname
></term>
        <listitem>
          <para
>Uma descrição da interface gráfica em XML do widget (padrão: o valor fornecido pelos arquivos de cabeçalho do plugin do &Qt; Designer). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>Group</varname
></term>
        <listitem>
          <para
>O grupo sob o qual mostrar o widget no &Qt; Designer (padrão: o valor do item <varname
>DefaultGroup</varname
> na seção <literal
>[Global]</literal
>). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>IconName</varname
></term>
        <listitem>
          <para
>Arquivo de imagem ou nome do ícone padrão a ser usado como ícone para este widget na lista de widgets do &Qt; Designer (padrão: um arquivo PNG com o nome da seção, sem quaisquer dois pontos duplos, na pasta "pics" de um arquivo de recursos compilado. Por exemplo, <filename
>:/pics/Foo.png</filename
> na seção <literal
>[Foo]</literal
> ou <filename
>:/pics/FooBar.png</filename
> na seção <literal
>[Foo::Bar]</literal
>). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>ImplClass</varname
></term>
        <listitem>
          <para
>A classe que deverá ser usada para criar uma instância do widget para ser usado no &Qt; Designer (padrão: nome da seção). Lembre-se de que esta não precisa ser a classe que seria criada para um aplicativo final: isso é determinado pelo <literal
>DomXML</literal
>. </para>
          <para
>Este item é ignorado se estiver definido como <literal
>CreateWidget</literal
>. </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>IncludeFile</varname
></term>
        <listitem>
          <para
>O cabeçalho que deverá ser incluído para usar este widget (padrão: a versão em minúsculo do nome da seção, retirando todos os dois pontos e adicionando o texto ".h". Por exemplo, <literal
>foo.h</literal
> na seção <literal
>[Foo]</literal
> ou <literal
>foobar.h</literal
> na seção <literal
>[Foo::Bar]</literal
>). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>IsContainer</varname
></term>
        <listitem>
          <para
>Se este widget pode conter ou não outros widgets (padrão: <literal
>false</literal
>). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>ToolTip</varname
></term>
        <listitem>
          <para
>A dica a ser exibida quando passar o ponteiro do mouse sobre o widget na lista de widgets do &Qt; Designer (padrão: o nome da seção, com o texto " Widget" adicionado. Por exemplo, <literal
>Foo Widget</literal
> na seção <literal
>[Foo]</literal
>). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>WhatsThis</varname
></term>
        <listitem>
          <para
>O texto 'O que é isto?' associado com o widget no &Qt; Designer (padrão: o nome da seção, com o texto " Widget" adicionado. Por exemplo, <literal
>Foo Widget</literal
> na seção <literal
>[Foo]</literal
>). </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </para>
</refsect1>



<refsect1>
  <title
>Exemplos</title>
  <para
>O arquivo de descrição mais simples poderá ser algo do tipo <screen language="ini">
<![CDATA[
[Foo]
ToolTip=Displays foos
[Bar]
ToolTip=Bar editor
]]>
    </screen
> Repare que cada classe deverá ter pelo menos uma chave definida (<literal
>ToolTip</literal
> foi usado neste exemplo), caso contrário, será ignorada. </para>
  <para
>Normalmente, você vai querer alterar pelo menos o texto visível ao usuário, o que corresponde aos itens <literal
>ToolTip</literal
>, <literal
>WhatsThis</literal
> e <literal
>Group</literal
>. 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 o aplicativo de depuração quanto a pessoa que efetua a mesma): <screen language="ini"
><![CDATA[
[Global]
PluginName=QualquerWidget
DefaultGroup=Visualização

[Foo]
ToolTip=Mostra ursos
WhatsThis=Um widget de imagens que mostra ursos dançando

[Bar]
ToolTip=Editor de barras
WhatsThis=Uma interface de edição de barras para ursos
Group=Edição
]]>
    </screen>
  </para>
  <para
>Pode ser necessário arquivos mais complexos, caso tenha classes com espaços de nomes ou opções extras que seja necessário passar aos construtores, como por exemplo: <screen language="ini"
><![CDATA[
[Global]
PluginName=QualquerWidget
DefaultGroup=Foo

[Foo::Bar]
ToolTip=Mostra barras
WhatsThis=Um widget que mostra as barras de uma determinada forma
IncludeFile=foo/bar.h
IconName=:/previews/bar.png

[Foo::Baz]
IncludeFile=foo/baz.h
ConstructorArgs=(Foo::Baz::SomeOption, parent)
Group=Foo (Especial)
IsContainer=true
IconName=:/previews/baz.png
]]>
    </screen>
  </para>
  <para
>Em alguns casos, os widgets muito complexos poderão necessitar da implementação de uma "classe de visualização" para usar no &Qt; Designer; esta poderá ser uma subclasse do widget real que simplesmente faz mais algumas configurações adicionais, ou poderá então ser uma implementação completamente diferente. <screen language="ini"
><![CDATA[
[Global]
Includes=visualizacoes.h

[WidgetBonito]
ImplClass=WidgetBonitoVisualização
]]>
    </screen>
  </para>
</refsect1>



<refsect1>
  <title
>Veja também</title>
  <variablelist>
    <varlistentry>
      <term>
        <uri
>http://qt-project.org/doc/qt-5/designer-creating-custom-widgets.html</uri>
      </term>
      <listitem>
        <para
>A documentação do &Qt; Designer para criação de plugins para widgets personalizados.</para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>



<refsect1>
  <title
>Problemas</title>
  <para
>Use por favor o <ulink url="http://bugs.kde.org"
>bugs.kde.org</ulink
> para reportar erros; não os envie diretamente para os autores por e-mail. </para>
</refsect1>

</refentry>
<!--
vim:sts=2:sw=2:et
-->
