간단한 텍스트 뷰어 예제

이 예에서는 Qt Assistant 을 사용자 지정 애플리케이션의 사용자 지정 도움말 보기로 사용하는 방법을 보여 줍니다. 이 작업은 두 단계로 이루어집니다. 먼저 문서를 만들고 Qt Assistant 을 사용자 지정한 다음, Qt Assistant 을 실행하고 제어하는 기능을 애플리케이션에 추가합니다.

간단한 텍스트 뷰어 애플리케이션을 통해 사용자는 기존 파일을 선택하고 볼 수 있습니다. 이 애플리케이션은 메인 창의 메뉴 표시줄에 있는 도움말 메뉴 또는 애플리케이션의 파일 찾기 대화 상자에서 도움말 버튼을 클릭하여 사용할 수 있는 자체 사용자 지정 문서를 제공합니다.

이 예제는 네 가지 클래스로 구성되어 있습니다:

• Assistant Qt Assistant 을 실행하는 기능을 제공합니다.
• MainWindow 는 기본 애플리케이션 창입니다.
• FindFileDialog 사용자가 와일드카드 일치를 사용하여 파일을 검색할 수 있습니다.
• TextEdit HTML 문서에서 참조된 이미지가 제대로 표시되는지 확인하는 서식 있는 텍스트 브라우저를 제공합니다.

문서 만들기 및 사용자 지정하기 Qt Assistant

HTML 페이지의 형태로 실제 문서를 만드는 방법은 이 예제의 범위에 속하지 않습니다. 일반적으로 HTML 페이지는 직접 작성하거나 qdoc 또는 Doxygen과 같은 문서 작성 도구를 사용하여 생성할 수 있습니다. 이 예제에서는 HTML 파일이 이미 생성되어 있다고 가정합니다. 따라서 남은 작업은 Qt Assistant 에 도움말 정보를 구성하고 표시하는 방법을 알려주는 것뿐입니다.

다음 대상에 대한 문서 구성 Qt Assistant

일반 HTML 파일에는 특정 주제에 대한 텍스트나 문서만 포함되어 있을 뿐, 여러 HTML 문서가 서로 어떻게 관련되어 있는지 또는 어떤 순서로 읽어야 하는지에 대한 정보는 포함되지 않는 것이 일반적입니다. 특정 정보를 찾기 위해 많은 문서를 훑어보지 않고도 특정 도움말 콘텐츠에 빠르게 액세스할 수 있는 색인과 함께 목차가 누락되어 있습니다.

문서를 정리하여 Qt Assistant 에서 사용할 수 있도록 하려면 Qt 도움말 프로젝트(.qhp) 파일을 만들어야 합니다. 프로젝트 파일에서 가장 중요한 첫 번째 부분은 네임스페이스의 정의입니다. 네임스페이스는 고유해야 하며 Qt Assistant 에서 페이지 URL의 첫 번째 부분이 됩니다. 또한 문서 세트의 공통 폴더 역할을 하는 가상 폴더를 설정해야 합니다. 즉, 두 개의 다른 네임스페이스로 식별되는 두 문서 세트는 하나의 큰 가상 폴더에 있으므로 HTML 파일을 상호 참조할 수 있습니다. 하지만 이 예에서는 하나의 문서 세트만 사용할 수 있으므로 가상 폴더 이름과 기능은 중요하지 않습니다.

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
  <namespace>org.qt-project.examples.simpletextviewer</namespace>
  <virtualFolder>doc</virtualFolder>

다음 단계는 필터 섹션을 정의하는 것입니다. 필터 섹션에는 목차, 인덱스 및 모든 문서 파일의 전체 목록이 포함되며, 필터 속성은 얼마든지 지정할 수 있습니다. 필터 속성은 자유롭게 선택할 수 있는 일반 문자열입니다. 나중에 Qt Assistant 에서 사용자는 이러한 속성을 참조하는 사용자 지정 필터를 정의할 수 있습니다. 필터 섹션의 속성이 사용자 지정 필터의 속성과 일치하면 문서가 표시되고, 그렇지 않으면 Qt Assistant 에 문서가 숨겨집니다.

다시 말하지만 문서 세트가 하나만 있으므로 Qt Assistant 의 필터링 기능이 필요하지 않으므로 필터 속성을 건너뛸 수 있습니다.

