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

<refentry lang="&language;">

<refentryinfo>
  <title
>Frameworks del &kde;: KDesignerPlugin</title>
  <author
><firstname
>Richard</firstname
> <surname
>Johnson</surname
> <contrib
>Va escriure la documentació original.</contrib>
    <affiliation>
      <address
><email
>rjohnson@kde.org</email
></address>
    </affiliation>
  </author>
  <author
><firstname
>Alex</firstname
> <surname
>Merry</surname
> <contrib
>Ha actualitzat la documentació al &kde; Frameworks 5.</contrib>
    <affiliation>
      <address
><email
>alexmerry@kde.org</email
></address>
    </affiliation>
  </author>
  <date
>28 de maig de 2014</date>
  <releaseinfo
>Frameworks 5.0</releaseinfo>
  <productname
>Frameworks del KDE</productname>
</refentryinfo>

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



<refnamediv>
  <refname
><command
>kgendesignerplugin</command
></refname>
  <refpurpose
>Genera connectors d'estri pel &Qt; Designer. </refpurpose>
</refnamediv>



<refsynopsisdiv>
  <cmdsynopsis
><command
>kgendesignerplugin</command
> <group choice="opt" rep="repeat"
><replaceable class="option"
>OPCIONS</replaceable
></group
> <arg choice="plain"
><replaceable
>fitxer</replaceable
></arg
> </cmdsynopsis>
</refsynopsisdiv>



<refsect1>
  <title
>Descripció</title>
  <para
>Els connectors d'estri personalitzats pel &Qt; Designer solen seguir un patró estàndard, i les classes proporcionades pel connector proporcionen principalment informació estàtica, juntament amb la funció de crear una instància que normalment només és una crida de constructor simple. <command
>kgendesignerplugin</command
> permet als desenvolupadors de biblioteques que proporcionen estris nous, el fet de crear un connector d'aquest tipus sense necessitat de crear tot el codi repetitiu associat, proporcionant un simple fitxer de descripció d'estil ini. </para>

  <para
><command
>kgendesignerplugin</command
> tria els valors per omissió per a la majoria dels ajustaments, de manera que sol ser necessària una configuració mínima. </para>
</refsect1>



<refsect1>
  <title
>Opcions</title>
  <variablelist>
    <varlistentry>
      <term
><option
>-o <replaceable
>fitxer</replaceable
></option
></term>
      <listitem>
        <para
>El nom per al fitxer C++ generat. Si no es dóna, s'utilitza la sortida estàndard (<varname
>stdout</varname
>). </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term
><option
>-n <replaceable
>nom_del_connector</replaceable
></option
></term>
      <listitem>
        <para
>Es proporciona per compatibilitat. El valor per omissió per a l'opció PluginName al fitxer d'entrada. </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term
><option
>-g <replaceable
>grup</replaceable
></option
></term>
      <listitem>
        <para
>Es proporciona per compatibilitat. El valor per omissió per a l'opció DefaultGroup al fitxer d'entrada. </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term
><option
>--author</option
></term>
      <listitem>
        <para
>Mostra informació sobre l'autor.</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term
><option
>--license</option
></term>
      <listitem>
        <para
>Mostra informació sobre la llicència.</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term
><option
>-h, --help</option
></term>
      <listitem>
        <para
>Mostra un text breu d'ajuda.</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term
><option
>-v, --version</option
></term>
      <listitem>
        <para
>Mostra informació sobre la versió.</para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>



<refsect1>
  <title
>Format del fitxer</title>
  <para
