En esta página

La interfaz QTextCursor

Los documentos se pueden editar mediante la interfaz que proporciona la clase ` QTextCursor `; los cursores se crean mediante un constructor o se obtienen de un widget de editor. El cursor se utiliza para realizar operaciones de edición que se corresponden exactamente con aquellas que el usuario puede realizar por sí mismo en un editor. Como resultado, la información sobre la estructura del documento también está disponible a través del cursor, lo que permite modificar dicha estructura. El uso de una interfaz orientada al cursor para la edición simplifica a los desarrolladores el proceso de creación de un editor personalizado, ya que las operaciones de edición se pueden visualizar fácilmente.

La clase ` QTextCursor ` también mantiene información sobre cualquier texto que haya seleccionado en el documento, siguiendo de nuevo un modelo que es conceptualmente similar a las acciones que realiza el usuario para seleccionar texto en un editor.

Los documentos de texto enriquecido pueden tener varios cursores asociados, y cada uno de ellos contiene información sobre su posición en el documento y las selecciones que pueda contener. Este paradigma basado en el cursor hace que las operaciones comunes, como cortar y pegar texto, sean fáciles de implementar mediante programación, al tiempo que permite realizar operaciones de edición más complejas en el documento.

En este capítulo se describen la mayoría de las operaciones de edición habituales que deberá realizar utilizando un cursor, desde la inserción básica de texto y elementos del documento hasta la manipulación más compleja de las estructuras del documento.

Edición basada en el cursor

En su forma más simple, los documentos de texto se componen de una cadena de caracteres, marcados de alguna manera para representar la estructura en bloques del texto dentro del documento. QTextCursor proporciona una interfaz basada en el cursor que permite manipular el contenido de un QTextDocument a nivel de caracteres. Dado que los elementos (bloques, marcos, tablas, etc.) también están codificados en el flujo de caracteres, la propia estructura del documento puede modificarse mediante el cursor.

El cursor realiza un seguimiento de su ubicación dentro del documento principal y puede proporcionar información sobre la estructura circundante, como el bloque de texto, el marco, la tabla o la lista que lo envuelve. Los formatos de las estructuras circundantes también pueden obtenerse directamente a través del cursor.

Uso de un cursor

El uso principal de un cursor es insertar o modificar texto dentro de un bloque. Podemos utilizar el cursor de un editor de texto para ello:

    QTextEdit *editor = new QTextEdit();
    QTextCursor cursor(editor->textCursor());

Como alternativa, podemos obtener un cursor directamente de un documento:

    QTextDocument *document = new QTextDocument(editor);
    QTextCursor cursor(document);

El cursor se sitúa al principio del documento para que podamos escribir en el primer bloque (vacío) del mismo.

Agrupación de operaciones del cursor

Es posible agrupar una serie de operaciones de edición para poder reproducirlas o deshacerlas juntas en una sola acción. Esto se consigue utilizando las funciones ` beginEditBlock() ` y ` endEditBlock() ` de la siguiente manera, tal y como se muestra en el ejemplo siguiente, en el que seleccionamos la palabra que contiene el cursor:

    cursor.beginEditBlock();
    cursor.movePosition(QTextCursor::StartOfWord);
    cursor.movePosition(QTextCursor::EndOfWord, QTextCursor::KeepAnchor);
    cursor.endEditBlock();

Si las operaciones de edición no se agrupan, el documento registra automáticamente las operaciones individuales para que puedan deshacerse más tarde. Agrupar operaciones en bloques más grandes puede hacer que la edición sea más eficiente tanto para el usuario como para la aplicación, pero hay que tener cuidado de no agrupar demasiadas operaciones, ya que el usuario puede querer un control más detallado sobre el proceso de deshacer.

Cursores múltiples

Se pueden utilizar varios cursores para editar simultáneamente el mismo documento, aunque el usuario solo verá uno de ellos en un widget de « QTextEdit ». El « QTextDocument » garantiza que cada cursor escriba el texto correctamente y no interfiera con ninguno de los demás.

