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.cppEsto 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 resourceEl 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.cppEsto 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.