이제 목차를 작성합니다. 목차의 항목은 항목 제목에 대한 속성과 실제 페이지로 연결되는 링크가 포함된 section 태그로 정의됩니다. 섹션 태그는 무한히 중첩할 수 있지만 실용적인 이유로 3~4단계보다 깊게 중첩하지 않는 것이 좋습니다. 이 예에서는 목차에 다음과 같은 개요를 사용하겠습니다:

• 간단한 텍스트 뷰어
  • 파일 찾기
    • 파일 대화 상자
    • 와일드카드 일치
    • 찾아보기
  • 파일 열기

도움말 프로젝트 파일에서 개요는 다음과 같이 표시됩니다:

<filterSection>
  <toc>
    <section title="Simple Text Viewer" ref="index.html">
      <section title="Find File" ref="findfile.html">
        <section title="File Dialog" ref="filedialog.html"/>
        <section title="Wildcard Matching" ref="wildcardmatching.html"/>
        <section title="Browse" ref="browse.html"/>
      </section>
      <section title="Open File" ref="openfile.html"/>
    </section>
  </toc>

목차가 정의된 후에는 모든 색인 키워드를 나열합니다:

<keywords>
  <keyword name="Display" ref="index.html"/>
  <keyword name="Rich text" ref="index.html"/>
  <keyword name="Plain text" ref="index.html"/>
  <keyword name="Find" ref="findfile.html"/>
  <keyword name="File menu" ref="findfile.html"/>
  <keyword name="File name" ref="filedialog.html"/>
  <keyword name="File dialog" ref="filedialog.html"/>
  <keyword name="File globbing" ref="wildcardmatching.html"/>
  <keyword name="Wildcard matching" ref="wildcardmatching.html"/>
  <keyword name="Wildcard syntax" ref="wildcardmatching.html"/>
  <keyword name="Browse" ref="browse.html"/>
  <keyword name="Directory" ref="browse.html"/>
  <keyword name="Open" ref="openfile.html"/>
  <keyword name="Select" ref="openfile.html"/>
</keywords>

마지막 단계로 문서를 구성하는 모든 파일을 나열해야 합니다. 여기서 주의해야 할 점은 이미지 파일을 포함한 모든 파일과 사용된 경우 스타일시트까지 모두 나열해야 한다는 것입니다.

    <files>
      <file>browse.html</file>
      <file>filedialog.html</file>
      <file>findfile.html</file>
      <file>index.html</file>
      <file>intro.html</file>
      <file>openfile.html</file>
      <file>wildcardmatching.html</file>
      <file>images/browse.png</file>
      <file>images/fadedfilemenu.png</file>
      <file>images/filedialog.png</file>
      <file>images/handbook.png</file>
      <file>images/mainwindow.png</file>
      <file>images/open.png</file>
      <file>images/wildcard.png</file>
    </files>
  </filterSection>
</QtHelpProject>

이제 도움말 프로젝트 파일이 완성되었습니다. 결과 문서를 Qt Assistant 에서 보려면 이 파일로 Qt 압축 도움말 파일을 생성하고 Qt Assistant 의 기본 도움말 컬렉션에 등록해야 합니다.

qhelpgenerator simpletextviewer.qhp -o simpletextviewer.qch
assistant -register simpletextviewer.qch

지금 Qt Assistant 을 시작하면 Qt 문서 옆에 간단한 텍스트 뷰어 설명서가 표시됩니다. 테스트 용도로는 괜찮지만 최종 버전에서는 Qt Assistant 에 간단한 텍스트 뷰어 설명서만 있기를 원합니다.

커스터마이징 Qt Assistant

Qt Assistant 에 간단한 텍스트 뷰어 설명서만 표시하도록 만드는 가장 쉬운 방법은 자체 도움말 컬렉션 파일을 만드는 것입니다. 컬렉션 파일은 압축된 도움말 파일과 유사한 바이너리 형식으로 저장되며 도움말 컬렉션 프로젝트 파일(*.qhcp)에서 생성됩니다. 컬렉션 파일을 사용하여 Qt Assistant 에서 제공하는 모양과 일부 기능까지 사용자 지정할 수 있습니다.

