사용자 정의 Qt Assistant

Qt Assistant 를 사용자 정의 도움말 뷰어로 사용하려면 단순히 사용자 정의 문서를 표시할 수 있는 것 이상의 기능이 필요합니다. Qt Assistant 의 외관을 사용자 정의하여 Qt Assistant 가 아닌 특정 애플리케이션 전용 도움말 뷰어로 인식되도록 하는 것도 마찬가지로 중요합니다. 이는 창 제목이나 아이콘은 물론, 애플리케이션별 메뉴 텍스트 및 동작을 변경함으로써 달성할 수 있습니다. 사용 가능한 사용자 정의 항목의 전체 목록은 ‘사용자 정의 도움말 컬렉션 파일 만들기’를 참조하십시오.

사용자 지정 도움말 뷰어의 또 다른 요구 사항은, 해당 뷰어가 도움말을 제공하는 애플리케이션으로부터 동작이나 명령을 수신할 수 있는 기능입니다. 이는 애플리케이션이 상황에 맞는 도움말을 제공할 때 특히 중요합니다. 이러한 방식으로 사용될 때, 도움말 뷰어는 애플리케이션의 현재 상태에 따라 내용을 변경해야 할 수 있습니다. 즉, 애플리케이션은 현재 상태를 도움말 뷰어에 전달해야 합니다. 자세한 내용은 ‘ Qt Assistant 원격 사용’을 참조하십시오.

'Simple Text Viewer' 예제는 이 문서에 설명된 기법을 사용하여 Qt Assistant 를 애플리케이션의 사용자 정의 도움말 뷰어로 활용하는 방법을 보여줍니다.

Qt Help 컬렉션 파일

Qt Assistant 에 대해 알아야 할 첫 번째 중요한 점은, 이 도구가 외관과 관련된 모든 설정 및 설치된 문서 목록을 도움말 컬렉션 파일에 저장한다는 것입니다. 즉, 서로 다른 컬렉션 파일을 사용하여 Qt Assistant 를 실행할 경우, Qt Assistant 의 모습이 완전히 달라질 수 있습니다. 설정을 이처럼 완전히 분리함으로써, Qt Assistant 의 서로 다른 인스턴스 간에 간섭이 발생할 위험 없이 한 대의 컴퓨터에서 여러 응용 프로그램에 대한 사용자 지정 도움말 뷰어로 Qt Assistant 를 배포할 수 있습니다.

Qt Assistant 에 특정 도움말 컬렉션을 적용하려면, 프로그램을 시작할 때 명령줄에서 해당 컬렉션 파일을 지정하십시오. 예:

assistant -collectionFile mycollection.qhc

그러나 모든 설정을 하나의 컬렉션 파일에 저장하면 몇 가지 문제가 발생합니다. 컬렉션 파일은 일반적으로 응용 프로그램 자체와 동일한 디렉터리나 그 하위 디렉터리 중 하나에 설치됩니다. 디렉터리와 운영 체제에 따라, 사용자 설정이 저장될 때 발생하는 경우처럼 사용자가 이 파일을 수정할 권한이 전혀 없을 수도 있습니다. 또한, 파일이 CD-ROM과 같은 읽기 전용 매체에 있는 경우처럼 사용자에게 쓰기 권한을 부여하는 것 자체가 불가능할 수도 있습니다.

모든 사용자에게 전역적으로 접근 가능한 컬렉션 파일에 설정을 저장할 수 있는 권한을 부여할 수 있다 하더라도, ‘ Qt Assistant ’을 종료할 때 한 사용자의 설정이 다른 사용자에 의해 덮어쓰이게 될 것입니다.