Inserción de elementos del documento

QTextCursor ofrece varias funciones que pueden utilizarse para modificar la estructura de un documento de texto enriquecido. En general, estas funciones permiten crear elementos del documento con la información de formato pertinente, y se insertan en el documento en la posición del cursor.

El primer grupo de funciones inserta elementos de nivel de bloque y actualiza la posición del cursor, pero no devuelve el elemento que se ha insertado:

  • insertBlock() inserta un nuevo bloque de texto (párrafo) en un documento en la posición del cursor y desplaza el cursor al inicio del nuevo bloque.
  • insertFragment() inserta un fragmento de texto existente en un documento en la posición del cursor.
  • insertImage() inserta una imagen en un documento en la posición del cursor.
  • insertText() inserta texto en el documento en la posición del cursor.

Puedes examinar el contenido del elemento insertado a través de la interfaz del cursor.

El segundo grupo de funciones inserta elementos que aportan estructura al documento y devuelve la estructura insertada:

  • insertFrame() inserta un marco en el documento después del bloque actual del cursor y desplaza el cursor al inicio del bloque vacío del nuevo marco.
  • insertList() inserta una lista en el documento en la posición del cursor y desplaza el cursor al inicio del primer elemento de la lista.
  • insertTable() inserta una tabla en el documento después del bloque actual del cursor y desplaza el cursor al inicio del bloque que sigue a la tabla.

Estos elementos contienen o agrupan otros elementos del documento.

Texto y fragmentos de texto

El texto se puede insertar en el bloque actual con el formato de carácter actual o con un formato personalizado que se especifique junto con el texto:

    cursor.insertText(tr("Character formats"),
                      headingFormat);

    cursor.insertBlock();

    cursor.insertText(tr("Text can be displayed in a variety of "
                                  "different character formats. "), plainFormat);
    cursor.insertText(tr("We can emphasize text by "));
    cursor.insertText(tr("making it italic"), emphasisFormat);

Una vez que se ha utilizado un formato de caracteres con un cursor, ese formato se convierte en el formato predeterminado para cualquier texto que se inserte con ese cursor hasta que se especifique otro formato de caracteres.

Si se utiliza un cursor para insertar texto sin especificar un formato de caracteres, al texto se le aplicará el formato de caracteres utilizado en esa posición del documento.

Bloques

Los bloques de texto se insertan en el documento con la función insertBlock().

    QTextBlockFormat backgroundFormat = blockFormat;
    backgroundFormat.setBackground(QColor("lightGray"));

    cursor.setBlockFormat(backgroundFormat);

El cursor se sitúa al principio del nuevo bloque.

Marcos

Los marcos se insertan en un documento mediante el cursor y se colocarán dentro del marco actual del cursor, después del bloque actual. El siguiente código muestra cómo se puede insertar un marco entre dos bloques de texto en el marco raíz de un documento. Comenzamos por localizar el marco actual del cursor:

    QTextFrame *mainFrame = cursor.currentFrame();
    cursor.insertText(...);

Insertamos algo de texto en este marco y, a continuación, configuramos un formato de marco para el marco secundario:

    QTextFrameFormat frameFormat;
    frameFormat.setMargin(32);
    frameFormat.setPadding(8);
    frameFormat.setBorder(4);

El formato de marco le dará al marco un margen externo de 32 píxeles, un relleno interno de 8 píxeles y un borde de 4 píxeles de ancho. Consulta la documentación de QTextFrameFormat para obtener más información sobre los formatos de marco.

El marco se inserta en el documento después del texto anterior:

    cursor.insertFrame(frameFormat);
    cursor.insertText(...);

Añadimos algo de texto al documento inmediatamente después de insertar el marco. Dado que el cursor de texto se encuentra dentro del marco cuando este se inserta en el documento, este texto también se insertará dentro del marco.

