사용자 지정하기 Qt Assistant

Qt Assistant 을 사용자 지정 도움말 보기로 사용하려면 단순히 사용자 지정 문서를 표시할 수 있는 것 이상의 기능이 필요합니다. Qt Assistant 의 모양을 사용자 지정하여 Qt Assistant 이 아닌 애플리케이션별 도움말 보기로 보이도록 하는 것도 마찬가지로 중요합니다. 이는 창 제목이나 아이콘은 물론 일부 애플리케이션별 메뉴 텍스트 및 작업을 변경하여 수행할 수 있습니다. 가능한 사용자 지정의 전체 목록은 사용자 지정 도움말 모음 파일 만들기를 참조하세요.

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

간단한 텍스트 뷰어 예제에서는 이 문서에 설명된 기술을 사용하여 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에서 반환한 경로의 하위 디렉터리에 저장됩니다. 이 사용자별 위치 내의 하위 디렉터리 또는 캐시 디렉터리는 도움말 컬렉션 프로젝트 파일에서 정의할 수 있습니다. 예를 들어

<?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 으로 전달하여 상태 메시지가 출력되지 않도록 할 수 있습니다.

모양 변경하기 Qt Assistant

시작 시 다른 명령줄 옵션을 전달하여 Qt Assistant 의 모양을 변경할 수 있습니다. 그러나 이러한 명령줄 옵션은 콘텐츠 또는 색인 보기와 같은 특정 위젯만 표시하거나 숨길 수 있습니다. 애플리케이션 제목이나 아이콘을 변경하거나 필터 기능을 비활성화하는 등의 다른 사용자 지정은 사용자 지정 도움말 모음 파일을 만들어서 수행할 수 있습니다.

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

Qt Assistant 에서 사용하는 도움말 컬렉션 파일(*.qhc)은 도움말 컬렉션 프로젝트 파일(*.qhcp)에서 qhelpgenerator 툴을 실행할 때 만들어집니다. 프로젝트 파일 형식은 XML이며 다음 태그를 지원합니다:

Qt Assistant 특정 태그 외에도 문서를 생성하고 등록하기 위한 태그를 사용할 수 있습니다. 자세한 내용은 Qt Help 컬렉션 파일 문서를 참조하세요.

사용 가능한 모든 태그를 사용하는 도움말 컬렉션 파일의 예가 아래에 나와 있습니다:

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