QTextCursor Class

Documentation des fonctions membres

QTextCursor::QTextCursor()

Construit un curseur nul.

[explicit] QTextCursor::QTextCursor(QTextDocument *document)

Construit un curseur pointant vers le début de document.

[explicit] QTextCursor::QTextCursor(QTextFrame *frame)

Construit un curseur pointant vers le début de frame.

[explicit] QTextCursor::QTextCursor(const QTextBlock &block)

Construit un curseur pointant vers le début de block.

QTextCursor::QTextCursor(const QTextCursor &cursor)

Construit un nouveau curseur qui est une copie de cursor.

[noexcept] QTextCursor::~QTextCursor()

Détruit le site QTextCursor.

int QTextCursor::anchor() const

Renvoie la position d'ancrage ; c'est la même chose que position() sauf s'il y a une sélection, auquel cas position() marque une extrémité de la sélection et anchor() marque l'autre extrémité. Tout comme la position du curseur, la position de l'ancre se situe entre les caractères.

Voir également position(), setPosition(), movePosition(), selectionStart() et selectionEnd().

bool QTextCursor::atBlockEnd() const

Renvoie true si le curseur se trouve à la fin d'un bloc ; sinon, renvoie false.

Voir aussi atBlockStart() et atEnd().

bool QTextCursor::atBlockStart() const

Renvoie true si le curseur se trouve au début d'un bloc ; sinon, renvoie false.

Voir aussi atBlockEnd() et atStart().

bool QTextCursor::atEnd() const

Renvoie true si le curseur se trouve à la fin du document ; sinon, renvoie false.

Voir aussi atStart() et atBlockEnd().

bool QTextCursor::atStart() const

Renvoie true si le curseur se trouve au début du document ; sinon, renvoie false.

Voir aussi atBlockStart() et atEnd().

void QTextCursor::beginEditBlock()

Indique le début d'un bloc d'opérations d'édition sur le document qui doit apparaître comme une seule opération du point de vue de l'annulation/rétablissement.

Par exemple, l'appel à undo() entraînera l'annulation des deux insertions :

QTextCursor cursor(textDocument);
cursor.beginEditBlock();
cursor.insertText("Hello");
cursor.insertText("World");
cursor.endEditBlock();

textDocument->undo();

L'appel à undo() annulera les deux insertions, ce qui entraînera la suppression de "World" et de "Hello".

Il est possible d'imbriquer les appels à beginEditBlock et endEditBlock. La paire la plus élevée déterminera la portée de l'opération d'annulation/rétablissement.

Voir également endEditBlock().

QTextBlock QTextCursor::block() const

Renvoie le bloc qui contient le curseur.

QTextCharFormat QTextCursor::blockCharFormat() const

Renvoie le format de caractère du bloc dans lequel se trouve le curseur.

Le format de caractères de bloc est le format utilisé pour insérer du texte au début d'un bloc vide.

Voir aussi setBlockCharFormat().

QTextBlockFormat QTextCursor::blockFormat() const

Renvoie le format du bloc dans lequel se trouve le curseur.

Voir aussi setBlockFormat() et charFormat().

int QTextCursor::blockNumber() const

Renvoie le numéro du bloc dans lequel se trouve le curseur, ou 0 si le curseur n'est pas valide.

Notez que cette fonction n'a de sens que dans les documents ne contenant pas d'objets complexes tels que des tableaux ou des cadres.

QTextCharFormat QTextCursor::charFormat() const

Renvoie le format du caractère immédiatement avant le curseur position(). Si le curseur est positionné au début d'un bloc de texte qui n'est pas vide, le format du caractère immédiatement après le curseur est renvoyé.

Voir aussi setCharFormat(), insertText() et blockFormat().

void QTextCursor::clearSelection()

Efface la sélection actuelle en plaçant l'ancre à la position du curseur.

Notez que cela ne supprime pas le texte de la sélection.

Voir aussi removeSelectedText() et hasSelection().

int QTextCursor::columnNumber() const

Renvoie la position du curseur dans la ligne qu'il contient.

