Пишемо простий хелп, Різне, Програмування, статті

Автор: Сергій Осколков, Королівство Delphi






Введення 


Довідкова система (далі в тексті також – “довідка”) – важлива складова частина будь-який більш-менш складною (і навіть простий) програми. Існують різні формати довідкових систем. Довідка у форматі WinHelp – Про неї в статті і піде мова, Html-help – як, наприклад, довідка до ОС Windows або до програм MS Office. В якості довідки може виступати набір пов’язаних html-файлів, наприклад так організована довідка до СУБД MySQL. З переваг WinHelp можна назвати її надійність і менші, ніж у HTML-help, вимоги до ресурсів. Існують різні програми для створення довідкових систем названих типів. Однак, для створення нескладної довідки цілком достатньо стандартної програми MS Help Workshop, яка поставляється з Delphi. Буде потрібно ще редактор rtf файлів, в даній статті описується робота зі знайомим всім MS Word “ом. Всі дії, які будуть описані – нескладні, але мені свого часу було потрібно певну кількість зусиль і часу, щоб розібратися по довідці до Help Workshop, як все це робити. Сподіваюся, що стаття зможе полегшити цей шлях для інших. Розрахована вона на початківців. У статті описується створення простої довідки, змісту до неї, створення послідовностей перегляду, вставка малюнків і гіперпосилань, а також підключення довідки до програми. Розглядається тільки технічна сторона, питання про те, що написано в довідці, залишений осторонь.
 






Загальні відомості 


До складу операційної системи Windows входить підсистема підтримки довідки – WinHelp. Вона має своє API, який дозволяє надати довідкову інформацію в тому чи іншому вигляді в додатках Windows. Створення довідкової системи можна розділити на дві частини



До складу довідки до програми зазвичай входить декілька файлів:







Створення тематичних файлів. 


Для створення довідки спочатку потрібно підготувати файли, що містять довідкову інформацію. Це – звичайні документи в форматі rtf, які можна створювати за допомогою різних програм. Я тут буду описувати роботу з MS Word (створюємо документ і вибираємо “Зберегти як” – “Текст у форматі RTF”). Будемо називати ці файли тематичними (topic files). Для отримання з тематичних файлів готових файлів довідки (Hlp), їх потрібно обробити (компілювати) програмою HelpWorkshop (hwc.exe). Крім власне тексту і малюнків, тематичні файли можуть містити також спеціальну розмітку, яка несе в собі інформацію, потрібну для створення переходів за посиланнями, зв’язку змісту довідки з її темами і т.п. – Для реалізації різних можливостей WinHelp.


Зазвичай довідка містить декілька тем і зміст, з якого можна перейти до цих тем. Найпростіший варіант: якщо тема – одна і змісту немає. В такому випадку просто пишемо те, що потрібно і зберігаємо це у файлі з розширенням “. rtf”. Для створення кількох тем процес ускладнюється ненабагато:



Для того, щоб тема були доступна зі змісту до довідки, потрібно задати їй ідентифікатор. Для цього потрібно в те місце тексту, куди буде згодом відбуватиметься перехід зі змісту (початок теми або, якщо потрібно, інше місце), вставити спеціальну розмітку, а саме: кінцеву виноску. Символом виноски потрібно вибрати “#”. Ідентифікатором теми служить текст виноски. Наприклад, створимо тему “Підтримка”, відокремимо її від інших тим розривами сторінок і задамо їй ідентифікатор “support”. Для цього помістимо каретку введення близько заголовка теми і виберемо в меню “Вставка” -> “Виноска …”. У діалоговому вікні (мал.1) обираємо вид виноски – “кінцева”, нумерація – “інша”, у віконці для введення символу пишемо “#” (без лапок, ясна річ). Натискаємо ОК, посилання додана і каретка автоматично переведена до тексту посилання. Пишемо “support”. Готово.
Повторюємо те ж саме для всіх тем довідки. Зберігаємо файл. Тепер можна спробувати створити свій хелп.

Рис.1. Додавання кінцевої виноски.


Запускаємо програму HelpWorkshop. Це – файл Hcw.exe в директорії DelphiHelpTools. Створюємо новий проект через меню “File” -> “New” -> “Help Project”. Праворуч на панелі є ряд кнопок, натискаємо “Files …”. У діалоговому вікні додаємо наш тематичний файл і закриваємо це вікно. Збережемо проект – це буде файл з розширенням hpj (Help Project). Наскільки я зрозумів, після першого запуску Help Workshop пов’язує себе з файлами hpj, а також – з файлами змісту довідки (cnt), так що їх потім можна відкривати подвійним клацанням мишею. Для створення help-файлу можна просто натиснути кнопку “Save and Compile”. Відкриється нове вікно з повідомленням про результат компіляції. Припустимо, що все в порядку, закриємо це вікно. Тепер в директорії, де перебував наш проект (. Hpj), повинен з’явитися файл довідки. Однак, при подвійному клацанні мишею на ньому ми зможемо переглянути лише першу тему. Щоб переглядати всі теми і переміщатися між ними, потрібно додати файл змісту.