Por último, colocamos el cursor fuera del marco tomando la última posición disponible del cursor dentro del marco que habíamos registrado anteriormente:

    cursor = mainFrame->lastCursorPosition();
    cursor.insertText(...);

El texto que añadimos en último lugar se inserta después del marco secundario en el documento. Dado que cada marco se rellena con bloques de texto, esto garantiza que siempre se puedan insertar más elementos con el cursor.

Tablas

Las tablas se insertan en el documento mediante el cursor y se colocarán dentro del marco actual del cursor, después del bloque actual:

    QTextCursor cursor(editor->textCursor());
    QTextTable *table = cursor.insertTable(rows, columns, tableFormat);

Las tablas se pueden crear con un formato específico que defina las propiedades generales de la tabla, como su alineación, el color de fondo y el espaciado entre celdas utilizado. También permite establecer restricciones para cada columna, de modo que cada una de ellas pueda tener un ancho fijo o cambiar de tamaño según el espacio disponible.

    QTextTableFormat tableFormat;
    tableFormat.setBackground(QColor("#e0e0e0"));
    QList<QTextLength> constraints;
    constraints << QTextLength(QTextLength::PercentageLength, 16);
    constraints << QTextLength(QTextLength::PercentageLength, 28);
    constraints << QTextLength(QTextLength::PercentageLength, 28);
    constraints << QTextLength(QTextLength::PercentageLength, 28);
    tableFormat.setColumnWidthConstraints(constraints);
    QTextTable *table = cursor.insertTable(rows, columns, tableFormat);

Cada una de las columnas de la tabla creada anteriormente ocupará un determinado porcentaje del ancho disponible. Ten en cuenta que el formato de la tabla es opcional; si insertas una tabla sin formato, se utilizarán unos valores predeterminados razonables para las propiedades de la tabla.

Dado que las celdas pueden contener otros elementos del documento, también se les puede aplicar formato y estilo según sea necesario.

Se puede añadir texto a la tabla desplazándose con el cursor a cada celda e insertando el texto.

    cell = table->cellAt(0, 0);
    cellCursor = cell.firstCursorPosition();
    cellCursor.insertText(tr("Week"), charFormat);

Podemos crear un horario sencillo siguiendo este procedimiento:

    for (column = 1; column < columns; ++column) {
        cell = table->cellAt(0, column);
        cellCursor = cell.firstCursorPosition();
        cellCursor.insertText(tr("Team %1").arg(column), charFormat);
    }

    for (row = 1; row < rows; ++row) {
        cell = table->cellAt(row, 0);
        cellCursor = cell.firstCursorPosition();
        cellCursor.insertText(tr("%1").arg(row), charFormat);

        for (column = 1; column < columns; ++column) {
            if ((row-1) % 3 == column-1) {
                cell = table->cellAt(row, column);
                QTextCursor cellCursor = cell.firstCursorPosition();
                cellCursor.insertText(tr("On duty"), charFormat);
            }
        }
    }

Listas

Las listas de elementos de bloque se pueden crear automáticamente e insertar en el documento en la posición actual del cursor. Cada lista que se cree de esta manera requiere que se especifique un formato de lista:

    QTextListFormat listFormat;
    if (list) {
        listFormat = list->format();
        listFormat.setIndent(listFormat.indent() + 1);
    }

    listFormat.setStyle(QTextListFormat::ListDisc);
    cursor.insertList(listFormat);

El código anterior comprueba primero si el cursor se encuentra dentro de una lista existente y, en caso afirmativo, asigna al formato de la nueva lista un nivel de sangría adecuado. Esto permite crear listas anidadas con niveles de sangría crecientes. Una implementación más sofisticada utilizaría también diferentes tipos de símbolos para las viñetas de cada nivel de la lista.

Imágenes

Las imágenes en línea se añaden a los documentos mediante el cursor de la forma habitual. A diferencia de muchos otros elementos, todas las propiedades de la imagen vienen determinadas por el formato de la misma. Esto significa que hay que crear un objeto ` QTextImageFormat ` antes de poder insertar una imagen:

    QTextImageFormat imageFormat;
    imageFormat.setName(":/images/advert.png");
    cursor.insertImage(imageFormat);

