En esta página

Incluir código externo

Los siguientes comandos te permiten incluir fragmentos de código procedentes de archivos externos. Puedes hacer que QDoc incluya el contenido completo de un archivo, o bien citar partes específicas del mismo y omitir otras. El uso habitual de esta última opción es citar un archivo fragmento por fragmento.

Nota: Aunque todos estos comandos pueden utilizarse para representar código C++, el \snippet y \codeline son preferibles a los demás. Estos comandos permiten sustituir los fragmentos de código C++ de la documentación por fragmentos equivalentes de otros lenguajes vinculados a Qt.

\quotefile

El comando ` \quotefile ` se expande para mostrar el contenido completo del archivo indicado como argumento.

El comando considera el resto de la línea como parte de su argumento, así que asegúrate de que el nombre del archivo vaya seguido de un salto de línea.

El contenido del archivo se muestra en un párrafo independiente, utilizando una fuente monoespaciada y la sangría estándar. El código se muestra tal cual.

/*!
   This is a simple "Hello world" example:

   \quotefile examples/main.cpp

   It contains only the bare minimum you need
   to get a Qt application up and running.
*/

A partir de la versión 6.11, se puede especificar un lenguaje como argumento opcional, sin distinción entre mayúsculas y minúsculas, en la misma línea que el comando « \quotefile ». Esto afecta al texto entre comillas de la misma forma que en el \code comando.

Por ejemplo:

\quotefile [text] examples/main.cpp

Esto puede resultar útil al citar un fragmento de un archivo que contenga código fuente que QDoc no pueda formatear.

Véase también \quotefromfile y \code.

\quotefromfile

El comando « \quotefromfile » abre el archivo indicado como argumento para generarle una cita.

El comando considera el resto de la línea como parte de su argumento, así que asegúrate de que el nombre del archivo vaya seguido de un salto de línea.

Este comando está pensado para citar fragmentos de un archivo con los comandos de guía paso a paso: \printline, \printto, \printuntil, \skipline, \skipto, \skipuntil. Esto te permite citar partes concretas de un archivo.

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp

   \skipto main
   \printuntil app(argc, argv)

   First we create a QApplication object using
   the \c argc and \c argv parameters.

   \skipto QPushButton
   \printuntil resize

   Then we create a QPushButton, and give it a reasonable
   size using the QWidget::resize() function.

   ...
*/

QDoc recuerda de qué archivo se está extrayendo el texto y la posición actual en dicho archivo (consulta \printline para obtener más información). No es necesario «cerrar» el archivo.

A partir de la versión 6.11, se puede especificar un idioma como argumento opcional, sin distinción entre mayúsculas y minúsculas, en la misma línea que el comando « \quotefromfile ». Esto influye en el texto citado de la misma forma que en el comando \code comando.

Por ejemplo:

\quotefromfile [text] examples/main.cpp
\skipto main
\printuntil app(argc, argv)

QDoc también recuerda de qué lenguaje de programación procede la cita, por lo que comandos como \printline, \printto y \printuntil se extraen del archivo actual, aplicando un estilo de marcado coherente hasta que se lea un nuevo archivo.

Véase también \quotefile, \code y \dots.

\printline

El comando « \printline » se expande a la línea desde la posición actual.

Para garantizar que la documentación se mantenga sincronizada con el archivo fuente, se debe especificar una subcadena de la línea como argumento del comando. Ten en cuenta que el comando considera el resto de la línea como parte de su argumento, así que asegúrate de que la subcadena vaya seguida de un salto de línea.

La línea del archivo fuente se muestra como un párrafo independiente, utilizando una fuente monoespaciada y la sangría estándar. El código se muestra tal cual.

/*!
   There has to be exactly one QApplication object
   in every GUI application that uses Qt.

   \quotefromfile examples/main.cpp

   \printline QApplication

   This line includes the QApplication class
   definition. QApplication manages various
   application-wide resources, such as the
   default font and cursor.

   \printline QPushButton

   This line includes the QPushButton class
   definition. The QPushButton widget provides a command
   button.

   \printline main

   The main function...
*/

QDoc lee el archivo de forma secuencial. Para avanzar la posición actual, puedes utilizar cualquiera de los comandos «\skip... ». Para retroceder la posición actual, puedes volver a utilizar el \quotefromfile comando de nuevo.

Si el argumento de la subcadena está entre barras, se interpreta como un regular expression.

