En esta página

QInputMethodEvent Class

La clase `QInputMethodEvent` proporciona parámetros para los eventos de los métodos de entrada. Más información...

Encabezado: #include <QInputMethodEvent>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Heredado de: QEvent

Tipos públicos

class Attribute
enum AttributeType { TextFormat, Cursor, Language, Ruby, Selection, MimeData }

Funciones públicas

QInputMethodEvent()
QInputMethodEvent(const QString &preeditText, const QList<QInputMethodEvent::Attribute> &attributes)
const QList<QInputMethodEvent::Attribute> &attributes() const
const QString &commitString() const
const QString &preeditString() const
int replacementLength() const
int replacementStart() const
void setCommitString(const QString &commitString, int replaceFrom = 0, int replaceLength = 0)

Funciones protegidas

QInputMethodEvent(QInputMethodEvent &&)
QInputMethodEvent &operator=(QInputMethodEvent &&)
QInputMethodEvent &operator=(const QInputMethodEvent &other)

Descripción detallada

Los eventos de método de entrada se envían a los widgets cuando se utiliza un método de entrada para introducir texto en un widget. Los métodos de entrada se utilizan ampliamente para introducir texto en idiomas con alfabetos no latinos.

Ten en cuenta que, al crear widgets de edición de texto personalizados, el atributo de ventana « Qt::WA_InputMethodEnabled » debe establecerse explícitamente (utilizando la función « QWidget::setAttribute()») para poder recibir eventos de métodos de entrada.

Estos eventos son de interés para los autores de widgets de introducción de texto mediante teclado que deseen poder gestionar correctamente idiomas con una introducción de caracteres compleja. La introducción de texto en dichos idiomas suele ser un proceso de tres pasos:

  1. Inicio de la composición

    Cuando el usuario pulsa la primera tecla del teclado, se crea un contexto de entrada. Este contexto de entrada contendrá una cadena formada por los caracteres tecleados.

  2. Redacción

    Con cada nueva tecla pulsada, el método de entrada intentará crear una cadena que coincida con el texto escrito hasta ese momento, denominada «cadena de preedición». Mientras el contexto de entrada esté activo, el usuario solo podrá mover el cursor dentro de la cadena perteneciente a dicho contexto de entrada.

  3. Finalización

    En algún momento, el usuario activará un componente de la interfaz de usuario (quizás mediante una tecla concreta) en el que podrá elegir entre varias cadenas que coincidan con el texto que haya escrito hasta ese momento. El usuario puede confirmar su elección o cancelar la entrada; en cualquiera de los dos casos, se cerrará el contexto de entrada.

QInputMethodEvent modela estas tres etapas y transfiere la información necesaria para representar correctamente el resultado intermedio. Un QInputMethodEvent tiene dos parámetros principales: ` preeditString()` y ` commitString()`. El parámetro preeditString() proporciona la cadena de preedición actualmente activa. El parámetro commitString() proporciona un texto que debe añadirse al texto del widget del editor (o sustituir partes del mismo). Suele ser el resultado de las operaciones de entrada y debe insertarse en el texto del widget directamente antes de la cadena de preedición.

Si la función ` commitString()` debe sustituir partes del texto del editor, ` replacementLength()` contendrá el número de caracteres que se van a sustituir. ` replacementStart()` contiene la posición relativa respecto al inicio de la cadena de preedición en la que se deben sustituir los caracteres.

Hay una serie de atributos que controlan el aspecto visual de la cadena de preedición (el aspecto visual del texto fuera de la cadena de preedición lo controla únicamente el widget). La enumeración AttributeType describe los diferentes atributos que se pueden establecer.

Una clase que implemente QWidget::inputMethodEvent() o QGraphicsItem::inputMethodEvent() debe, como mínimo, comprender y respetar los atributos TextFormat y Cursor.

Dado que los métodos de entrada deben poder consultar determinadas propiedades del widget o del elemento gráfico, las subclases también deben implementar QWidget::inputMethodQuery() y QGraphicsItem::inputMethodQuery(), respectivamente.

Al recibir un evento del método de entrada, el widget de texto debe realizar los siguientes pasos:

  1. Si el widget tiene texto seleccionado, dicho texto debe eliminarse.
  2. Eliminar el texto a partir de ` replacementStart()` con una longitud de ` replacementLength()` y sustituirlo por ` commitString()`. Si ` replacementLength()` es 0, ` replacementStart()` proporciona la posición de inserción para ` commitString()`.

    Al realizar la sustitución, se ignora el área de la cadena de preedición; por lo tanto, una sustitución que comience en -1 y tenga una longitud de 2 eliminará el último carácter antes de la cadena de preedición y el primer carácter después de ella, e insertará la cadena de confirmación directamente antes de la cadena de preedición.

    Si el widget implementa las funciones de deshacer/rehacer, esta operación se añade a la pila de deshacer.

  3. Si no hay ninguna cadena de preedición actual, inserta la cadena de confirmación ( preeditString()) en la posición actual del cursor; de lo contrario, sustituye la cadena de preedición ( preeditString ) anterior por la recibida de este evento.

    Si el widget implementa las funciones de deshacer/rehacer, la llamada a ` preeditString()` no debe influir en la pila de deshacer/rehacer de ninguna manera.

    El widget debe examinar la lista de atributos que se van a aplicar a la cadena de preedición. Debe interpretar, como mínimo, los atributos « TextFormat » y «Cursor», y representarlos tal y como se especifica.

Véase también QInputMethod.

Documentación sobre tipos de miembros

enum QInputMethodEvent::AttributeType