>El fitxer d'entrada és un fitxer de configuració d'estil ini (en concret, és el format implementat per l'entorn de treball KConfig), el qual descriu un conjunt d'estris. Conté una secció <literal
>[Global]</literal
>, la qual proporciona informació general sobre el connector, i una secció per a cada estri que s'ha d'incloure en el connector. </para>

  <para
>La secció <literal
>[Global]</literal
> conté les següents entrades: <variablelist>
      <varlistentry>
        <term
><varname
>DefaultGroup</varname
></term>
        <listitem>
          <para
>El valor per omissió per a l'entrada <varname
>Group</varname
> en les seccions de classe (per omissió: «<literal
>Custom</literal
>», a menys que s'indiqui l'opció <option
>-g</option
>). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>Includes</varname
></term>
        <listitem>
          <para
>Una llista (separada per comes) dels «includes» requerits (per omissió: buida). Tingueu en compte que els fitxers de capçalera pels estris especificats més endavant al fitxer no s'han de llistar aquí. En canvi, això és per a les capçaleres especials per a l'ús propi del connector, com les de les classes que proporcionen vistes prèvies. </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>PluginName</varname
></term>
        <listitem>
          <para
>El nom de la classe de C++ principal en el connector (per omissió: «<literal
>WidgetsPlugin</literal
>», a menys que s'indiqui l'opció <option
>-n</option
>). </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </para>

  <para
>Cada classe ha de tenir la seva pròpia secció <literal
>[<replaceable
>ClassName</replaceable
>]</literal
>, la qual pot incloure les següents entrades: <variablelist>
      <varlistentry>
        <term
><varname
>CodeTemplate</varname
></term>
        <listitem>
          <para
>El valor retornat per la funció <code
>codeTemplate()</code
> del connector, la qual és marcada per a «ús futur» pel &Qt; Designer (per omissió: buida). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>ConstructorArgs</varname
></term>
        <listitem>
          <para
>Els arguments que s'ha de passar al constructor de la classe indicada per <literal
>ImplClass</literal
>. Aquests han d'estar envoltats entre parèntesis (per omissió: «<literal
>(parent)</literal
>»). L'única variable garantida que estarà disponible és la <varname
>parent</varname
>, la qual és la pare de <code
>QWidget</code
> passada pel &Qt; Designer. </para>
          <para
>Aquesta entrada serà ignorada si s'estableix <literal
>CreateWidget</literal
>. </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>CreateWidget</varname
></term>
        <listitem>
          <para
>El codi necessari per crear una instància de l'estri (per omissió: utilitza <code
>new</code
> per crear una instància de la classe indicada per l'entrada <literal
>ImplClass</literal
>, passant els arguments especificats per <literal
>ConstructorArgs</literal
>). Vegeu les notes per a <literal
>ImplClass</literal
> i <literal
>ConstructorArgs</literal
>. </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>DomXML</varname
></term>
        <listitem>
          <para
>Una descripció IU en XML de l'estri (per omissió: el valor per omissió proporcionat per les capçaleres al connector del &Qt; Designer). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>Group</varname
></term>
        <listitem>
          <para
>El grup per mostrar l'estri sota el &Qt; Designer (per omissió: el valor de l'entrada <varname
>DefaultGroup</varname
> a la secció <literal
>[Global]</literal
>). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>IconName</varname
></term>
        <listitem>
          <para
>El fitxer d'imatge o nom d'icona estàndard que s'utilitza com a icona per aquest estri en la llista d'estris del &Qt; Designer (per omissió: un fitxer PNG anomenat amb el nom de la secció, eliminant qualsevol caràcter de dos punts, al directori «pics» dins d'un fitxer de recursos compilat. Per exemple, <filename
>:/pics/Foo.png</filename
> a la secció <literal
>[Foo]</literal
>, o <filename
>:/pics/FooBar.png</filename
> a la secció <literal
>[Foo::Bar]</literal
>). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>ImplClass</varname
></term>
        <listitem>
          <para
>La classe que s'ha d'utilitzar per crear una instància de l'estri per a l'ús del &Qt; Designer (per omissió: el nom de la secció). Tingueu en compte que aquest en realitat no ha de per què ser la classe que es crearia per a una aplicació final: està determinat per la <literal
>DomXML</literal
>. </para>
          <para
>Aquesta entrada serà ignorada si s'estableix <literal
>CreateWidget</literal
>. </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>IncludeFile</varname
></term>
        <listitem>
          <para
>La capçalera que s'ha d'incloure per utilitzar-la amb aquest estri (per omissió: la versió en minúscules del nom de la secció, eliminant qualsevol caràcter de dos punts i annexant «*.h». Per exemple, <literal
>foo.h</literal
> a la secció <literal
>[Foo]</literal
>, o <literal
>foobar.h</literal
> a la secció <literal
>[Foo::Bar]</literal
>). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>IsContainer</varname
></term>
        <listitem>
          <para