Створення змісту довідки. 


Файл змісту довідки має простий текстовий формат, але створювати його зручно теж в HelpWorkshop. Для цього вибираємо в меню HelpWorkshop “File” -> “New” -> “Help Contents”. У верхній частині вікна потрібно вписати ім’я головного файлу довідки (файлів, взагалі кажучи, може бути кілька) і заголовок (title) для змісту довідки. Те ж можна зробити в діалоговому вікні, яке відкривається при натисканні кнопки Edit … .


Тепер створюємо власне зміст. Воно складається з елементів двох типів – розділи довідки, які включають в себе декілька тем і представлені у змісті довідки значком книжки і самі теми – текст і картинки, представлені у змісті довідки значком аркуша зі знаком питання на ньому (можна подивитися це в змісті будь довідки). Також до змісту можна вставити макроси і включити файли (include), цього я тут торкатися не буду. Праворуч на панелі є набір кнопок для додавання і маніпуляції елементами змісту. (Add Below – Додати нижче, Add Above – Додати вище, Move Right – Зрушити вправо, Move Left – Перемістити ліворуч, Edit, Delete). За допомогою них створюємо потрібну структуру змісту. При додаванні розділу в діалоговому вікні потрібно вказати тільки його назву, при додаванні теми – назва, ідентифікатор (той, який ми поставили їй в rtf-файл, коли вставляли кінцеву виноску), ім’я help-файлу та ім’я вікна. Якщо тема знаходиться в тому ж help-файлі, який ми вказали як головний, то ім’я help-файлу вказувати не потрібно. Ім’я вікна вказувати теж не обов’язково, якщо воно не зазначено, то тема відкриється у вікні по-замовчуванню. Потрібно зберегти файл змісту (він буде мати розширення. Cnt) в тій же директорії, де знаходиться help-файл краще з тим же ім’ям, що й help-файл. Тепер потрібно знову відкрити файл проекту. Hpj і, натиснувши кнопку “Options”, в діалоговому вікні на закладці “Files” вказати наш файл змісту (Contents file). Закриваємо діалогове вікно, знову натискаємо “Save and Compile”. Тепер при подвійному натисканні мишею по значку файлу довідки має відкритися її зміст, з якого можна отримати доступ до всіх тем.


Мені не вдалося, схоже, це неможливо, створити таку структуру змісту, щоб в самому лівому ряду спочатку йшов значок теми (наприклад, “Загальні відомості”), а під ним – значки розділів. Довелося навіть для одиночної теми створювати розділ, що містить її одну.






Створення послідовностей перегляду. 


Зручно переміщатися в довідці від теми до теми за допомогою кнопок “>>” і “<<" на панелі інструментів вікна або за допомогою клавіш "<", ">” клавіатури. Щоб додати таку можливість, потрібно:


  1. Створити одну або кілька послідовностей перегляду (browse sequence) в. Rtf файлі тексту довідки, додавши відповідну розмітку.
  2. Визначити в проекті довідки (файл. Hpj) вікно з відповідними кнопками.

Розмітка має наступний вигляд: це теж кінцеві виноски, як і для ідентифікаторів тим, однак в даному випадку знаком виноски служить не символ “#”, а “+” – знак плюса. Текстом виносок може бути або число, або рядок символів. Перегляд буде здійснюватися в порядку зростання (як при сортуванні рядків). Звідси наступне – якщо використовуються номери, то потрібно вставляти необхідну кількість нулів перед значущими цифрами для правильної сортування. Наприклад, якщо у Вас 20 тем, то перші треба нумерувати як 01, 02, і т.д. Можливо кілька варіантів:



Щоб додати кнопки навігації “<<" і ">>” у вікні довідки (за умовчанням їх немає), потрібно визначити хоча б одне вікно. Для цього, відкривши файл проекту в HelpWorkshop, потрібно натиснути кнопку “Windows …” в правій частині вікна. У діалоговому вікні із закладками натиснути кнопку “Add …” і у вікні, ввести в полі назви “main”, а поле типу вікна очистити, після чого натиснути OK. Тепер у нас визначено одне вікно, різні властивості якого можна змінювати, переміщаючись по закладках. На закладці “Buttons” відзначаємо галочкою “Browse”. Натискаємо ОК, готово. Тепер вікно довідки матиме потрібні кнопки. Натискаємо “Save and Compile” внизу вікна і можемо перевіряти, що вийшло у вихідному help файлі.






