QT Assistant, Не пойму, куда ткнуться. Ткните пожалуйста. Опции

[Shpiron]

Всем здравствуйте. Я в QT третий день, как бы это смешно не звучало.. Моя задача - научиться делать в ней доку. Есть набор html-файлов, хочу их отобразить с помощью QT Assistant'a...
Но как то сделать, не соображу совсем. Перечитала кучу материалов в нете. Прочитала пример про SimpleTextViewer. Но не поняла ничего
Не пойму, где что писать, где какие xml-ки формировать, куда что загонять для генерации.. как получить qch-файлы...
Подскажите что-нибудь.. Пожааалуйста...

[alex977]

Перевод примера "Simple Text Viewer" (пока на сайте не появился).
Скопировать пример в другой каталог. Поменять на нужные файлы. Выполнить шаги, приведенные в описании примера.

Раскрывающийся текст

Пример "Simple Text Viewer" показывает, как использовать Qt Assistant в качестве настраиваемого просмотрщика помощи для вашего приложения.

Это делается в два этапа. Во-первых, создаётся документация и настраивается Qt Assistant; во-вторых, в приложение добавляется функциональность для запуска и управления Qt Assistant.

Приложение "Simple Text Viewer" позволяет пользователю выбрать и просмотреть существующие файлы.

Приложение предоставляет свою собственную пользовательскую документацию, которая доступна в меню Help в панели меню главного окна, или щелкнув по кнопке Help в диалоге поиска файла приложения.

Пример состоит из четырех классов:

* Assistant предоставляет функциональность для запуска Qt Assistant.
* MainWindow - главное окно приложения.
* FindFileDialog позволяет пользователю искать файлы используя совпадение с метасимволами (wildcard).
* TextEdit предоставляет браузер форматированного текста, который гарантирует, что изображения на которые есть ссылки в документах HTML, будут правильно выведены на экран.

Обратите внимание на то, что мы комментируем только те части реализации, которые относятся к главному вопросу, который заставляет Qt Assistant действовать как настраиваемый просмотрщик справки для нашего приложения Simple Text Viewer.

Создание документации и настройка Qt Assistant

Как создать реальную документацию в форме HTML-страниц - за рамками этого примера. Вообще, HTML-страницы могут быть написаны вручную или сгенерированы с помощью инструментов документирования таких как qdoc или Doxygen. Для целей данного примера мы притворились, что файлы HTML уже созданы. Поэтому единственной вещью, которая осталось сделать - сообщить Qt Assistant как структурировать и отображать справочную информацию.

Упорядочение документации для Qt Assistant

Простые файлы HTML содержат только текст или документацию по отдельным темам, но обычно они не включают информацию о том, как для связаны несколько документов HTML друг с другом или в каком порядке предполагается их читать. Недостает оглавления наряду с указателем для быстрого доступа к определённому содержимому помощи, без просмотра множества документов для того чтобы найти порцию информации.

Чтобы упорядочить документацию и сделать её пригодной для Qt Assistant, мы создаём файл проекта помощи Qt (.qhp). Первой и наиболее важной частью файл проекта является объявление пространства имён. Пространство имён является уникальным и будет первой частью URL страницы в Qt Assistant. Кроме того, мы установили виртуальную папку, которая служит в качестве общей папка для наборов документации. Это означает, что два набора документации идентифицируемых двумя разными пространствами имён могут перекрёстно ссылаться на файлы HTML пока эти файлы находятся в одной большой виртуальной папке. Тем не менее, для этого примера, у нас есть только один набор документации, поэтому имя виртуальной папки и её функциональность не важны.

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

Следующий шаг - определить секцию фильтра. Секция фильтра содержит таблицу оглавление, указатели и полный список всех файлов документации, а также может иметь любое количество назначенных ему атрибутов фильтра. Атрибут фильтра - это обыкновенная строка, которая может быть легко выбрана. Позднее в Qt Assistant, пользователи могут определить пользовательский фильтр ссылаясь на эти атрибуты. Если атрибуты секции фильтра совпадут с атрибутами пользовательского фильтра, то документация будет показана, в противном случае Qt Assistant скроет документацию.

С другой стороны, так как мы имеем только один набор документации, нам не нужна функциональность фильтрования Qt Assistant и поэтому мы можем пропустить атрибуты фильтра.

Теперь мы создадим оглавление. Элемент в оглавлении определяется тегом section, который содержит атрибуты для элемента заголовка а также ссылку на фактическую страницу. Теги секций могут вкладываться друг в друга до бесконечности, но по практическим соображениям не рекомендуется вкладывать их глубже, чем на три или четыре уровня. Для нашего примера мы хотим использовать следующую структуру оглавления:

* "Simple Text Viewer"
o "Find File"
+ "File Dialog"
+ "Wildcard Matching"
+ "Browse"
o "Open File"

В файле проекта помощи структура представлена так:

<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>
<section title="Wildcard Matching" ref="./wildcardmatching.html"></section>
<section title="Browse" ref="./browse.html"></section>
</section>
<section title="Open File" ref="./openfile.html"></section>
</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/*.png</file>
</files>
</filterSection>
</QtHelpProject>

Теперь файл проекта помощи завершён. Если вы хотите увидеть получившуюся документацию в Qt Assistant, сгенерируйте из него сжатый файл помощи Qt и зарегистрируйте его с коллекцией справки Qt Assistant по умолчанию.

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

Если вы запустите теперь Qt Assistant, то вы увидите рядом с документацией Qt документацию Simple Text Viewer. Это хорошо для целей отладки, но для окончательной версии мы хотим иметь в Qt Assistant только документацию Simple Text Viewer.
Настройка Qt Assistant

Самый лёгкий способ заставить Qt Assistant выводить на экран только документацию Simple Text Viewer - создать свой собственный файл коллекции помощи. Файл коллекции сохраняется в двоичном формате, подобном формату сжатого файла помощи, и генерируется из файл проекта коллекции помощи (*.qhcp). С помощью файла коллекции можно настроить внешний вид и даже некоторую функциональность предлагаемую Qt Assistant.

Сначала мы изменим заголовок окна и пиктограмму. Вместо показа "Qt Assistant" он будет показывать "Simple Text Viewer", так понятнее пользователю, что просмотрщик помощи фактически принадлежит нашему приложению.

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

Тег cacheDirectory задаёт подкаталог в каталоге пользовательских данных (смотрите Файлы коллекции справки Qt), где сохраняется файл кэша для полнотекстового поиска или файл настроек.

После этого мы установим страницу, отображаемую Qt Assistant при самом первом запуске в новой конфигурации. URL состоит из пространства имён и виртуальной папки, определённой в файле проекта помощи Qt, следом - имя файла реальной страницы.

<startPage>qthelp://com.trolltech.examples.simpletextviewer/doc/index.html</startPage>

Потом мы меняем имя пункта меню "About" на "About Simple Text Viewer". Содержимое диалога About также изменяется задав файл, откуда брать текст о программе или пиктограмму.

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

В качестве последнего шага, мы генерируем двоичный файл коллекции из файла проекта коллекции помощи. Это делают запустив инструмент qcollectiongenerator.

qcollectiongenerator simpletextviewer.qhcp -o simpletextviewer.qhc

Чтобы проверить все наши настройки сделанные в Qt Assistant, мы добавили имя файла коллекции в командную строку:

assistant -collectionFile simpletextviewer.qhc

Сообщение отредактировал alex977 - 13.6.2010, 23:01