QTextCursor 인터페이스

문서는 ` QTextCursor ` 클래스가 제공하는 인터페이스를 통해 편집할 수 있으며, 커서는 생성자를 사용하여 생성하거나 편집기 위젯에서 가져올 수 있습니다. 이 커서는 사용자가 편집기에서 직접 수행할 수 있는 작업과 정확히 일치하는 편집 작업을 수행하는 데 사용됩니다. 결과적으로 문서 구조에 대한 정보도 커서를 통해 이용할 수 있으며, 이를 통해 구조를 수정할 수 있습니다. 편집에 커서 중심 인터페이스를 사용하면 편집 작업을 쉽게 시각화할 수 있으므로, 개발자가 사용자 정의 편집기를 작성하는 과정이 더 간단해집니다.

QTextCursor 클래스는 또한 문서 내에서 선택한 텍스트에 대한 정보를 유지하는데, 이는 편집기에서 사용자가 텍스트를 선택할 때 수행하는 동작과 개념적으로 유사한 모델을 따릅니다.

리치 텍스트 문서에는 여러 개의 커서가 연결될 수 있으며, 각 커서는 문서 내 위치와 해당 커서가 포함하고 있는 선택 영역에 대한 정보를 담고 있습니다. 이러한 커서 기반 패러다임은 텍스트 잘라내기 및 붙여넣기와 같은 일반적인 작업을 프로그래밍 방식으로 간단하게 구현할 수 있게 해줄 뿐만 아니라, 문서에 대해 더 복잡한 편집 작업을 수행할 수도 있게 해줍니다.

이 장에서는 텍스트 및 문서 요소의 기본적인 삽입부터 문서 구조의 더 복잡한 조작에 이르기까지, 커서를 사용하여 수행해야 할 대부분의 일반적인 편집 작업을 설명합니다.

커서 기반 편집

가장 기본적인 수준에서 텍스트 문서는 문서 내 텍스트의 블록 구조를 나타내기 위해 어떤 방식으로든 마크업된 일련의 문자로 구성됩니다. QTextCursor 는 QTextDocument 의 내용을 문자 단위로 조작할 수 있는 커서 기반 인터페이스를 제공합니다. 요소(블록, 프레임, 표 등)도 문자 스트림에 인코딩되어 있으므로, 커서를 통해 문서 구조 자체를 변경할 수 있습니다.

커서는 상위 문서 내의 위치를 추적하며, 둘러싸고 있는 텍스트 블록, 프레임, 표 또는 목록과 같은 주변 구조에 대한 정보를 보고할 수 있습니다. 둘러싸고 있는 구조의 형식도 커서를 통해 직접 얻을 수 있습니다.

커서 사용

커서의 주요 용도는 블록 내의 텍스트를 삽입하거나 수정하는 것입니다. 텍스트 편집기의 커서를 사용하여 이를 수행할 수 있습니다:

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

또는 문서에서 직접 커서를 가져올 수도 있습니다:

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

커서는 문서의 시작 부분에 위치하므로, 문서의 첫 번째(비어 있는) 블록에 텍스트를 입력할 수 있습니다.

커서 작업 그룹화

일련의 편집 작업을 묶어두면, 이를 한 번에 다시 실행하거나 한 번에 취소할 수 있습니다. 이는 ` beginEditBlock() ` 및 ` endEditBlock() ` 함수를 다음과 같이 사용하여 구현할 수 있습니다. 다음 예제에서는 커서가 위치한 단어를 선택하는 방법을 보여줍니다:

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

편집 작업이 그룹화되지 않은 경우, 문서는 나중에 되돌릴 수 있도록 개별 작업을 자동으로 기록합니다. 작업을 더 큰 단위로 그룹화하면 사용자와 애플리케이션 모두에게 편집 효율을 높일 수 있지만, 사용자가 되돌리기 과정을 세밀하게 제어하고 싶어 할 수 있으므로 너무 많은 작업을 한꺼번에 그룹화하지 않도록 주의해야 합니다.

다중 커서

다중 커서를 사용하면 동일한 문서를 동시에 편집할 수 있지만, ` QTextEdit ` 위젯에서는 사용자에게 하나의 커서만 표시됩니다. ` QTextDocument `는 각 커서가 텍스트를 올바르게 기록하고 다른 커서와 간섭하지 않도록 보장합니다.

문서 요소 삽입