먼저 창 제목과 아이콘을 변경합니다. "Qt Assistant"가 표시되는 대신 "간단한 텍스트 뷰어"가 표시되므로 사용자가 도움말 뷰어가 실제로 애플리케이션에 속해 있음을 훨씬 더 명확하게 알 수 있습니다.

<?xml version="1.0" encoding="UTF-8"?>
<QHelpCollectionProject version="1.0">
<assistant>
    <title>Simple Text Viewer</title>
    <applicationIcon>images/handbook.png</applicationIcon>
    <cacheDirectory>QtProject/SimpleTextViewer</cacheDirectory>

cacheDirectory 태그는 전체 텍스트 검색용 캐시 파일 또는 설정 파일이 저장될 사용자 데이터 디렉터리( Qt Help 컬렉션 파일 참조)의 하위 디렉터리를 지정합니다.

그런 다음 새 구성에서 처음 실행할 때 Qt Assistant 에 표시되는 페이지를 설정합니다. URL은 Qt 도움말 프로젝트 파일에 정의된 네임스페이스와 가상 폴더, 그리고 실제 페이지 파일 이름으로 구성됩니다.

<startPage>qthelp://org.qt-project.examples.simpletextviewer/doc/index.html</startPage>

다음으로 "정보" 메뉴 항목의 이름을 "About(정보)"에서 "About Simple Text Viewer(간단한 텍스트 뷰어 정보)"로 변경합니다. 정보 대화 상자의 내용도 정보 텍스트나 아이콘을 가져온 파일을 지정하여 변경합니다.

<aboutMenuText>
    <text>About Simple Text Viewer</text>
</aboutMenuText>
<aboutDialog>
    <file>about.txt</file>
    <icon>images/icon.png</icon>
</aboutDialog>

Qt Assistant 는 환경설정 대화상자를 통해 문서를 추가하거나 제거할 수 있는 기능을 제공합니다. 이 기능은 Qt Assistant 을 더 많은 애플리케이션의 중앙 도움말 뷰어로 사용할 때 유용하지만, 저희의 경우에는 실제로 사용자가 문서를 제거하지 못하도록 하고 싶었습니다. 그래서 환경설정 대화 상자에서 문서 탭을 숨겼습니다.

주소 표시줄은 이렇게 작은 문서 집합에서는 별로 중요하지 않으므로 이 기능도 끕니다. 필터 속성이 없는 필터 섹션이 하나만 있으면 Qt Assistant 의 필터 기능도 비활성화할 수 있으므로 필터 페이지와 필터 도구 모음을 사용할 수 없게 됩니다.

    <enableDocumentationManager>false</enableDocumentationManager>
    <enableAddressBar>false</enableAddressBar>
    <enableFilterFunctionality>false</enableFilterFunctionality>
</assistant>

테스트 목적으로 이미 압축된 도움말 파일을 생성하여 Qt Assistant 의 기본 도움말 컬렉션에 등록했습니다. 다음 줄을 사용하면 동일한 결과를 얻을 수 있습니다. 유일한 중요한 차이점은 압축된 도움말 파일을 기본 컬렉션이 아닌 자체 컬렉션 파일에 등록한다는 것입니다.

  <docFiles>
    <generate>
        <file>
            <input>simpletextviewer.qhp</input>
            <output>simpletextviewer.qch</output>
            </file>
        </generate>
    <register>
        <file>simpletextviewer.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>

마지막 단계로 도움말 컬렉션 프로젝트 파일에서 바이너리 컬렉션 파일을 생성해야 합니다. 이 작업은 qhelpgenerator 도구를 실행하여 수행합니다.

qhelpgenerator simpletextviewer.qhcp -o simpletextviewer.qhc

Qt Assistant 에 대한 모든 사용자 지정 사항을 테스트하기 위해 명령줄에 컬렉션 파일 이름을 추가합니다:

assistant -collectionFile simpletextviewer.qhc

어시스턴트 클래스를 통해 Qt Assistant 제어하기

먼저 원격 애플리케이션에서 Qt Assistant 을 시작하고 작동하는 방법을 살펴 보겠습니다. 이를 위해 Assistant 이라는 클래스를 만듭니다.