ConstanteValorDescripción
QInputMethodEvent::TextFormat0Un objeto ` QTextCharFormat ` para la parte de la cadena de preedición especificada por `start` y `length`. `value` contiene un objeto ` QVariant ` de tipo ` QTextFormat ` que especifica la representación de esta parte de la cadena de preedición. Debe haber como máximo un formato para cada parte de la cadena de preedición. Si se especifican varios formatos para un mismo carácter de la cadena, el comportamiento es indefinido. Una implementación conforme debe respetar, como mínimo, las propiedades backgroundColor, textColor y fontUnderline del formato.
QInputMethodEvent::Cursor1Si se establece, debe mostrarse un cursor dentro de la cadena de preedición en la posición start. La variable length determina si el cursor es visible o no. Si la longitud es 0, el cursor es invisible. Si el valor es un objeto ` QVariant ` de tipo ` QColor `, se utilizará este color para representar el cursor; de lo contrario, se utilizará el color del texto circundante. Solo debe haber como máximo un atributo Cursor por evento. Si se especifican varios, el comportamiento es indefinido.
QInputMethodEvent::Language2La variante contiene un objeto « QLocale » que especifica el idioma de una parte determinada de la cadena de preedición. Solo debe haber un idioma establecido como máximo para cada parte de la cadena de preedición. Si se especifican varios para cualquier carácter de la cadena, el comportamiento es indefinido.
QInputMethodEvent::Ruby3El texto en rubí para una parte de la cadena de preedición. Solo debe haber un texto en rubí establecido como máximo para cada parte de la cadena de preedición. Si se especifican varios para cualquier carácter de la cadena, el comportamiento es indefinido.
QInputMethodEvent::Selection4Si se establece, el cursor de edición debe desplazarse a la posición especificada en el contenido del texto del editor. A diferencia de ` Cursor`, este atributo no actúa sobre el texto de preedición, sino sobre el texto circundante. El cursor se desplazará una vez que se haya validado la cadena de validación, y la cadena de preedición se situará en la nueva posición de edición. La posición inicial especifica la nueva posición y la variable de longitud se puede utilizar para establecer una selección a partir de ese punto. El valor no se utiliza.
QInputMethodEvent::MimeData5Si se establece, la variante contiene un objeto ` QMimeData ` que representa el texto confirmado. La función ` commitString()` sigue proporcionando la representación en texto sin formato del texto confirmado.

Véase también Attribute.

Documentación de las funciones de miembro

QInputMethodEvent::QInputMethodEvent()

Crea un evento de tipo QEvent::InputMethod. Los métodos attributes(), preeditString(), commitString(), replacementStart() y replacementLength() se inicializan con los valores predeterminados.

Véase también setCommitString().

QInputMethodEvent::QInputMethodEvent(const QString &preeditText, const QList<QInputMethodEvent::Attribute> &attributes)

Crea un evento de tipo QEvent::InputMethod. El texto de preedición se establece en preeditText y los atributos en attributes.

Los valores de commitString(), replacementStart() y replacementLength() se pueden establecer mediante setCommitString().

Véanse también preeditString() y attributes().

[protected delete] QInputMethodEvent::QInputMethodEvent(QInputMethodEvent &&)

Crea una instancia de « QInputMethodEvent » mediante la construcción «move». Esta función se ha eliminado.

const QList<QInputMethodEvent::Attribute> &QInputMethodEvent::attributes() const

Devuelve la lista de atributos pasados al constructor de ` QInputMethodEvent `. Los atributos controlan el aspecto visual de la cadena de preedición (el aspecto visual del texto fuera de la cadena de preedición lo controla únicamente el widget).

Véase también preeditString() y Attribute.

const QString &QInputMethodEvent::commitString() const

Devuelve el texto que debe añadirse (o sustituir partes del) al texto del widget del editor. Suele ser el resultado de las operaciones de entrada y debe insertarse en el texto del widget justo antes de la cadena de preedición.

Véase también setCommitString(), preeditString(), replacementStart() y replacementLength().

const QString &QInputMethodEvent::preeditString() const

Devuelve el texto anterior a la edición, es decir, el texto tal y como estaba antes de que el usuario comenzara a editarlo.

Véase también commitString() y attributes().

int QInputMethodEvent::replacementLength() const

Devuelve el número de caracteres que se van a sustituir en la cadena de preedición.

Véase también replacementStart() y setCommitString().

int QInputMethodEvent::replacementStart() const

Devuelve la posición en la que se deben sustituir los caracteres, relativa respecto al inicio de la cadena de preedición.

Véanse también replacementLength() y setCommitString().

void QInputMethodEvent::setCommitString(const QString &commitString, int replaceFrom = 0, int replaceLength = 0)

Establece la cadena de confirmación en « commitString ».

La cadena de confirmación es el texto que debe añadirse (o sustituir partes de) al texto del widget del editor. Suele ser el resultado de las operaciones de entrada y debe insertarse en el texto del widget justo antes de la cadena de preedición.

Si la cadena de confirmación debe sustituir partes del texto del editor, replaceLength especifica el número de caracteres que se van a sustituir. replaceFrom especifica la posición en la que se van a sustituir los caracteres, relativa al inicio de la cadena de preedición.

Véanse también commitString(), replacementStart() y replacementLength().

[protected delete] QInputMethodEvent &QInputMethodEvent::operator=(QInputMethodEvent &&)

Asigna mediante «move» other a esta instancia de QInputMethodEvent. Esta función se elimina.

[noexcept protected default] QInputMethodEvent &QInputMethodEvent::operator=(const QInputMethodEvent &other)

Asigna por copia other a esta instancia de QInputMethodEvent.

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