QTextCursor 리치 텍스트 문서의 구조를 변경하는 데 사용할 수 있는 여러 함수를 제공합니다. 일반적으로 이러한 함수를 사용하면 관련 서식 정보와 함께 문서 요소를 생성할 수 있으며, 이 요소들은 커서 위치에 문서에 삽입됩니다.

첫 번째 함수 그룹은 블록 수준 요소를 삽입하고 커서 위치를 업데이트하지만, 삽입된 요소를 반환하지는 않습니다.

• insertBlock()는 커서 위치에 새로운 텍스트 블록(단락)을 문서에 삽입하고, 커서를 새 블록의 시작 부분으로 이동시킵니다.
• insertFragment()는 기존 텍스트 조각을 문서의 커서 위치에 삽입합니다.
• insertImage()는 커서 위치에 이미지를 문서에 삽입합니다.
• insertText()는 커서 위치에 텍스트를 삽입합니다.

삽입된 요소의 내용은 커서 인터페이스를 통해 확인할 수 있습니다.

두 번째 함수 그룹은 문서에 구조를 제공하는 요소를 삽입하고, 삽입된 구조를 반환합니다:

• insertFrame()는 커서의 현재 블록 뒤에 프레임 하나를 문서에 삽입하고, 커서를 새 프레임 내 빈 블록의 시작 부분으로 이동시킵니다.
• insertList()는 커서 위치에 목록을 문서에 삽입하고, 커서를 목록의 첫 번째 항목 시작 부분으로 이동시킵니다.
• insertTable()는 커서의 현재 블록 뒤에 문서에 표를 삽입하고, 커서를 표 다음 블록의 시작 부분으로 이동시킵니다.

이러한 요소들은 문서 내의 다른 요소들을 포함하거나 그룹화합니다.

텍스트 및 텍스트 조각

텍스트는 현재 문자 서식으로, 또는 텍스트와 함께 지정된 사용자 정의 서식으로 현재 블록에 삽입될 수 있습니다:

    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);

커서에 특정 문자 서식이 한 번 적용되면, 다른 문자 서식이 지정될 때까지 해당 커서로 삽입되는 모든 텍스트에 대해 그 서식이 기본 서식으로 적용됩니다.

문자 서식을 지정하지 않고 커서를 사용하여 텍스트를 삽입하면, 해당 텍스트에는 문서 내 해당 위치에서 사용 중인 문자 서식이 적용됩니다.

블록

텍스트 블록은 ` insertBlock()` 함수를 사용하여 문서에 삽입됩니다.

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

    cursor.setBlockFormat(backgroundFormat);

커서는 새 블록의 시작 부분에 위치합니다.

프레임

프레임은 커서를 사용하여 문서에 삽입되며, 현재 블록 뒤의 커서가 위치한 프레임 내에 배치됩니다. 다음 코드는 문서의 루트 프레임 내 두 텍스트 블록 사이에 프레임을 삽입하는 방법을 보여줍니다. 먼저 커서가 위치한 현재 프레임을 찾습니다:

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

이 프레임에 텍스트를 삽입한 다음, 자식 프레임에 대한 프레임 형식을 설정합니다:

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

이 프레임 형식을 적용하면 프레임의 외부 여백은 32픽셀, 내부 여백은 8픽셀, 테두리 너비는 4픽셀이 됩니다. 프레임 형식에 대한 자세한 내용은 QTextFrameFormat 문서를 참조하십시오.

프레임은 앞선 텍스트 뒤에 문서에 삽입됩니다:

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

프레임을 삽입한 직후 문서에 텍스트를 추가합니다. 프레임이 문서에 삽입될 때 텍스트 커서가 프레임 내부에 위치해 있으므로, 이 텍스트도 프레임 내부에 삽입됩니다.

마지막으로, 앞서 기록해 둔 프레임 내부의 마지막 사용 가능한 커서 위치를 참조하여 커서를 프레임 외부로 이동시킵니다:

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

마지막으로 추가한 텍스트는 문서 내의 자식 프레임 뒤에 삽입됩니다. 각 프레임은 텍스트 블록으로 채워져 있으므로, 이를 통해 커서를 사용하여 항상 더 많은 요소를 삽입할 수 있습니다.

표

표는 커서를 사용하여 문서에 삽입되며, 현재 블록 뒤의 커서가 위치한 프레임 내에 배치됩니다:

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

