Qt Help 프레임워크

개요

Qt Help 시스템에는 Qt 도움말 파일을 생성하고 표시하는 도구가 포함되어 있습니다. 또한, Qt 애플리케이션에 온라인 도움말을 통합할 수 있도록 프로그래밍 방식으로 도움말 콘텐츠에 접근할 수 있는 클래스를 제공합니다.

실제 도움말 데이터, 즉 목차, 색인 키워드 또는 HTML 문서는 Qt Help 압축 도움말 파일에 포함되어 있습니다. 따라서 이러한 도움말 파일 하나는 대개 하나의 매뉴얼이나 문서 세트를 나타냅니다. 대부분의 제품은 더 포괄적이며 여러 도구로 구성되어 있기 때문에, 하나의 매뉴얼만으로는 충분하지 않은 경우가 많습니다. 대신, 동시에 접근할 수 있어야 하는 여러 매뉴얼이 존재합니다. 이상적으로는 한 매뉴얼의 특정 내용을 다른 매뉴얼에서 참조할 수 있어야 합니다. 따라서 Qt Help 시스템은 임의의 개수의 압축된 도움말 파일을 포함하는 도움말 모음 파일을 기반으로 작동합니다.

그러나 여러 문서 세트를 통합하기 위해 컬렉션 파일을 사용하면 몇 가지 문제가 발생할 수 있습니다. 예를 들어, 하나의 색인 키워드가 서로 다른 문서 세트에 정의되어 있을 수 있습니다. 따라서 색인에서 키워드만 보고 이를 클릭했을 때, 기대하는 문서가 표시될 것이라고 확신할 수 없습니다. 따라서 Qt Help 시스템은 특정 속성을 기준으로 도움말 내용을 필터링할 수 있는 기능을 제공합니다. 다만 이를 위해서는 압축된 도움말 파일을 생성하기 전에 해당 속성이 도움말 내용에 미리 할당되어 있어야 합니다.

앞서 언급한 바와 같이, Qt Help 압축 도움말 파일에는 모든 데이터가 포함되어 있으므로 더 이상 개별 HTML 파일을 모두 배포할 필요가 없습니다. 대신, 압축 도움말 파일과 선택적으로 컬렉션 파일만 배포하면 됩니다. 컬렉션 파일은 선택 사항입니다. 예를 들어 이전 릴리스에서 생성된 기존 컬렉션 파일을 사용할 수 있기 때문입니다.

따라서 일반적으로 도움말 시스템과 연동되는 파일은 네 개이며, 이 중 두 개는 Qt Help를 생성하는 데 사용되고, 나머지 두 개는 배포용입니다:

생성 Qt Help

Qt Help 도움말 시스템용 도움말 파일을 빌드할 때는 HTML 문서 파일이 이미 존재한다고 가정합니다.

HTML 문서가 준비되면, 확장자가 .qhp 인 Qt Help 프로젝트 파일을 생성해야 합니다. 이 파일에 모든 관련 정보를 지정한 후, 다음 명령을 실행하여 컴파일해야 합니다:

qhelpgenerator doc.qhp -o doc.qch

doc.qch 파일에는 목차 및 색인 키워드와 함께 모든 HTML 파일이 압축된 형태로 포함되어 있습니다. 생성된 파일이 올바른지 확인하려면 Qt Assistant 를 열고, 해당 파일을 Settings > Documentation 경로에 설치하십시오.

표준 Qt 소스 빌드의 경우, .qhp 파일이 생성되어 HTML 페이지와 동일한 디렉터리에 배치됩니다.

Qt Help 컬렉션 생성

첫 번째 단계는 Qt Help 컬렉션 프로젝트 파일을 생성하는 것입니다. Qt Help 컬렉션은 주로 압축된 도움말 파일에 대한 참조를 저장하므로, mycollection.qhcp 프로젝트 파일은 예상대로 매우 간단합니다:

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <docFiles>
        <register>
            <file>doc.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>

컬렉션 파일을 실제로 생성하려면 다음을 호출하십시오:

qhelpgenerator mycollection.qhcp -o mycollection.qhc

압축된 도움말과 컬렉션 파일을 한 번에 생성하려면, 도움말 생성기가 먼저 압축된 도움말을 생성하도록 지시하도록 도움말 컬렉션 프로젝트 파일을 수정하십시오:

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

물론, ` generate ` 또는 ` register ` 섹션에 여러 파일을 지정할 수 있으므로, 한 번에 원하는 수의 압축된 도움말 파일을 생성하고 등록할 수 있습니다.

QHelpEngine API 사용

QHelpEngine 을 사용하면 도움말 내용을 애플리케이션에 직접 삽입할 수 있습니다.

웹 브라우저와 같은 외부 애플리케이션에서 도움말을 표시하는 대신, 온라인 도움말을 애플리케이션에 직접 내장할 수도 있습니다. 그러면 QHelpEngine 클래스를 통해 내용을 불러와 거의 모든 형태로 표시할 수 있습니다. QTextBrowser 에서 도움말을 표시하는 것이 가장 일반적인 방법이지만, 'What's This' 도움말에 내장하는 것도 충분히 가능합니다.

파일 엔진에서 도움말 데이터를 가져오는 데는 많은 코드가 필요하지 않습니다. 첫 번째 단계는 도움말 엔진의 인스턴스를 생성하는 것입니다. 그런 다음 엔진에 식별자(이 경우 MyDialog::ChangeButton)에 할당된 링크를 요청합니다. 링크가 발견되었다면, 즉 해당 주제에 대한 도움말 문서가 하나 이상 존재한다는 의미이므로, QHelpEngineCore::fileData()를 호출하여 실제 도움말 내용을 가져와 사용자에게 문서를 표시합니다.

QHelpEngineCore helpEngine("mycollection.qhc");
...

// get all file references for the identifier
QList<QHelpLink> links =
    helpEngine.documentsForIdentifier(QLatin1String("MyDialog::ChangeButton"));

// If help is available for this keyword, get the help data
// of the first file reference.
if (links.count()) {
    QByteArray helpData = helpEngine->fileData(links.constBegin()->url);
    // show the documentation to the user
    if (!helpData.isEmpty())
        displayHelp(helpData);
}

API 사용 방법에 대한 자세한 내용은 QHelpEngine 클래스 참조 문서를 확인해 주세요.