Додавання картинок і гіперпосилань. 


Буває, що в довідку потрібно помістити зображення. Це можна зробити, просто додавши їх у документ rtf звичайним для MS Word способом. Якщо одне зображення використовується в декількох місцях, то можна скористатися спеціальною розміткою, передбаченої для вставки зображень в довідку, так що зображення буде зберігатися в одному екземплярі. Тут я не буду розглядати, як це зробити (чесно кажучи, я цього ніколи і не робив).

Звичайна справа – вказати адресу свого сайту і / або електронної пошти в розділі “Підтримка”. Як зробити, щоб це посилання виглядала і функціонувала як гіперпосилання на Веб-сторінках? Аналог гіперпосилання, тобто тега anchor () HTML в WinHelp – “hotspot”. Hotspot – це область, по клацанню миші на якій, виконується будь-яку дію з передбачених у WinHelp. В даному випадку нам потрібно запустити один з макросів WinHelp, а саме макрос ExecFile. Цей макрос нагадує функцію WinApi ShellExecute. Синтаксис його такий:

ExecFile(program[, arguments[, display-state[, topic-ID]]])

Перший параметр, як написано в довідці, може вказувати на програму або файл. Однак, як і в ShellExecute, замість імені файлу можна вказати URL, наприклад “http://www.mysite.ru” або “mailto: nekto@somemail.ru”.
Щоб створити hotspot, що запускає такий макрос, потрібно зробити наступне:
Відразу після тексту hotspot “a ввести символ”! “, А відразу за ним – текст макросу, наприклад:

Наш сайт: www.mysite.ru!ExecFile (http://www.mysite.ru)

Примітка: URL в дужках повинен бути без лапок.
Далі, потрібно відформатувати цей уривок так: текст hotspot “a повинен мати подвійне підкреслення, а символ”! “І текст макросу після нього – мати атрибут” прихований “. І те, і інше робиться через меню” Формат ” -> “Шрифт” (див. рис. 2) На всякий випадок, ще раз уточню: подвійне підкреслення (випадаючий список поряд з “кольором тексту”), а не закреслення ..

Рис. 2.

Тепер, якщо додати такий hotspot і компілювати проект, то ми побачимо в своїй довідці, що в рядку тексту


Наш сайт: www.mysite.ru – адреса виглядає і функціонує як гіперпосилання.






Приєднуємо довідку до програми. 


Щоб довідка була доступна в програмі, потрібно вказати програмі на файл. Hlp. Найпростіший спосіб розміщення файлу довідки – в тій же папці, де знаходиться виконуваний файл. Визначити для програми файл довідки можна так: відкривши проект (додатки) в Delphi і вибравши меню “Project” -> “Options” -> “Application”, вписати назву файлу довідки в поле введення “Help file”. При цьому потрібно вказати назва файлу без шляху. Коли WinHelp намагається знайти довідковий файл, одна з переглядаються директорій – та, де розташований виконуваний файл програми. Інший спосіб – в обробник події OnCreate головної форми програми вставити рядок:

Application.HelpFile:=ExtractFilePath(Application.ExeName) + “MyHelp.hlp”;

де MyHelp.hlp – назва файлу довідки.

Щоб з меню в програмі викликати зміст довідки, потрібно скористатися функцією

  Application.HelpCommand(HELP_FINDER, 0);

Щоб перейти до однієї з визначених нами тем довідки, потрібно викликати функцію

Application.HelpJump(“MyTopic”),

де MyTopic – ідентифікатор теми.

Один із способів виклику довідки – натискання клавіші F1. Можна організувати виклик контекстної довідки при натисканні на F1, коли активним є той чи інший елемент керування. Для цього відповідної темі довідки потрібно присвоїти номер, а потім цей номер привласнити властивості HelpContext елемента управління. Щоб задати номери для тем довідки, потрібно відкрити проект довідки в HelpWorkshop і натиснути кнопку “Map” в правій частині вікна. Натискаємо в діалоговому вікні “Add”, вводимо ідентифікатор теми і довільний номер (наприклад, 1 :)), повторюємо це для всіх потрібних тем (кожної – свій номер), закриваємо вікно і натискаємо в черговий раз “Save and Compile”. Потім в Delphi, у вікні інспектора об’єктів, присвоюємо потрібні номери потрібних елементів управління (нагадую, властивість HelpContext).

Схожі статті:


Сподобалася стаття? Ви можете залишити відгук або підписатися на RSS , щоб автоматично отримувати інформацію про нові статтях.

Коментарів поки що немає.

Ваш отзыв

Поділ на параграфи відбувається автоматично, адреса електронної пошти ніколи не буде опублікований, допустимий HTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

*

*