/*!
   \quotefromfile examples/mainwindow.cpp

   \skipto closeEvent
   \printuntil /^\}/

   Close events are sent to widgets that the users want to
   close, usually by clicking \c File|Exit or by clicking
   the \c X title bar button. By reimplementing the event
   handler, we can intercept attempts to close the
   application.
*/

(El archivo de ejemplo completo...)

La expresión regular /^\}/ hace que QDoc muestre hasta el primer carácter «}» que aparezca al principio de la línea sin sangría. /.../ enmarca la expresión regular, y «^» significa el principio de la línea. El carácter «}» debe escaparse, ya que es un carácter especial en las expresiones regulares.

QDoc emitirá una advertencia si no se puede localizar la subcadena o la expresión regular especificadas, es decir, si el código fuente ha cambiado.

Véase también \printto y \printuntil.

\printto

El comando « \printto » se expande a todas las líneas desde la posición actual hasta la siguiente línea que contenga una subcadena determinada, excluida esta última.

El comando considera el resto de la línea como parte de su argumento, así que asegúrate de que la subcadena vaya seguida de un salto de línea. El comando también sigue las mismas convenciones de posicionamiento y argumentos que el \printline comando.

Las líneas del archivo fuente se muestran en un párrafo independiente, utilizando una fuente monoespaciada y la sangría estándar. El código se muestra tal cual.

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \printto hello

   First we create a QApplication object using the \c argc and
   \c argv parameters...
*/

Véase también \printline y \printuntil.

\printuntil

El comando « \printuntil » se expande a todas las líneas desde la posición actual hasta la siguiente línea que contenga una subcadena determinada, incluida esta.

El comando considera el resto de la línea como parte de su argumento, así que asegúrate de que la subcadena vaya seguida de un salto de línea. El comando también sigue las mismas convenciones de posicionamiento y argumentos que el \printline comando.

Si se utiliza « \printuntil » sin ningún argumento, se expande a todas las líneas desde la posición actual hasta el final del archivo entre comillas.

Las líneas del archivo de origen se muestran en un párrafo independiente, utilizando una fuente monoespaciada y la sangría estándar. El código se muestra tal cual.

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil hello

   First we create a QApplication object using the
   \c argc and \c argv parameters, then we create
   a QPushButton.
*/

Véase también \printline y \printto.

\skipline

El comando « \skipline » ignora la siguiente línea que no esté en blanco del archivo fuente actual.

Doc lee el archivo de forma secuencial, y el comando « \skipline » se utiliza para desplazar la posición actual (omitiendo una línea del archivo fuente). Véase la observación anterior sobre el posicionamiento en el archivo.

El comando considera el resto de la línea como parte de su argumento; asegúrate de que la subcadena vaya seguida de un salto de línea. El comando también sigue las mismas convenciones para los argumentos que el \printline , y se utiliza junto con el \quotefromfile .

/*!
   QPushButton is a GUI push button that the user
   can press and release.

   \quotefromfile examples/main.cpp
   \skipline QApplication
   \printline QPushButton

   This line includes the QPushButton class
   definition. For each class that is part of the
   public Qt API, there exists a header file of
   the same name that contains its definition.
*/

Véase también \skipto, \skipuntil y \dots.

\skipto

El comando « \skipto » ignora todas las líneas desde la posición actual hasta la siguiente línea que contenga una subcadena determinada, excluida esta última.

QDoc lee el archivo de forma secuencial, y el comando « \skipto » se utiliza para desplazar la posición actual (omitiendo una o varias líneas del archivo fuente). Véase la observación anterior sobre el posicionamiento en el archivo.

El comando considera el resto de la línea como parte de su argumento; asegúrate de que la subcadena vaya seguida de un salto de línea.

El comando también sigue las mismas convenciones para los argumentos que el \printline , y se utiliza junto con el \quotefromfile .

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil }

   First we create a QApplication object. There
   has to be exactly one such object in
   every GUI application that uses Qt. Then
   we create a QPushButton, resize it to a reasonable
   size ...
*/

Véase también \skipline, \skipuntil y \dots.

\skipuntil

El comando « \skipuntil » ignora todas las líneas desde la posición actual hasta la siguiente línea que contenga una subcadena determinada, incluida esta última.

QDoc lee el archivo de forma secuencial, y el comando « \skipuntil » se utiliza para desplazar la posición actual (omitiendo una o varias líneas del archivo fuente). Véase la observación anterior sobre el posicionamiento en el archivo.

El comando considera el resto de la línea como parte de su argumento; asegúrate de que la subcadena vaya seguida de un salto de línea.

El comando también sigue las mismas convenciones para los argumentos que el \printline , y se utiliza junto con el \quotefromfile .