표는 정렬, 배경색, 셀 간격 등 표의 전반적인 속성을 정의하는 특정 형식으로 생성할 수 있습니다. 또한 각 열에 대한 제약 조건을 지정하여 각 열의 너비를 고정하거나 사용 가능한 공간에 따라 크기를 조정할 수 있습니다.

    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);

위에서 생성한 표의 각 열은 사용 가능한 너비의 일정 비율을 차지합니다. 표 서식은 선택 사항입니다. 서식 없이 표를 삽입하면 표 속성에 대해 합리적인 기본값이 적용됩니다.

셀에는 다른 문서 요소를 포함할 수 있으므로, 필요에 따라 셀에도 서식을 지정하고 스타일을 적용할 수 있습니다.

커서를 사용하여 각 셀로 이동한 후 텍스트를 삽입하면 테이블에 텍스트를 추가할 수 있습니다.

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

다음과 같은 방법으로 간단한 시간표를 만들 수 있습니다:

    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);
            }
        }
    }

목록

블록 요소로 구성된 목록은 자동으로 생성되어 현재 커서 위치에 문서에 삽입될 수 있습니다. 이러한 방식으로 생성되는 각 목록에는 목록 형식이 지정되어야 합니다:

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

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

위의 코드는 먼저 커서가 기존 목록 내에 있는지 확인하고, 만약 그렇다면 새 목록의 목록 형식에 적절한 들여쓰기 수준을 적용합니다. 이를 통해 들여쓰기 수준이 점차 깊어지는 중첩 목록을 생성할 수 있습니다. 보다 정교한 구현 방식에서는 목록의 각 수준에 따라 다른 종류의 기호를 글머리 기호로 사용할 수도 있습니다.

이미지

인라인 이미지는 일반적인 방식대로 커서를 통해 문서에 추가됩니다. 다른 많은 요소와 달리, 이미지의 모든 속성은 이미지 형식을 통해 지정됩니다. 즉, 이미지를 삽입하기 전에 ` QTextImageFormat ` 객체를 생성해야 합니다:

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

이미지 이름은 애플리케이션의 리소스 파일에 있는 항목을 가리킵니다. 이 이름을 도출하는 방법은 『Qt 리소스 시스템』에 설명되어 있습니다.

예제

서식 있는 텍스트는 텍스트 문서에 저장되며, 이 문서는 외부 소스에서 HTML을 가져와 생성하거나 ` QTextCursor`를 사용하여 생성할 수 있습니다.

리치 텍스트 조작

리치 텍스트 문서를 사용하는 가장 쉬운 방법은 문서에 대한 편집 가능한 뷰를 제공하는 ` QTextEdit ` 클래스를 이용하는 것입니다. 아래 코드는 HTML을 문서로 가져온 다음, 텍스트 편집 위젯을 사용하여 문서를 표시합니다.

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

document() 함수를 사용하여 텍스트 편집기에서 문서를 가져올 수 있습니다. 그런 다음 QTextCursor 클래스를 사용하여 프로그래밍 방식으로 문서를 편집할 수 있습니다. 이 클래스는 화면 커서를 모델로 하며, 편집 작업도 동일한 의미 체계를 따릅니다. 다음 코드는 문서의 첫 번째 줄을 굵은 글꼴로 변경하고, 다른 모든 글꼴 속성은 그대로 유지합니다. 편집기는 기본 문서 데이터에 가해진 변경 사항을 반영하도록 자동으로 업데이트됩니다.

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);

커서가 첫 번째 줄의 시작 부분에서 끝 부분으로 이동했지만, 줄의 시작 부분에는 앵커가 유지되었다는 점에 유의하십시오. 이는 ` QTextCursor ` 클래스의 커서 기반 선택 기능을 보여주는 예시입니다.

달력 생성

커서 기반 접근 방식을 사용하면 리치 텍스트를 매우 빠르게 생성할 수 있습니다. 다음 예제는 요일 제목이 굵은 글꼴로 표시된 간단한 달력을 QTextEdit 위젯에 표시한 것입니다:

    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);
        }
    }

위의 예제는 최소한의 코드로 새로운 리치 텍스트 문서를 빠르게 생성하는 것이 얼마나 간단한지 보여줍니다. 코드 양을 줄이기 위해 다소 투박한 고정 간격 달력을 생성했지만, Scribe는 훨씬 더 정교한 레이아웃 및 서식 지정 기능을 제공합니다.