이 클래스는 문서 페이지를 표시하는 데 사용되는 공개 함수와 Qt Assistant 가 실행 중인지 확인하는 비공개 헬퍼 함수 하나를 제공합니다.

Qt Assistant 실행은 startAssistant() 함수에서 QProcess를 생성하고 시작하기만 하면 됩니다. 프로세스가 이미 실행 중이면 함수가 즉시 반환됩니다. 그렇지 않으면 프로세스를 설정하고 시작해야 합니다.

bool Assistant::startAssistant()
{
    if (m_process.isNull()) {
        m_process.reset(new QProcess);
        QObject::connect(m_process.data(), &QProcess::finished,
                         m_process.data(), [this](int exitCode, QProcess::ExitStatus status) {
            finished(exitCode, status);
        });
    }

    if (m_process->state() != QProcess::Running) {
        QString app = QLibraryInfo::path(QLibraryInfo::BinariesPath);
#ifndef Q_OS_DARWIN
        app += "/assistant"_L1;
#else
        app += "/Assistant.app/Contents/MacOS/Assistant"_L1;
#endif

        const QString collectionDirectory = documentationDirectory();
        if (collectionDirectory.isEmpty()) {
            showError(tr("The documentation directory cannot be found"));
            return false;
        }

        const QStringList args{"-collectionFile"_L1,
                               collectionDirectory + "/simpletextviewer.qhc"_L1,
                               "-enableRemoteControl"_L1};

        m_process->start(app, args);

        if (!m_process->waitForStarted(3000)) {
            showError(tr("Unable to launch Qt Assistant (%1): %2")
                      .arg(QDir::toNativeSeparators(app), m_process->errorString()));
            return false;
        }
    }
    return true;
}

프로세스를 시작하려면 Qt Assistant 의 실행 파일 이름과 사용자 지정 모드에서 Qt Assistant 을 실행하기 위한 명령줄 인수가 필요합니다. 실행 파일 이름은 플랫폼에 따라 달라지기 때문에 약간 까다롭지만 다행히도 macOS에서만 다릅니다.

Qt Assistant 을 실행할 때 -collectionFile 명령줄 인수를 사용하여 표시되는 문서를 변경할 수 있습니다. 아무런 옵션 없이 시작하면 Qt Assistant 에 기본 문서 세트가 표시됩니다. Qt가 설치되면 Qt Assistant 의 기본 문서 세트에는 Qt 참조 문서와 Qt Designer 및 qmake 와 같은 Qt와 함께 제공되는 도구가 포함되어 있습니다.

이 예제에서는 프로세스의 명령줄 옵션에 애플리케이션별 컬렉션 파일을 전달하여 기본 문서 세트를 사용자 정의 문서로 대체합니다.

마지막 인수로 -enableRemoteControl 을 추가하여 Qt Assistant 이 stdin 채널에서 문서의 특정 페이지를 표시하는 명령과 같은 명령을 수신하도록 합니다. 그런 다음 프로세스를 시작하고 실제로 실행될 때까지 기다립니다. 어떤 이유로 Qt Assistant 를 시작할 수 없는 경우 startAssistant() 은 false를 반환합니다.

showDocumentation() 구현은 이제 간단합니다. 먼저 Qt Assistant 가 실행 중인지 확인한 다음 프로세스의 stdin 채널을 통해 page 을 표시하라는 요청을 보냅니다. 여기서 명령이 라인 끝 토큰으로 종료되어 채널을 플러시하는 것이 매우 중요합니다.

void Assistant::showDocumentation(const QString &page)
{
    if (!startAssistant())
        return;

    QByteArray ba("SetSource ");
    ba.append("qthelp://org.qt-project.examples.simpletextviewer/doc/");

    m_process->write(ba + page.toLocal8Bit() + '\n');
}

마지막으로 애플리케이션이 종료되는 경우 Qt Assistant 가 제대로 종료되는지 확인합니다. QProcess의 소멸자는 프로세스를 종료하므로 애플리케이션이 사용자 설정 저장과 같은 작업을 수행할 수 없어 설정 파일이 손상될 수 있습니다. 이를 방지하기 위해 Assistant 클래스의 소멸자에서 Qt Assistant 을 종료하도록 요청합니다.