/*!
   The first thing we did in the \c main() function
   was to create a QApplication object \c app.

   \quotefromfile examples/main.cpp
   \skipuntil show
   \dots
   \printuntil }

   In the end we must remember to make \c main() pass the
   control to Qt. QCoreApplication::exec() will return when
   the application exits...
*/

Véase también \skipline, \skipto y \dots.

\dots

El comando « \dots » indica que se han omitido partes del archivo fuente al citar un archivo.

Este comando se utiliza junto con el \quotefromfile , y debe escribirse en una línea aparte. Los puntos se muestran en una nueva línea, utilizando una fuente monoespaciada.

/*!
   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil {
   \dots
   \skipuntil exec
   \printline }
*/

La sangría predeterminada es de 4 espacios, pero se puede ajustar mediante el argumento opcional del comando.

/*!
    \dots 0
    \dots
    \dots 8
    \dots 12
    \dots 16
*/

Véase también \skipline, \skipto y \skipuntil.

\snippet

El comando « \snippet » hace que se incluya un fragmento de código tal cual, como texto preformateado, que puede aparecer con resaltado de sintaxis.

Cada fragmento de código se identifica mediante el archivo que lo contiene y mediante un identificador único para dicho archivo. Los archivos de fragmentos suelen almacenarse en un directorio « snippets » dentro del directorio de documentación (por ejemplo, $QTDIR/doc/src/snippets).

Nota: QDoc resuelve una ruta relativa de fragmento en función de los directorios configurados por las variables exampledirs e imagedirs (además de cualquier directorio doc/images que se encuentre bajo los directorios de ejemplos). No busca en sourcedirs ni en headerdirs, por lo que los archivos de fragmentos que se encuentren en un árbol distinto al de los ejemplos deben seguir siendo accesibles desde exampledirs o imagedirs. El \quotefile y \quotefromfile resuelven sus archivos de la misma manera.

QDoc utiliza el primer archivo coincidente que encuentra. Cuando existe la misma ruta relativa en más de un directorio de búsqueda, QDoc consulta los directorios en orden lexicográfico, por lo que un archivo puede ocultarse tras otro.

Por ejemplo, la siguiente documentación hace referencia a un fragmento de código en un archivo que se encuentra en un subdirectorio del directorio de documentación:

\snippet snippets/textdocument-resources/main.cpp Adding a resource

El texto que sigue al nombre del archivo es el identificador único del fragmento de código. Se utiliza para delimitar el código entre comillas en el archivo del fragmento correspondiente, tal y como se muestra en el siguiente ejemplo, que se corresponde con el comando anterior « \snippet »:

    ...
    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));

//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...

Por defecto, QDoc busca « //! » como marcador de fragmento de código. En los archivos « .pro », « .py », « .cmake » y « CMakeLists.txt », se detecta « #! ». Por último, « <!-- » se acepta en los archivos « .html », « .qrc », « .ui », « .xml » y « .xq ».

QDoc normaliza la sangría de los fragmentos de código comparando la sangría basada en espacios del marcador del fragmento con la sangría mínima del contenido del fragmento (ignorando las macros de Qt, las líneas en blanco y los comentarios que ocupan toda la línea). A continuación, desindenta automáticamente el cuerpo del fragmento hasta el valor más pequeño, lo que garantiza que el código generado conserve siempre su estructura natural, independientemente de dónde se encuentren los marcadores. Los marcadores con indentación insuficiente no se modifican.

Nota: QDoc solo tiene en cuenta los espacios para la normalización de la sangría, no las tabulaciones ni otros caracteres de espacio en blanco. Para obtener los mejores resultados, utiliza una sangría basada en espacios de forma coherente en los archivos fuente que contengan fragmentos de código.

A partir de la versión 6.11, se puede especificar un lenguaje como argumento opcional que no distingue entre mayúsculas y minúsculas en la misma línea que el comando « \snippet ». Esto influye en el texto entre comillas de la misma forma que en el comando \code comando.

En este ejemplo de uso del comando se anula el estilo de marcado predeterminado de C++ y, en su lugar, se genera texto sin formato:

\snippet [text] code.cpp

Esto puede resultar útil a la hora de citar un lenguaje que QDoc no puede formatear, o cuando se necesita citar un archivo con un nombre poco convencional.

\codeline

El comando « \codeline » inserta una línea en blanco de texto preformateado. Se utiliza para insertar espacios entre fragmentos sin cerrar el área de texto preformateado actual ni abrir una nueva.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.