El nombre de la imagen hace referencia a una entrada del archivo de recursos de la aplicación. El método utilizado para derivar este nombre se describe en «El sistema de recursos de Qt».

Ejemplos

El texto enriquecido se almacena en documentos de texto que pueden crearse importando HTML desde una fuente externa o generarse utilizando un ` QTextCursor`.

Manipulación de texto enriquecido

La forma más sencilla de utilizar un documento de texto enriquecido es a través de la clase ` QTextEdit `, que proporciona una vista editable del documento. El código siguiente importa HTML a un documento y muestra el documento mediante un widget de edición de texto.

QTextEdit *editor = new QTextEdit(parent);
editor->setHtml(aStringContainingHTMLtext);
editor->show();

Puedes recuperar el documento desde el editor de texto utilizando la función document(). A continuación, el documento se puede editar mediante programación utilizando la clase ` QTextCursor `. Esta clase se basa en el modelo de un cursor de pantalla, y las operaciones de edición siguen la misma semántica. El código siguiente cambia la primera línea del documento a negrita, dejando intactas todas las demás propiedades de fuente. El editor se actualizará automáticamente para reflejar los cambios realizados en los datos subyacentes del documento.

QTextDocument *document = edit->document();
QTextCursor cursor(document);

cursor.movePosition(QTextCursor::Start);
cursor.movePosition(QTextCursor::EndOfLine, QTextCursor::KeepAnchor);

QTextCharFormat format;
format.setFontWeight(QFont::Bold);

cursor.mergeCharFormat(format);

Obsérvese que el cursor se ha desplazado desde el inicio de la primera línea hasta el final, pero que ha conservado un punto de anclaje al principio de la línea. Esto ilustra las funciones de selección basadas en el cursor de la clase ` QTextCursor `.

Creación de un calendario

El texto enriquecido se puede generar muy rápidamente utilizando el enfoque basado en el cursor. El siguiente ejemplo muestra un calendario sencillo en un widget ` QTextEdit ` con los encabezados de los días de la semana en negrita:

    editor = new QTextEdit(this);

    QTextCursor cursor(editor->textCursor());
    cursor.movePosition(QTextCursor::Start);

    QTextCharFormat format(cursor.charFormat());
    format.setFontFamilies({"Courier"});

    QTextCharFormat boldFormat = format;
    boldFormat.setFontWeight(QFont::Bold);

    cursor.insertBlock();
    cursor.insertText(" ", boldFormat);

    QDate date = QDate::currentDate();
    int year = date.year(), month = date.month();

    for (int weekDay = 1; weekDay <= 7; ++weekDay) {
        cursor.insertText(QString("%1 ").arg(QLocale::system().dayName(weekDay), 3),
            boldFormat);
    }

    cursor.insertBlock();
    cursor.insertText(" ", format);

    for (int column = 1; column < QDate(year, month, 1).dayOfWeek(); ++column) {
        cursor.insertText("    ", format);
    }

    for (int day = 1; day <= date.daysInMonth(); ++day) {
        int weekDay = QDate(year, month, day).dayOfWeek();

        if (QDate(year, month, day) == date)
            cursor.insertText(QString("%1 ").arg(day, 3), boldFormat);
        else
            cursor.insertText(QString("%1 ").arg(day, 3), format);

        if (weekDay == 7) {
            cursor.insertBlock();
            cursor.insertText(" ", format);
        }
    }

El ejemplo anterior demuestra lo sencillo que resulta generar rápidamente nuevos documentos de texto enriquecido utilizando una cantidad mínima de código. Aunque hemos generado un calendario rudimentario de espaciado fijo para evitar citar demasiado código, Scribe ofrece funciones de diseño y formato mucho más sofisticadas.

© 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.