>Si aquest estri pot contenir altres estris (per omissió: <literal
>false</literal
>). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>ToolTip</varname
></term>
        <listitem>
          <para
>El consell d'eina que es mostrarà quan es passi per sobre de l'estri a la llista d'estris del &Qt; Designer (per omissió: el nom de la secció, amb «Widget» annexat. Per exemple, <literal
>Foo Widget</literal
> a la secció <literal
>[Foo]</literal
>). </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term
><varname
>WhatsThis</varname
></term>
        <listitem>
          <para
>El text de «Què és això» associat amb l'estri al &Qt; Designer (per omissió: el nom de la secció, amb «Widget» annexat. Per exemple, <literal
>Foo Widget</literal
> a la secció <literal
>[Foo]</literal
>). </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </para>
</refsect1>



<refsect1>
  <title
>Exemples</title>
  <para
>El fitxer de descripció més simple podria semblar-se a això <screen language="ini">
<![CDATA[
[Foo]
ToolTip=Displays foos
[Bar]
ToolTip=Bar editor
]]>
    </screen
> Tingueu en compte que cada classe almenys haurà de tenir un conjunt de claus (en aquest exemple s'utilitza <literal
>ToolTip</literal
>), en cas contrari s'ignorarà. </para>
  <para
>Usualment, voldreu canviar el text a almenys visible per l'usuari, el qual vol dir les entrades <literal
>ToolTip</literal
>, <literal
>WhatsThis</literal
> i <literal
>Group</literal
>. A més, establir el nom del connector pot ser una bona idea per evitar possibles col·lisions de símbol i no confondre als depuradors (tant l'aplicació del depurador com la persona que realitza la depuració): <screen language="ini"
><![CDATA[
[Global]
PluginName=FooWidgets
DefaultGroup=Display

[Foo]
ToolTip=Displays bears
WhatsThis=An image widget that displays dancing bears

[Bar]
ToolTip=Bar editor
WhatsThis=An editor interface for bars for bears
Group=Editing
]]>
    </screen>
  </para>
  <para
>Poden ser necessaris fitxers més complexos si teniu classes d'espais de nom o opcions addicionals que necessiten ser subministrades als constructors, per exemple: <screen language="ini"
><![CDATA[
[Global]
PluginName=FooWidgets
DefaultGroup=Foo

[Foo::Bar]
ToolTip=Displays bars
WhatsThis=A widget that displays bars in a particular way
IncludeFile=foo/bar.h
IconName=:/previews/bar.png

[Foo::Baz]
IncludeFile=foo/baz.h
ConstructorArgs=(Foo::Baz::SomeOption, parent)
Group=Foo (Special)
IsContainer=true
IconName=:/previews/baz.png
]]>
    </screen>
  </para>
  <para
>De vegades els estris especialment complexos poden necessitar una implementació «classe de vista prèvia» especial per al seu ús en el &Qt; Designer. Aquesta podria ser una subclasse de l'estri real, la qual només faria algun ajustament addicional, o podria ser una implementació completament diferent. <screen language="ini"
><![CDATA[
[Global]
Includes=foopreviews.h

[FancyWidget]
ImplClass=FancyWidgetPreview
]]>
    </screen>
  </para>
</refsect1>



<refsect1>
  <title
>Vegeu també</title>
  <variablelist>
    <varlistentry>
      <term>
        <uri
>https://doc.qt.io/qt-5/designer-creating-custom-widgets.html</uri>
      </term>
      <listitem>
        <para
>La documentació del &Qt; Designer sobre la creació de connectors per a estris personalitzats.</para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>



<refsect1>
  <title
>Errors</title>
  <para
>Si us plau, empreu el <ulink url="http://bugs.kde.org"
>seguidor d'errors del KDE</ulink
> (escriviu-hi en anglès) per a informar-ne, no envieu cap correu directament als autors. </para>
</refsect1>

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