QT Assistant, Не пойму, куда ткнуться. Ткните пожалуйста. |
Здравствуйте, гость ( Вход | Регистрация )
QT Assistant, Не пойму, куда ткнуться. Ткните пожалуйста. |
Shpiron |
13.6.2010, 22:16
Сообщение
#1
|
Новичок Группа: Новичок Сообщений: 7 Регистрация: 13.6.2010 Пользователь №: 1804 Спасибо сказали: 0 раз(а) Репутация: 0 |
Всем здравствуйте. Я в QT третий день, как бы это смешно не звучало.. Моя задача - научиться делать в ней доку. Есть набор html-файлов, хочу их отобразить с помощью QT Assistant'a...
Но как то сделать, не соображу совсем. Перечитала кучу материалов в нете. Прочитала пример про SimpleTextViewer. Но не поняла ничего Не пойму, где что писать, где какие xml-ки формировать, куда что загонять для генерации.. как получить qch-файлы... Подскажите что-нибудь.. Пожааалуйста... |
|
|
kibsoft |
13.6.2010, 22:23
Сообщение
#2
|
Участник Группа: Участник Сообщений: 180 Регистрация: 21.7.2009 Из: Самара Пользователь №: 928 Спасибо сказали: 14 раз(а) Репутация: 2 |
Using Qt Assistant as a Custom Help Viewer и The Qt Help Framework почитайте в ассистенте.
Цитата Generating Qt Help
Building help files for the Qt help system assumes that the html documentation files already exist, i.e. the Qt help system does not offer the possibility to create html files like e.g. Doxygen. Once the html documentents are in place, a Qt Help Project file has to be created. After specifying all relevant information in this file, it needs to be compiled by calling: qhelpgenerator doc.qhp -o doc.qch The file 'doc.qch' contains then all html files in compressed form along with the table of contents and index keywords. To test if the generated file is correct, open Qt Assistant and install the file via the Settings|Documentation page. |
|
|
alex977 |
13.6.2010, 23:00
Сообщение
#3
|
Активный участник Группа: Участник Сообщений: 310 Регистрация: 19.6.2008 Из: Россия, МО, г.Мытищи Пользователь №: 206 Спасибо сказали: 77 раз(а) Репутация: 8 |
Перевод примера "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 |
|
|
Litkevich Yuriy |
14.6.2010, 3:46
Сообщение
#4
|
||
разработчик РЭА Группа: Сомодератор Сообщений: 9669 Регистрация: 9.1.2008 Из: Тюмень Пользователь №: 64 Спасибо сказали: 807 раз(а) Репутация: 94 |
как получить qch-файлы Это очень просто. Вот реальный пример файла проекта справки (qhp), для самого асиситента:assistant.qhp
Чтобы получить сжатые файлы справки нужно просто скомандовать:
Про содержимое qhp: namespace - должно быть уникальным, это начало адреса, например, для файла assistant-manual.html, в адресной строке асиситента будет выглядеть так: toc - оглавление, то что будет в нём отображаться keywords - предметный указатель (или просто указатель), то что будет в нём отображаться files - список файлов, которые должны быть помещены в сжатый файл справки ----- customFilter - создаёт новый фильтр, который можно выбрать в панели фильтра асиситента: filterSection - секция описывающая содержимое фильтра. Здесь речь идёт о неком уже существующем фильтре и выбирается он комбинацией атрибутов. Например, в assistant.qhp создан фильтр с именем "Qt Assistant Manual", а в своём файле вы можете просто перечислить в секции filterSection, его атрибуты. При этом не создавая нового фильтра. Тогда при выборе фильтра "Qt Assistant Manual" будет доступна документация по Асистенту и ваша. Под доступностью понимается: наличие соответствующих пунктов в Оглавлении, Указателе и при полнотекстовом поиске. |
||
|
|||
Shpiron |
14.6.2010, 10:14
Сообщение
#5
|
Новичок Группа: Новичок Сообщений: 7 Регистрация: 13.6.2010 Пользователь №: 1804 Спасибо сказали: 0 раз(а) Репутация: 0 |
Всем спасибо, начинаю что-то понимать потихоньку...
Вопроса два: 1. для того, чтобы...., нужно просто написать qhelpgenerator.exe assistant.qhp -o assistant.qch У меня это получается непросто.. Так как файлы помощи и генератор.exe лежат в абсол.тно разных местах.. Это нормально? То есть, чтоб это выполнить, мне нужно для каждого файла указать полный путь... 2. Сгенерить двоичный файл из файла коллекции .qhcp - это последний этап сборки помощи. Что после этого должно выйти? Простите за неграмотность, но в итоге ведь должен выйти какой-то exe-шник, который я запускаю и открывается окно помощи.. нет? |
|
|
Litkevich Yuriy |
14.6.2010, 10:33
Сообщение
#6
|
разработчик РЭА Группа: Сомодератор Сообщений: 9669 Регистрация: 9.1.2008 Из: Тюмень Пользователь №: 64 Спасибо сказали: 807 раз(а) Репутация: 94 |
То есть, чтоб это выполнить, мне нужно для каждого файла указать полный путь... конечно, но путь может быть и относительным. (относительно того каталога в котором выполняется команда)ведь должен выйти какой-то exe-шник, который я запускаю и открывается окно помощи.. нет? нет. Эти файлы нужно будет добавить в асистент. (см. справку)Вот почитайка команды Qt RTT для добавления перевода документации к имеющейся: Раскрывающийся текст === Руководство по установке документации Qt версии 4.5. === Переместите файлы *.qch в каталог %QTDIR%\doc\qch ==== Добавление документации в Qt Assistant ==== 1) Запускаем Qt Assistant 2) Меню "Правка" -> "Настройки" -> вкладка "Документация" 3) Нажимаем кнопку "Добавить" 4) В появившемся диалоге выбираем эти qch-файлы, и нажимаем кнопку диалога "Открыть" (в списке документации должны появится строчки c префиксом: ru.trolltech.* ) 5) Нажимаем "Ок" и ждем завершения индексации. (В боковой панели "Оглавление (Contents)" должны появится пункты с русским названием, типа "Руководство по ...") 6) Щелкаем правой кнопкой мышки по панели инструментов и включаем пенель фильтра. 7) Можете выбрать фильтр "Qt 4.5.2 - RU", тогда англоязычная документация скроется (и не будет учавствовать в поиске) Замечание: Чтобы быстро переключится с одного языка на другой, достаточно в строке адреса исправить префикс "ru" на "en" или наоборот. |
|
|
Shpiron |
14.6.2010, 20:06
Сообщение
#7
|
Новичок Группа: Новичок Сообщений: 7 Регистрация: 13.6.2010 Пользователь №: 1804 Спасибо сказали: 0 раз(а) Репутация: 0 |
Всем спасибо огромное, у меня даже что-то получилось..
Появился еще вопросик: когда меняется html-файл, что нужно сделать, чтобы исправленная версия отобразилась? Перерегистрировать? или может вообще ничего не нужно, я зря парюсь? |
|
|
Kagami |
14.6.2010, 22:42
Сообщение
#8
|
Старейший участник Группа: Участник Сообщений: 601 Регистрация: 2.2.2009 Пользователь №: 523 Спасибо сказали: 101 раз(а) Репутация: 9 |
Если какой-либо файл .html изменился, то надо пересоздать файл .qch.
Сообщение отредактировал Kagami - 14.6.2010, 22:45 |
|
|
Shpiron |
15.6.2010, 9:33
Сообщение
#9
|
Новичок Группа: Новичок Сообщений: 7 Регистрация: 13.6.2010 Пользователь №: 1804 Спасибо сказали: 0 раз(а) Репутация: 0 |
У меня получилось отобразить желаемую структуру.. Слева отображается дерево, раскрываются списки, а вот справа ничего не отображается
вообще пусто... что я не так делаю? |
|
|
Litkevich Yuriy |
15.6.2010, 13:37
Сообщение
#10
|
разработчик РЭА Группа: Сомодератор Сообщений: 9669 Регистрация: 9.1.2008 Из: Тюмень Пользователь №: 64 Спасибо сказали: 807 раз(а) Репутация: 94 |
Shpiron, ты экспериментируешь прямо с асиситентом?
|
|
|
Текстовая версия | Сейчас: 25.12.2024, 8:05 |