Notez qu'il s'agit du numéro de colonne par rapport à une ligne enveloppée, et non par rapport au bloc (c'est-à-dire le paragraphe).

Vous devriez probablement appeler positionInBlock() à la place.

Voir aussi positionInBlock().

QTextList *QTextCursor::createList(const QTextListFormat &format)

Crée et renvoie une nouvelle liste avec l'adresse format, et fait du paragraphe actuel le curseur du premier élément de la liste.

Voir aussi insertList() et currentList().

QTextList *QTextCursor::createList(QTextListFormat::Style style)

Crée et renvoie une nouvelle liste avec l'adresse style, en faisant du paragraphe courant du curseur le premier élément de la liste.

Le style à utiliser est défini par l'enum QTextListFormat::Style.

Voir aussi insertList() et currentList().

QTextFrame *QTextCursor::currentFrame() const

Renvoie un pointeur sur le cadre actuel. Renvoie nullptr si le curseur n'est pas valide.

Voir aussi insertFrame().

QTextList *QTextCursor::currentList() const

Renvoie la liste actuelle si le curseur position() se trouve à l'intérieur d'un bloc faisant partie d'une liste ; sinon, renvoie nullptr.

Voir également insertList() et createList().

QTextTable *QTextCursor::currentTable() const

Renvoie un pointeur sur la table actuelle si le curseur position() se trouve à l'intérieur d'un bloc faisant partie d'une table ; sinon, renvoie nullptr.

Voir aussi insertTable().

void QTextCursor::deleteChar()

S'il n'y a pas de texte sélectionné, supprime le caractère à la position actuelle du curseur ; sinon, supprime le texte sélectionné.

Voir aussi deletePreviousChar(), hasSelection() et clearSelection().

void QTextCursor::deletePreviousChar()

S'il n'y a pas de texte sélectionné, supprime le caractère précédant la position actuelle du curseur ; sinon, supprime le texte sélectionné.

Voir aussi deleteChar(), hasSelection() et clearSelection().

QTextDocument *QTextCursor::document() const

Renvoie le document auquel ce curseur est associé.

void QTextCursor::endEditBlock()

Indique la fin d'un bloc d'opérations d'édition sur le document qui devrait apparaître comme une opération unique du point de vue de l'annulation/rétablissement.

Voir également beginEditBlock().

bool QTextCursor::hasComplexSelection() const

Renvoie true si le curseur contient une sélection qui n'est pas simplement une plage allant de selectionStart() à selectionEnd() ; sinon, renvoie false.

Les sélections complexes sont celles qui couvrent au moins deux cellules d'un tableau ; leur étendue est spécifiée par selectedTableCells().

bool QTextCursor::hasSelection() const

Renvoie true si le curseur contient une sélection, sinon renvoie false.

void QTextCursor::insertBlock()

Insère un nouveau bloc vide au curseur position() avec les blocs actuels blockFormat() et charFormat().

Voir aussi setBlockFormat().

void QTextCursor::insertBlock(const QTextBlockFormat &format)

Insère un nouveau bloc vide au curseur position() avec le format de bloc format et le bloc actuel charFormat() avec le format de bloc char.

Voir aussi setBlockFormat().

void QTextCursor::insertBlock(const QTextBlockFormat &format, const QTextCharFormat &charFormat)

Insère un nouveau bloc vide au curseur position() avec le format de bloc format et charFormat comme format de bloc char.

Voir aussi setBlockFormat().

void QTextCursor::insertFragment(const QTextDocumentFragment &fragment)

Insère le texte fragment à l'endroit où se trouve position().

QTextFrame *QTextCursor::insertFrame(const QTextFrameFormat &format)

Insère un cadre avec l'adresse format au niveau du curseur actuel position(), déplace le curseur position() à l'intérieur du cadre et renvoie le cadre.

Si le curseur contient une sélection, toute la sélection est déplacée à l'intérieur du cadre.

Voir aussi hasSelection().

void QTextCursor::insertHtml(const QString &html)

Insère le texte html à l'endroit où se trouve position(). Le texte est interprété comme du HTML.

void QTextCursor::insertImage(const QTextImageFormat &format)

Insère l'image définie par format à l'emplacement actuel de position().

void QTextCursor::insertImage(const QString &name)

Méthode de commodité pour insérer l'image avec l'adresse name à l'adresse position().

QImage img;
textDocument->addResource(QTextDocument::ImageResource, QUrl("myimage"), img);
cursor.insertImage("myimage");

void QTextCursor::insertImage(const QImage &image, const QString &name = QString())

Fonction de commodité permettant d'insérer l'adresse image donnée avec une adresse name facultative à l'adresse position() actuelle.

void QTextCursor::insertImage(const QTextImageFormat &format, QTextFrameFormat::Position alignment)

Insère l'image définie par l'adresse format à la position actuelle du curseur avec l'adresse alignment.

Voir aussi position().

QTextList *QTextCursor::insertList(const QTextListFormat &format)

Insère un nouveau bloc à la position actuelle et en fait le premier élément d'une liste nouvellement créée avec l'adresse format. Renvoie la liste créée.

Voir aussi currentList(), createList() et insertBlock().

QTextList *QTextCursor::insertList(QTextListFormat::Style style)

Insère un nouveau bloc à la position actuelle et en fait le premier élément d'une liste nouvellement créée avec l'adresse style. Renvoie la liste créée.

Voir aussi currentList(), createList() et insertBlock().

[since 6.4] void QTextCursor::insertMarkdown(const QString &markdown, QTextDocument::MarkdownFeatures features = QTextDocument::MarkdownDialectGitHub)

Insère le texte markdown à l'emplacement actuel position(), avec le format Markdown spécifié features. La valeur par défaut est le dialecte GitHub.

Cette fonction a été introduite dans Qt 6.4.

QTextTable *QTextCursor::insertTable(int rows, int columns, const QTextTableFormat &format)

Crée un nouveau tableau avec le nombre donné de rows et columns dans le format spécifié, l'insère au curseur actuel position() dans le document et renvoie l'objet tableau. Le curseur est déplacé au début de la première cellule.

Le tableau doit comporter au moins une ligne et une colonne.

Voir aussi currentTable().

QTextTable *QTextCursor::insertTable(int rows, int columns)

Crée un nouveau tableau avec le nombre donné de rows et columns, l'insère au curseur actuel position() dans le document, et renvoie l'objet tableau. Le curseur est déplacé au début de la première cellule.

Le tableau doit comporter au moins une ligne et une colonne.

Voir aussi currentTable().

void QTextCursor::insertText(const QString &text)

Insère text à la position actuelle, en utilisant le format de caractères actuel.

S'il existe une sélection, celle-ci est supprimée et remplacée par text, par exemple :

cursor.clearSelection();
cursor.movePosition(QTextCursor::NextWord, QTextCursor::KeepAnchor);
cursor.insertText("Hello World");

Ceci efface toute sélection existante, sélectionne le mot au niveau du curseur (c'est-à-dire à partir de position()) et remplace la sélection par la phrase "Hello World".

Tous les caractères ASCII de saut de ligne (\n) dans le texte inséré sont transformés en séparateurs de blocs unicode, correspondant aux appels de insertBlock().

Voir également charFormat() et hasSelection().

void QTextCursor::insertText(const QString &text, const QTextCharFormat &format)

Insère text à la position actuelle avec format.

bool QTextCursor::isCopyOf(const QTextCursor &other) const

Renvoie true si ce curseur et other sont des copies l'un de l'autre, c'est-à-dire que l'un d'eux a été créé en tant que copie de l'autre et qu'aucun n'a bougé depuis. Cette règle est beaucoup plus stricte que l'égalité.

Voir aussi operator=() et operator==().

bool QTextCursor::isNull() const

Renvoie true si le curseur est nul, sinon renvoie false. Un curseur nul est créé par le constructeur par défaut.

void QTextCursor::joinPreviousEditBlock()

Comme beginEditBlock(), il indique le début d'un bloc d'opérations d'édition qui devrait apparaître comme une opération unique d'annulation/rétablissement. Toutefois, à la différence de beginEditBlock(), il ne démarre pas un nouveau bloc mais inverse l'appel précédent à endEditBlock() et intègre donc les opérations suivantes dans le bloc d'édition créé précédemment.

Par exemple :

QTextCursor cursor(textDocument);
cursor.beginEditBlock();
cursor.insertText("Hello");
cursor.insertText("World");
cursor.endEditBlock();

// ...

cursor.joinPreviousEditBlock();
cursor.insertText("Hey");
cursor.endEditBlock();

textDocument->undo();

L'appel à undo() annulera les trois insertions.

Voir également beginEditBlock() et endEditBlock().

bool QTextCursor::keepPositionOnInsert() const

Indique si le curseur doit conserver sa position actuelle lorsque du texte est inséré à la position du curseur.

La valeur par défaut est false ;

Voir aussi setKeepPositionOnInsert().

void QTextCursor::mergeBlockCharFormat(const QTextCharFormat &modifier)

Modifie le format des caractères de bloc du bloc actuel (ou de tous les blocs contenus dans la sélection) avec le format de bloc spécifié par modifier.

Voir également setBlockCharFormat().

void QTextCursor::mergeBlockFormat(const QTextBlockFormat &modifier)

Modifie le format de bloc du bloc actuel (ou de tous les blocs contenus dans la sélection) avec le format de bloc spécifié par modifier.

Voir également setBlockFormat() et blockFormat().

void QTextCursor::mergeCharFormat(const QTextCharFormat &modifier)

Fusionne le format de caractères actuel du curseur avec les propriétés décrites par le format modifier. Si le curseur comporte une sélection, cette fonction applique toutes les propriétés définies dans modifier à tous les formats de caractères qui font partie de la sélection.

Voir également hasSelection() et setCharFormat().

bool QTextCursor::movePosition(QTextCursor::MoveOperation operation, QTextCursor::MoveMode mode = MoveAnchor, int n = 1)

Déplace le curseur en exécutant operation n fois, en utilisant mode, et renvoie true si toutes les opérations ont été effectuées avec succès ; sinon, renvoie false.

Par exemple, si cette fonction est utilisée de manière répétée pour rechercher la fin du mot suivant, elle finira par échouer lorsque la fin du document sera atteinte.

Par défaut, l'opération de déplacement est effectuée une seule fois (n = 1).

Si mode est KeepAnchor, le curseur sélectionne le texte sur lequel il se déplace. Il s'agit du même effet que celui obtenu par l'utilisateur lorsqu'il maintient la touche Shift enfoncée et qu'il déplace le curseur à l'aide des touches du curseur.

Voir aussi setVisualNavigation().

int QTextCursor::position() const

Renvoie la position absolue du curseur dans le document. Le curseur est positionné entre les caractères.

Voir également setPosition(), movePosition(), anchor() et positionInBlock().

int QTextCursor::positionInBlock() const

Renvoie la position relative du curseur dans le bloc. Le curseur est positionné entre les caractères.

Cela équivaut à position() - block().position().

Voir également position().

void QTextCursor::removeSelectedText()

S'il y a une sélection, son contenu est supprimé ; sinon, il ne fait rien.

Voir également hasSelection().

void QTextCursor::select(QTextCursor::SelectionType selection)

Sélectionne le texte dans le document en fonction de l'adresse selection.

void QTextCursor::selectedTableCells(int *firstRow, int *numRows, int *firstColumn, int *numColumns) const

Si la sélection s'étend sur des cellules de tableau, firstRow est renseigné avec le numéro de la première ligne de la sélection, firstColumn avec le numéro de la première colonne de la sélection, et numRows et numColumns avec le nombre de lignes et de colonnes de la sélection. Si la sélection ne recouvre aucune cellule de tableau, les résultats sont inoffensifs mais indéfinis.

QString QTextCursor::selectedText() const

Renvoie le texte de la sélection actuelle (qui peut être vide). Cette fonction ne renvoie que le texte, sans aucune information sur le formatage du texte enrichi. Si vous souhaitez obtenir un fragment de document (c'est-à-dire du texte enrichi formaté), utilisez plutôt selection().

QTextDocumentFragment QTextCursor::selection() const

Renvoie la sélection actuelle (qui peut être vide) avec toutes ses informations de formatage. Si vous ne voulez que le texte sélectionné (c'est-à-dire du texte brut), utilisez plutôt selectedText().

Voir également QTextDocumentFragment::toPlainText().

int QTextCursor::selectionEnd() const

Renvoie la fin de la sélection ou position() si le curseur n'a pas de sélection.

Voir aussi selectionStart(), position() et anchor().

int QTextCursor::selectionStart() const

Renvoie le début de la sélection ou position() si le curseur n'a pas de sélection.

Voir aussi selectionEnd(), position() et anchor().

void QTextCursor::setBlockCharFormat(const QTextCharFormat &format)

Définit le format block char du bloc actuel (ou de tous les blocs contenus dans la sélection) à format.

Voir aussi blockCharFormat().

void QTextCursor::setBlockFormat(const QTextBlockFormat &format)

Définit le format de bloc du bloc actuel (ou de tous les blocs contenus dans la sélection) à format.

Voir également blockFormat() et mergeBlockFormat().

void QTextCursor::setCharFormat(const QTextCharFormat &format)

Définit le format de caractère actuel du curseur au format donné format. Si le curseur a une sélection, le format format est appliqué à la sélection en cours.

Voir aussi charFormat(), hasSelection() et mergeCharFormat().

void QTextCursor::setKeepPositionOnInsert(bool b)

Définit si le curseur doit conserver sa position actuelle lorsque du texte est inséré à la position actuelle du curseur.

Si b est vrai, le curseur conserve sa position actuelle lorsque le texte est inséré à la position du curseur. Si b est faux, le curseur se déplace avec le texte inséré.

La valeur par défaut est false.

Notez qu'un curseur se déplace toujours lorsque du texte est inséré avant la position actuelle du curseur, et qu'il conserve toujours sa position lorsque du texte est inséré après la position actuelle du curseur.

Voir également keepPositionOnInsert().

void QTextCursor::setPosition(int pos, QTextCursor::MoveMode m = MoveAnchor)

Déplace le curseur à la position absolue dans le document spécifié par pos en utilisant un MoveMode spécifié par m. Le curseur est positionné entre les caractères.

Voir également position(), movePosition() et anchor().

void QTextCursor::setVerticalMovementX(int x)

Définit la position x visuelle pour les mouvements verticaux du curseur à x.

La position x du mouvement vertical est effacée automatiquement lorsque le curseur se déplace horizontalement et reste inchangée lorsque le curseur se déplace verticalement. Ce mécanisme permet au curseur de se déplacer vers le haut et vers le bas sur une ligne visuellement droite avec des polices proportionnelles, et de "sauter" doucement sur de courtes lignes.

La valeur -1 indique qu'il n'y a pas de position x prédéfinie. Elle sera alors définie automatiquement la prochaine fois que le curseur se déplacera vers le haut ou vers le bas.

Voir aussi verticalMovementX().

void QTextCursor::setVisualNavigation(bool b)

Définit la navigation visuelle à b.

La navigation visuelle consiste à sauter les paragraphes de texte cachés. La valeur par défaut est false.

Voir aussi visualNavigation() et movePosition().

[noexcept] void QTextCursor::swap(QTextCursor &other)

Remplace cette instance de curseur de texte par other. Cette opération est très rapide et n'échoue jamais.

int QTextCursor::verticalMovementX() const

Renvoie la position visuelle x pour les mouvements verticaux du curseur.

La valeur -1 indique qu'il n'y a pas de position x prédéfinie. Elle sera définie automatiquement la prochaine fois que le curseur se déplacera vers le haut ou vers le bas.

Voir aussi setVerticalMovementX().

bool QTextCursor::visualNavigation() const

Renvoie true si le curseur effectue une navigation visuelle ; sinon, renvoie false.

La navigation visuelle consiste à sauter les paragraphes de texte cachés. La valeur par défaut est false.

Voir aussi setVisualNavigation() et movePosition().

bool QTextCursor::operator!=(const QTextCursor &other) const

Renvoie true si le curseur other se trouve à une position différente de ce curseur dans le document ; sinon, renvoie false.

bool QTextCursor::operator<(const QTextCursor &other) const

Renvoie true si le curseur other est positionné plus loin dans le document que ce curseur ; sinon, renvoie false.

bool QTextCursor::operator<=(const QTextCursor &other) const

Renvoie true si le curseur other est positionné plus tard ou à la même position dans le document que ce curseur ; sinon renvoie false.

QTextCursor &QTextCursor::operator=(const QTextCursor &cursor)

Fait une copie de cursor et l'affecte à QTextCursor. Notez que QTextCursor est une classe implicitement partagée.

bool QTextCursor::operator==(const QTextCursor &other) const

Renvoie true si le curseur other se trouve à la même position que ce curseur dans le document ; sinon, renvoie false.

bool QTextCursor::operator>(const QTextCursor &other) const

Renvoie true si le curseur other est positionné plus tôt dans le document que ce curseur ; sinon, renvoie false.

bool QTextCursor::operator>=(const QTextCursor &other) const

Renvoie true si le curseur other est positionné plus tôt ou à la même position dans le document que ce curseur ; sinon, renvoie false.