Assistant::~Assistant()
{
    if (!m_process.isNull() && m_process->state() == QProcess::Running) {
        QObject::disconnect(m_process.data(), &QProcess::finished, nullptr, nullptr);
        m_process->terminate();
        m_process->waitForFinished(3000);
    }
}

메인 윈도우 클래스

MainWindow 클래스는 메인 애플리케이션 창에 두 개의 메뉴를 제공합니다: 파일 메뉴는 사용자가 기존 파일을 열고 볼 수 있게 해주고, 도움말 메뉴는 애플리케이션과 Qt에 대한 정보를 제공하며, Qt Assistant 을 열어 애플리케이션의 문서를 표시할 수 있게 해줍니다.

도움말 기능에 액세스할 수 있도록 MainWindow 의 생성자에서 Assistant 객체를 초기화합니다.

MainWindow::MainWindow()
    : textViewer(new TextEdit)
    , assistant(new Assistant)
{
    ...
}

그런 다음 간단한 텍스트 뷰어 애플리케이션에 대한 모든 액션을 생성합니다. 특히 F1 바로 가기 또는 도움말 > 도움말 내용 메뉴 항목을 통해 액세스할 수 있는 assistantAct 액션이 흥미롭습니다. 이 액션은 MainWindow 클래스의 showDocumentation() 슬롯에 연결됩니다.

void MainWindow::createActions()
{
    assistantAct = new QAction(tr("Help Contents"), this);
    assistantAct->setShortcut(QKeySequence::HelpContents);
    connect(assistantAct, &QAction::triggered, this, &MainWindow::showDocumentation);
    ...
}

showDocumentation() 슬롯에서는 문서 홈 페이지의 URL을 사용하여 Assistant 클래스의 showDocumentation() 함수를 호출합니다.

void MainWindow::showDocumentation()
{
    assistant->showDocumentation("index.html");
}

마지막으로, 애플리케이션을 종료하기 전에 애플리케이션의 Qt Assistant 인스턴스가 제대로 닫혔는지 확인하기 위해 보호된 QWidget::closeEvent() 이벤트 핸들러를 다시 구현해야 합니다.

void MainWindow::closeEvent(QCloseEvent *)
{
    delete assistant;
}

FindFileDialog 클래스

단순 텍스트 뷰어 애플리케이션은 사용자가 와일드카드 일치를 사용하여 파일을 검색할 수 있는 파일 찾기 대화 상자를 제공합니다. 검색은 지정된 디렉토리 내에서 수행되며, 사용자에게 기존 파일 시스템을 탐색하여 관련 디렉토리를 찾을 수 있는 옵션이 제공됩니다.

생성자에서는 인자로 전달된 Assistant 및 QTextEdit 객체에 대한 참조를 저장합니다. Assistant 객체는 곧 보게 되겠지만 FindFileDialog 의 help() 슬롯에서 사용되며, QTextEdit는 대화 상자의 openFile() 슬롯에서 선택된 파일을 표시하는 데 사용됩니다.

FindFileDialog::FindFileDialog(TextEdit *editor, Assistant *assistant)
    : QDialog(editor)
    , currentEditor(editor)
    , currentAssistant(assistant)
{
    ...
}

FindFileDialog 클래스에서 관찰해야 할 가장 관련성이 높은 멤버는 비공개 help() 슬롯입니다. 이 슬롯은 대화 상자의 도움말 버튼에 연결되어 있으며, Assistant 의 showDocumentation() 함수를 호출하여 현재 Qt Assistant 인스턴스를 대화 상자의 문서와 함께 전경으로 가져옵니다.

void FindFileDialog::help()
{
    currentAssistant->showDocumentation("filedialog.html");
}

요약

Qt Assistant 이 애플리케이션의 사용자 정의 도움말 도구로 작동하도록 하려면, Qt 압축 도움말 파일을 포함한 사용자 정의 도움말 컬렉션 파일과 함께 Qt Assistant 을 제어하는 프로세스를 애플리케이션에 제공해야 합니다.

Qt Assistant 을 사용자 정의 도움말 뷰어로 사용하는 애플리케이션에서 사용할 수 있는 옵션 및 설정에 대한 자세한 내용은 사용자 정의 Qt Assistant 을 참조하십시오.

예제 프로젝트 @ code.qt.io