이러한 딜레마를 해결하기 위해, Qt Assistant 는 원래 컬렉션 파일을 거의 그대로 복사한 사용자별 컬렉션 파일을 생성합니다. 사용자별 컬렉션 파일은 QDesktopServices::AppDataLocation이 반환하는 경로의 하위 디렉터리에 저장됩니다. 이 사용자별 위치 내의 하위 디렉터리, 즉 캐시 디렉터리는 help collection 프로젝트 파일에서 정의할 수 있습니다. 예를 들어:

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <assistant>
        <title>My Application Help</title>
        <cacheDirectory>mycompany/myapplication</cacheDirectory>
        ...
    </assistant>
</QHelpCollectionProject>

따라서

assistant -collectionFile mycollection.qhc

Qt Assistant 는 실제로 컬렉션 파일을 사용합니다:

%QDesktopServices::AppDataLocation%/mycompany/myapplication/mycollection.qhc

사용자별 컬렉션 파일을 사용하여 Qt Assistant 를 실행할 필요는 전혀 없습니다. 대신, 애플리케이션과 함께 제공되는 컬렉션 파일을 항상 사용해야 합니다. 또한, 컬렉션 파일에서 문서를 추가하거나 제거할 때(다음 섹션 참조)에는 항상 일반 컬렉션 파일을 사용하십시오. 설치된 문서 목록이 변경되면 Qt Assistant 가 사용자 컬렉션 파일의 동기화를 처리합니다.

사용자 정의 문서 표시

Qt Assistant 가 문서를 표시하려면 실제 문서 파일의 위치를 파악해야 합니다. 즉, Qt 압축 도움말 파일(*.qch)의 위치를 알아야 합니다. 앞서 언급한 바와 같이, Qt Assistant 는 현재 사용 중인 컬렉션 파일에 압축된 도움말 파일에 대한 참조 정보를 저장합니다. 따라서 새 컬렉션 파일을 생성할 때 Qt Assistant 가 표시해야 할 모든 압축된 도움말 파일을 나열할 수 있습니다.

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

때로는 Qt Assistant 가 도움말 뷰어로 작동하는 애플리케이션에 따라, 시간이 지남에 따라 더 많은 문서를 추가해야 할 필요가 있습니다. 예를 들어, 애플리케이션 구성 요소나 플러그인을 추가로 설치할 때입니다. 이는 Qt Assistant 에서 ‘편집 > 환경 설정> 문서’를 선택하여 수동으로 수행할 수 있습니다. 그러나 이 방법의 단점은 모든 사용자가 새로운 문서에 접근하기 위해 수동으로 이 작업을 수행해야 한다는 점입니다.

기존 컬렉션 파일에 문서를 추가하는 권장 방법은 Qt Assistant 의 -register 명령줄 플래그를 사용하는 것입니다. 이 플래그를 사용하여 Qt Assistant 를 실행하면 문서가 추가되며, 등록이 성공했는지 여부에 대한 메시지가 표시된 후 Qt Assistant 가 즉시 종료됩니다.

검색 색인 생성은 사용자 정의 *.html, *.htm 및 *.txt 파일에 대해서만 수행됩니다.

assistant -collectionFile mycollection.qhc -register myapplication-manual.qch

-quiet 플래그를 Qt Assistant 에 전달하면 상태 메시지가 출력되지 않습니다.

xml-ph-0000@deepl.internal의 외관 변경 Qt Assistant

Qt Assistant 의 외관은 시작 시 다양한 명령줄 옵션을 전달하여 변경할 수 있습니다. 그러나 이러한 명령줄 옵션을 사용하면 목차나 색인 보기와 같은 특정 위젯을 표시하거나 숨길 수 있을 뿐입니다. 응용 프로그램 제목이나 아이콘 변경, 필터 기능 비활성화와 같은 기타 사용자 지정은 사용자 지정 도움말 모음 파일을 생성하여 수행할 수 있습니다.

사용자 지정 도움말 컬렉션 파일 만들기

Qt Assistant 에서 사용하는 도움말 컬렉션 파일(*.qhc)은 도움말 컬렉션 프로젝트 파일(*.qhcp)에 대해 qhelpgenerator 도구를 실행할 때 생성됩니다. 프로젝트 파일 형식은 XML이며 다음 태그를 지원합니다:

Qt Assistant 에 특화된 태그 외에도, 문서를 생성하고 등록하기 위한 태그를 사용할 수 있습니다. 자세한 내용은 Qt Help Collection Files 문서를 참조하십시오.

사용 가능한 모든 태그를 사용하는 도움말 컬렉션 파일의 예는 다음과 같습니다.

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <assistant>
        <title>My Application Help</title>
        <startPage>qthelp://com.mycompany.1_0_0/doc/index.html</startPage>
        <currentFilter>myfilter</currentFilter>
        <applicationIcon>application.png</applicationIcon>
        <enableFilterFunctionality>false</enableFilterFunctionality>
        <enableDocumentationManager>false</enableDocumentationManager>
        <enableAddressBar visible="true">true</enableAddressBar>
        <cacheDirectory>mycompany/myapplication</cacheDirectory>
        <aboutMenuText>
            <text>About My Application</text>
            <text language="de">Über meine Applikation...</text>
        </aboutMenuText>
        <aboutDialog>
            <file>about.txt</file>
            <file language="de">ueber.txt</file>
            <icon>about.png</icon>
        </aboutDialog>
    </assistant>
    <docFiles>
        <generate>
            <file>
                <input>myapplication-manual.qhp</input>
                <output>myapplication-manual.qch</output>
            </file>
        </generate>
        <register>
            <file>myapplication-manual.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>

바이너리 컬렉션 파일을 생성하려면 qhelpgenerator 도구를 실행하십시오:

qhelpgenerator mycollection.qhcp -o mycollection.qhc

생성된 컬렉션 파일을 테스트하려면 다음 방법대로 Qt Assistant 를 실행하십시오:

assistant -collectionFile mycollection.qhc

Qt Assistant 원격 사용

도움말 뷰어는 독립 실행형 응용 프로그램이지만, 대부분은 해당 도움말을 제공하는 응용 프로그램에 의해 실행됩니다. 이러한 방식을 통해 응용 프로그램은 도움말 뷰어가 시작되는 즉시 특정 도움말 내용을 표시하도록 요청할 수 있습니다. 이 방식의 또 다른 장점은 애플리케이션이 도움말 뷰어 프로세스와 통신할 수 있어, 애플리케이션의 현재 상태에 따라 다른 도움말 내용을 표시하도록 요청할 수 있다는 점입니다.

따라서 Qt Assistant 을 애플리케이션의 사용자 정의 도움말 뷰어로 사용하려면, QProcess를 생성하고 Qt Assistant 실행 파일의 경로를 지정하기만 하면 됩니다. Qt Assistant 가 애플리케이션의 신호를 수신하도록 하려면, -enableRemoteControl 명령줄 옵션을 전달하여 원격 제어 기능을 활성화하십시오.

다음 예제는 이를 구현하는 방법을 보여줍니다:

QProcess *process = new QProcess;
QStringList args;
args << QLatin1String("-collectionFile")
    << QLatin1String("mycollection.qhc")
    << QLatin1String("-enableRemoteControl");
process->start(QLatin1String("assistant"), args);
if (!process->waitForStarted())
    return;

Qt Assistant 가 실행되면, 프로세스의 stdin 채널을 사용하여 명령을 보낼 수 있습니다. 아래 코드 스니펫은 Qt Assistant 에 문서의 특정 페이지를 표시하도록 지시하는 방법을 보여줍니다.

QByteArray ba;
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);

Qt Assistant 를 제어하려면 다음 명령어를 사용할 수 있습니다:

짧은 시간 내에 여러 명령을 전송하려는 경우, 명령마다 한 줄씩 작성하는 대신 프로세스의 stdin에 한 줄만 작성하는 것이 좋습니다. 다음 예제와 같이 명령은 세미콜론으로 구분해야 합니다.

QByteArray ba;
ba.append("hide bookmarks;");
ba.append("hide index;");
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);