Як використовувати довідку в програмах Delphi, Різне, Програмування, статті

Як використовувати довідку в програмах Delphi


Зміст:
    1. Як Delphi програми працюють з файлами довідки.
    2. Практика: вказуємо файл довідки.
    3. Підтримка довідки в Delphi програмах.
    4. Практика: простий виклик статичної довідки.
    5. Практика: динамічний виклик контекстно-залежної довідки.
    6. Огляд поширених форматів файлів довідок.
    7. Підтримка форматів довідки в Delphi.
    8.Висновок



      Як Delphi програми працюють з файлами довідки


      Перш ніж ваша Delphi програма зможе показувати довідку – ви повинні сказати вашому додатком (тобто програму), що вона (довідка) у вас взагалі є. Робиться це установкою властивості HelpFile в об'єкта Application або форми.

      У кожному VCL додатку Delphi є глобальний об'єкт Application ("Додаток") типу TApplication. У цього об'єкта є властивості і методи, що впливають на весь додаток цілком. І для активації довідки у нього є властивість Application.HelpFile.

      Коли цій властивості присвоєно значення, ви можете використовувати методи і властивості об'єкта Application і ваших форм (вікон), щоб працювати з вашою довідкою. Значенням властивості є ім'я файлу довідки вашої програми. Формат довідки може бути будь-яким із підтримуваних вашим додатком (про це трохи пізніше). Зараз тільки зазначимо, що різні формати файлів довідок мають різні можливості (і зовнішній вигляд!). Відрізняється також і підтримка цих форматів в самій Delphi. Тому, чи працюватиме та чи інша можливість, обговорювана нижче – залежатиме від того, який формат файлу довідки ви оберете. Але, знову-таки, про це пізніше.

      Отже, крім об'єкта Application, Властивість HelpFile є й у об'єктів класу TForm. Коли додатком надходить команда по роботі з довідковою системою (наприклад, користувач натиснув F1), То Delphi додаток буде використовувати файл довідки, зазначений у Application.HelpFile для виконання цієї команди. Але якщо при цьому активна форма, у якій задане її властивість HelpFile, То для виконання команди буде використовувати властивість форми, а не програми.

      Іншими словами, Form.HelpFile просто змінює Application.HelpFile в контексті однієї конкретної форми. Якщо у вашій програмі є лише один файл довідки, то ви не повинні встановлювати властивості HelpFile у форм, а встановити властивість HelpFile в об'єкта Application.


      Практика: вказуємо файл довідки


      Ви можете встановити властивість HelpFile програмно (кодом) або вказати у властивостях проекту.

      Програмно: Project / View Source






      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16

      program Project1;
        
      uses
        Forms,
        SysUtils, // <- Добавлено
        Unit1 in Unit1.pas {Form1};
        
      {$R *.res}
        
      begin
        Application.Initialize;
        Application.MainFormOnTaskbar := True;
        Application.HelpFile := ExtractFilePath(Application.ExeName) + HelpHelpFile.hlp; // <- Добавлено
        Application.CreateForm(TForm1, Form1);
        Application.Run;
      end.


      У цьому прикладі файл довідки повинен називатися HelpFile.hlpі лежати в папці Help вашої програми. Зрозуміло, ви повинні замінити цей рядок своїми даними.

      Через GUI: Project / Options / Application:




      Тут є цілих три проблеми:


      1. Натискання на кнопку "Browse" покаже вам тільки *. hlp файли. Щоб вибрати файл іншого формату, вам потрібно вибрати у фільтрі діалогу відкриття опцію "All Files (*.*)".

      2. Вибір файлу довідки кнопкою "Browse" занесе в поле повний шлях до файлу виду C: UsersАлександрDocumentsRAD StudioProjectsDemoProjectHelpHelpFile.hlp – Це не дуже вдала ідея, адже на машині, куди ваша програма буде потім встановлена, цей файл буде лежати в зовсім іншому місці. Краща ідея – обрізати шлях до відносного: .HelpHelpFile.hlp.

      3. Проблема з попереднім пунктом в тому, що відносний шлях вважається відносно поточного каталогу. Що звичайно дорівнює папці вашої програми, але далеко не завжди. Кращим рішенням буде виправити цей момент так:






      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16

      program Project1;
        
      uses
        Forms,
        SysUtils, // <- Добавлено
        Unit1 in Unit1.pas {Form1};
        
      {$R *.res}
        
      begin
        Application.Initialize;
        Application.MainFormOnTaskbar := True;
        Application.HelpFile := ExtractFilePath(Application.ExeName) + Application.HelpFile; // <- Добавлено
        Application.CreateForm(TForm1, Form1);
        Application.Run;
      end.


      Що дає вам 100% гарантію роботи, але … чи не простіше просто використовувати програмну установку шляху спочатку, не чіпаючи GUI?


      Що стосується індивідуальних файлів довідок для форм – то до них застосовуються ті ж слова: ви можете виставляти властивості програмно:






      1
      2
      3
      4

      procedure TForm1.FormCreate(Sender: TObject);
      begin
        HelpFile := ExtractFilePath(Application.ExeName) + HelpMainForm.hlp;
      end;


      або через інспектор об'єктів:



      І знову: проблеми з відносними / повними шляхами ведуть до того, що перший спосіб з програмною установкою виглядає набагато привабливіше.


      Підтримка довідки в Delphi програмах


      Як тільки Delphi додаток дізнається, що у нього є файл довідки, воно дасть вам сім стандартних способів показати довідку:

      Натискання F1
      Ця функція реалізує контексту довідку. Коли користувач натискає F1, Додаток шукає в файлі довідці тему (topic) з номером контексту (context number) або ключовим словом (keyword), заданими у властивостях компонента, що має фокус. Якщо знайдена одна або декілька тем – то відкривається файл довідки, показуючи ці теми в окремому вікні.
       


      Кнопка з питаннячко в заголовку вікна



      Ця кнопка активує контекстно-залежний режим довідки на формі – так звана функція "Whats this?" ("Що це таке?"). Коли користувач натискає на цю кнопку, форма тимчасово відключається, а курсор змінює форму на стрілочку з питаннячко:



      Натискання на будь-який елемент управління в цьому режимі змусить додаток виконати пошук теми у файлі довідки, асоційованої з цим компонентом. Якщо тема знайдена, то вона буде показана у спливаючому віконці.


      Зазвичай цей спосіб не використовується в сучасних програмах. Історично він з'явився в 16 розрядних Windows, коли ще не було спливаючих підказок. Сьогодні ж замість цього функціонала набагато простіше використовувати звичайна властивість Hint.
       


      Кнопка "Довідка" з Kind = bkHelp




      Це простий спосіб викликати довідку, не створюючи жодного рядка коду. Натискання на кнопку відкриє тему з номером контексту або ключовим словом, заданими у властивостях або самої кнопки, або (зазвичай) форми.
       


      Application.HelpCommand
      Це гнучкий метод, який дозволяє вам виконати будь-яку команду з вашим файлом довідки. Детальніше ця команда розглянута нижче.
       


      Application.HelpJump
      Це допоміжна функція, яка є обгорткою до Application.HelpCommand з командою "jump". Вона дозволяє вам відобразити тему довідки по її ID (імені).
       


      Application.HelpContext
      Це допоміжна функція, яка є обгорткою до Application.HelpCommand. Вона дозволяє вам показати тему по так званому номером контексту (context number).
       


      Application.HelpKeyword
      Це допоміжна функція, яка є обгорткою до Application.HelpCommand. Вона дозволяє вам показати тему по ключовому слову (keyword).
       


      Опції 1, 2 і 3 працюють автоматично. Вам не потрібно нічого робити, окрім як прив'язати теми довідки до компонентів (через номера контекстів або за ключовими словами).


      Практика: простий виклик довідки


      Розберемо найпростіші методи роботи з довідкою – показ фіксованих вікон і тим без урахування контексту, використовуючи останні чотири методи зі списку в попередньому пункті.

      Кожне серйозне Windows додаток має пункт меню "Довідка" на зразок такого:




      Або хоча б такого:




      Коли ви натискаєте на подібні пункти меню – з'являється вікно, зване (в термінах Microsoft) "Finder". Воно виглядає якось так:




      Або так (в цьому випадку вікно Finder включає в себе і вікно з темою):




      Або так:





      Як відкрити довідку


      Отже, як вам відкрити вікно Finder? Насправді, це дуже просто: помістіть цей код в обробник натискання пункту меню:






      1
      2
      3
      4

      procedure TForm1.miHelpContentsClick(Sender: TObject);
      begin
        Application.HelpCommand(HELP_FINDER, 0);
      end;


      Цей код покаже вікно Finder на тій вкладці, яка була відкрита в останній раз.


      Як відкрити зміст довідки


      Зміст (Table Of Contents) – це перша вкладка вікна Finder. Це так само просто, як відкрити вікно Finder, але команда буде виглядати так:






      1
      2
      3
      4

      procedure TForm1.miHelpContentsClick(Sender: TObject);
      begin
        Application.HelpCommand(HELP_TAB, 0);
      end;


      Примітка: у деяких версіях Delphi константа HELP_TAB не визначена. У цьому випадку додайте в відповідне місце програми це визначення:






      1
      2

      const
        HELP_TAB = 15;




      Як відкрити тему по-замовчуванню


      Тема за замовчуванням – це тема, яка була вказана як тема за замовчуванням у налаштуваннях файлу довідки. Якщо такої не вказано, то темою за замовчуванням вважається перша тема в змісті. Команда для відкриття теми за замовчуванням виглядає так:






      1
      2
      3
      4

      procedure TForm1.miHelpDefaultClick(Sender: TObject);
      begin
        Application.HelpCommand(HELP_CONTENTS, 0);
      end;


      Історична довідка
      Що відбувається, коли ви відкриваєте старий файл довідки з 16 бітних Windows? Відкривається вікно, що показує тему. Ця тема називається темою за замовчуванням (default topic).
       
      32 бітний файл довідки формату WinHelp складається з двох файлів (16 бітний – з одного):. HLP, який містить теми і зміст -. CNT. Якщо ви вилучили. CNT файл і відкриєте. HLP файл, то побачите тему по замовчуванням.
       
      У минулому столітті, коли Windows 3.x ще була передовими технологіями, тема за замовчуванням була єдиним способом показати якийсь огляд (зміст). Ця тема зазвичай була першою темою у файлі довідки та містила посилання на інші теми. Ось чому Microsoft називала її "CONTENTS" (Зміст). Якщо ця тема явно не задана, то темою за замовчуванням вважається перша тема у файлі довідки.
       
      Ось чому команда






      1

      Application.HelpCommand(HELP_CONTENTS, 0);

      НЕ покаже вам зміст, незважаючи на назву "CONTENTS". Це команда для відкриття теми за замовчуванням.


      Як відкрити індекс довідки


      Вкладка індекс (Index) показує алфавітний список ключових слів (keyword). Ключові слова повинні бути задані у властивостях тем. Якщо ключові слова взагалі не визначені – ця вкладка не показується.

      Наступний приклад показує, як можна відкрити довідку на вкладці індексу:






      1
      2
      3
      4
      5
      6
      7
      8

      procedure TForm1.ShowKeywordIndex;
      var
        Command: array[0..255] of Char; // примечание: этот код также работает с D2009+
      begin
        Command := SEARCH();
        Application.HelpCommand(HELP_FORCEFILE, 0);
        Application.HelpCommand(HELP_COMMAND, Longint(@Command));
      end;




      Як відкрити пошук по довідці


      Вкладка пошуку (Find) показує діалог повнотекстового пошуку по довідці. Якщо у файлі довідки відключені можливості повнотекстового пошуку, то ця вкладка взагалі не показується.

      Наступний приклад відкриває вікно довідки з активним вікном пошуку:






      1
      2
      3
      4
      5
      6
      7
      8

      procedure TForm1.ShowFullTextSearch;
      var
        Command: array[0..255] of Char; // примечание: этот код также работает с D2009+
      begin
        Command := FIND();
        Application.HelpCommand(HELP_FORCEFILE, 0);
        Application.HelpCommand(HELP_COMMAND, Longint(@command));
      end;




      Як відкрити тему по імені


      Для показу теми по імені ви можете використовувати метод Application.HelpJump, Який приймає один строковий параметр – ID (ім'я) теми. Наприклад:






      1
      2
      3
      4

      procedure TForm1.ShowTopicByName;
      begin
        Application.HelpJump(mytopic);
      end;


      Цей метод повертає True, Якщо тема існує і була знайдена, і False – В іншому випадку. Проте, в останньому випадку також автоматично показується повідомлення користувача про те, що тема не існує.
      Якщо у вашій Delphi команди HelpJump ні, то ось її код:






      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11

       
      function TForm1.HelpJump(const JumpID: string): Boolean;
      var
        Command: array[0..255] of Char;
      begin
        Result := True;
        if InvokeHelp(HELP_CONTENTS, 0) then
        begin
          StrLFmt(Command, SizeOf(Command) – 1, JumpID(“”,”%s”), [JumpID]);
          Result := Application.HelpCommand(HELP_COMMAND, Longint(@Command));
        end;
      end;

      Як відкрити тему за номером контексту
       
      А для показу теми по контекстного номером ви можете використовувати метод Application.HelpContext, Який приймає один числовий параметр – номер контексту. Наприклад:






      1
      2
      3
      4

      procedure TForm1.ShowTopicByNumber;
      begin
        Application.HelpContext(2);
      end;


      Аналогічно, цей метод повертає True, Якщо тема існує і була знайдена, і False – В іншому випадку.
       
      Якщо у вашій Delphi команди HelpContext ні, то ось її код:






      1
      2
      3
      4

      function TForm1.HelpContext(const AContext: Integer): Boolean;
      begin
        Result := Application.HelpCommand(HELP_CONTEXT, AContext);
      end;

      Зазвичай ви не викликаєте цю команду вручну – адже ви може просто асоціювати компонент з темою, використовуючи властивості (про це – нижче).

      Ця команда покаже тему в окремому вікні. Якщо ви хочете використовувати спливаюче вікно – використовуйте іншу команду:






      1
      2
      3
      4

      procedure TForm1.ShowTopicByNumberInPopup;
      begin
        Application.HelpCommand(HELP_CONTEXTPOPUP, 2);
      end;




      Як відкрити тему за ключовим словом


      Чи цікавилися ви коли-небудь, як працює довідка середовища Delphi? Коли ви виділяєте властивість компонента в інспектора об'єктів або встановлюєте на нього курсор в коді і натискаєте F1, То ви отримуєте опис цієї властивості.

      Це працює за допомогою ключових слів. Коли ви натискаєте F1, У довідці шукаються теми з ключовим словом, яке зазначено під курсором або в інспекторі об'єктів. Для цього файл довідки повинен містити список ключових слів, асоційованих з темами. Ви задаєте це при створенні файлу довідки (вказуючи ключові слова у властивостях теми).

      Для показу теми за ключовим словом використовується метод Application.HelpKeyword, Який приймає один строковий параметр – ключове слово. Наприклад:






      1
      2
      3
      4

      procedure TForm1.ShowTopicByKeyword;
      begin
        Application.HelpKeyword(example);
      end;

      Якщо у вашій Delphi команди HelpContext ні, то ось її код:






      1
      2
      3
      4
      5
      6
      7

      function TForm1.HelpKeyword(const AKeyword: String): Boolean;
      var
        Command: array[0..255] of Char;
      begin
        StrLcopy(Command, PChar(AKeyword), SizeOf(Command) – 1);
        Result := Application.HelpCommand(HELP_KEY, Integer(@Command));
      end;

      А як тепер закрити довідку
      Немає нічого простішого:






      1
      2
      3
      4

      procedure TForm1.CloseHelp;
      begin
        Application.HelpCommand(HELP_QUIT, 0);
      end;




      Практика: виклик довідки з контекстом


      Контекстна довідка (context sensitive help або contextual help) дає миттєву підтримку користувачам, не примушуючи їх покидати контекст, в якому вони працюють. Вона показує інформацію про конкретний об'єкті, з яким працює користувач. Зазвичай вона відповідає на питання на зразок "Що це таке?", "Навіщо це використовувати?" і "Що і як з цим робити?". Вона дуже корисна саме тим, що користувач не відключається від процесу роботи. Основні способи для контекстної довідки включають в себе:

      • Контекстні теми у файлі довідки

      • Кнопки виклику довідки (наприклад, кнопка Help поруч з OK і Cancel в діалогах)

      • Підказки (показуються при наведенні миші на об'єкт)

      • Повідомлення в рядку статусу (StatusBar)

      Коли я говорю про контекстну довідку в цьому пості, я в маю на увазі перші два пункти. Другі два пункти в цій статті не розглядаються. Другий пункт реалізується або ручним викликом довідки одним з методів, які ми розглянули вище, або призначенням кнопки виду (Kind) bkHelp (Обробник при цьому реалізовувати не потрібно).

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


      Як включається контекстна довідка


      Контекстна довідка зазвичай викликається одним з трьох основних способів:

      Натискання F1, Коли фокус уведення знаходиться на якомусь елементі управління. Це основний спосіб показу контекстної довідки. Коли користувач застряє, він натискає F1, а програма показує йому тему довідки, в залежності від того, де він знаходиться. Цей спосіб підтримується Delphi і вам не потрібно писати для нього код.
      Функція "Whats this?". Це або кнопка з питаннячко в заголовку вікна, або аналогічна кнопка з питаннячко на панелі інструментів (Toolbar-е), або пункт меню Довідка/Що це таке?. Як я вже говорив, це старий режим роботи з довідкою. Я не буду його особливо розглядати, тому що в сучасних програмах набагато простіше і зручніше використовувати спливаючі підказки.
      Кнопка з Kind = bkHelpабо аналогічний спосіб. Цей спосіб не можна повністю віднести до контексту довідці – адже коли ви натискаєте на кнопку, то фокус йде з поточного елемента керування. Тим не менш, я перераховую цей спосіб, як ще один варіант автоматичного виклику довідки без написання коду.


      Як реалізується контекстна довідка


      Показ теми в контекстно-залежної довідці вимагає ідентифікації теми по числовому номеру, званому номером контексту (context number). У більш пізніх версіях Delphi також можливий показ контекстів довідки за ключовими словами. За замовчуванням у файлі довідки не задаються ні номера контекстів, ні ключові слова. Ви повинні або вводити їх вручну, або (тільки для номерів контектов) ви можете включити в опціях автоматичну нумерацію (в деяких просунутих редакторах файлів довідок, типу Help & Manual).

      Можливо, ви вже помітили ці властивості в інспекторі об'єктів – це властивість HelpContext і властивість HelpKeyword:




      Властивість HelpType визначає, яке властивість потрібно використовувати для виклику контекстної довідки. Зазвичай використовуються номери контекстів, а не ключові слова – цей варіант є варіантом за умовчанням для властивості HelpType.

      Для роботи контекстної довідки або ці номери (не важливо – створені вами або проставлені автоматично) або ключові слова повинні бути присвоєні темами і встановлені у властивості компонентів на формі. Номери повинні бути унікальні як у файлі довідки, так і в Delphi проекті. Ви можете давати один і той же номер двом і більше компонентами – але це буде означати, що ці компоненти прив'язані до однієї і тієї ж темі. На відміну від номерів контексту, ключові слова не зобов'язані бути унікальними. Якщо з одним ключовим словом пов'язано більш однієї теми, то вам буде показано вікно, з якого ви зможете вибрати потрібну тему.

      Коли користувач викликає контекстну довідку (будь-яким із способів, описаних в попередньому пункті – або через F1, Або через функцію "Whats this?", Або кнопкою «Довідка») – то показується тема довідки, контекстний номер якої зазначений у властивості HelpContext. Або ж, якщо HelpType встановлено в htKeyword, То показується тема (и) з ключовим словом з властивості HelpKeyword. Для роботи контекстної довідки вам не потрібно робити нічого, окрім як проставити номери контекстів темами і компонентів. Всю роботу Delphi зробить автоматично.

      Вам не потрібно проставляти номери контекстів або ключові слова абсолютно всіма компонентами на формі – адже властивості HelpContext і HelpKeyword успадковується. Тобто якщо раптом у компонента потрібне властивість не задано (дорівнює нулю або порожній рядку відповідно), то використовується властивість HelpContext/HelpKeyword його батька (в сенсі Parent). Якщо ж це властивість не задано і у батьків – то перевіряється властивість батька батька. І так далі, аж до форми. Якщо ж властивість не задано і у форми, то контекстна довідка взагалі не викликається. Якщо ви використовуєте кнопку виклику довідки з Kind = bkHelp, То ви зобов'язані присвоїти номер контексту або ключове слово або їй, якій формі.

      Отже, підсумовуючи: щоб у вашій програмі працювала контекстна довідка, вам потрібно:

      Ви повинні вказати додатком, що у вас є файл довідки. Це спільна дія для будь-якого типу довідки в Delphi додатку.


      Ви повинні придумати і присвоїти номери контекстів (Або ключові слова, або і те і інше) темами у вашому файлі довідки. Необов'язково робити це для всіх тем. Якщо ключові слова бажано проставляти взагалі (для роботи індексу), то номери контекстів можна вказувати тільки у тих тем, які повинні бути доступні через контекстну довідку. Ви можете включити автоматичну нумерацію, якщо ваша програма для створення файлів довідок це дозволяє.


      Ви повинні присвоїти контекстні номера (Або ключові слова) формі і компонентів на ній у вашому Delphi додатку, щоб асоціювати елементи керування в додатку з темами довідки. Як мінімум, ви повинні вказати ці номери (ключові слова) для форм.


      Готово. Після цього у вашій програмі працюватиме контекстна довідка. Ви можете відкрити вашу програму і, наприклад, натиснути F1 – Автоматично відкриється тема в довідці, яку ви поставили у властивостях поточного елемента керування.


      Огляд поширених форматів файлів довідок


      На сьогоднішній день існують такі формати довідок (з найпоширеніших):

      16 бітної Windows Help aka WinHelp 1.0 (. HLP) – пропрієтарний формат файлів довідки, розроблений компанією Microsoft для організації довідкової системи. Вихідна інформація готується в форматах RTF (текст) і BMP (зображення), а потім з використанням компілятора генерується бінарний файл з розширенням HLP. Підтримки Unicode немає. Може бути декомпілювати у вихідні файли. Розроблено в 1990 та підтримується в Win16, Win32, WinNT до XP включно. Застарілий в 2006. Обмежено доступний в Windows Vista і Windows 7 (і вище) – підтримка для нього повинна бути встановлена ​​додатково. Сьогодні в здоровому глузді не використовується ніким.
       


      32 бітний Windows Help aka WinHelp 2.0-4.0 (. HLP +. CNT) – поліпшений варіант формату. HLP, що з'явився в Windows 95. Підтримується в Win32/WinNT до Windows XP включно. Підтримки Unicode немає. Застарілий в 2006. Обмежено доступний в Windows Vista і Windows 7 (і вище) – підтримка для нього повинна бути встановлена ​​додатково. Сьогодні в основному використовується старими програмами або тими, кому потрібні спеціальні функції формату WinHelp.
       


      Compiled HTML Help aka HTML Help 1.0-1.4 (. CHM) – основний і самий популярний формат файлів довідок, випущений в 1997 і підтримуваний починаючи з Windows 98 у всіх Windows, включаючи Windows Vista і Windows 7. Являє собою скомпільований файл, отриманий із звичайних HTML-файлів зі спеціальною розміткою. З цієї причини формат став популярним для створення e-books. Може бути декомпілювати у вихідні файли. Однак у цей формат уже не вносяться зміни та нові можливості, а лише усуваються знайдені вразливості. Microsoft планує замінити його на якийсь інший формат у майбутньому. Підтримка Unicode обмежена.
       


      Assistance Platform 1.0 (. H1S) – досить специфічний формат довідки, оскільки використовується тільки для розширення вбудованої довідки самої ОС OEM партнерами. Зрозуміло, що він не призначений для загального використання.
       


      Microsoft Help aka HTML Help 2.0 (. HXS) – формат довідки, використовуваний Visual Studio 2002/2003/2005/2008 і останніми версіями Delphi. Розроблений в 2001. Підтримує Unicode. Стиснутий файл. HxS виходить з набору тим, написаних в HTML (схоже на. CHM). На відміну від усіх інших форматів, цей формат довідки НЕ призначений для програм загального призначення. Справа в тому, що переглядач довідки цього формату не входить в комплект жодної ОС Windows на сьогоднішній день. Підтримка довідки цього формату встановлюється тільки разом з Visual Studio або Delphi – це Document Explorer (dexplore.exe). Плюс до всього ви не можете тягати разом зі своєю програмою установник для цієї довідки (згідно ліцензії).
       


      Microsoft Help System aka HTML Help 3.0 (. MSHC) – формат довідки, використовуваний Visual Studio 2010. Розроблений в 2009. Підтримує Unicode. Аналогічно формату HTML Help 2.0/HXS – НЕ призначений для програм загального призначення (принаймні поки що), хоча обмежень на переглядач вже немає (довідку можна переглядати в будь-якому браузері). Файл. MSHC є звичайним перейменованим. ZIP файлом. Компілятор не потрібно – файли вмісту, що містять посилання один на одного, просто укладаються в архів. Сильні сторони формату: відкритість, швидкість, простота і прозора інтеграція з online-довідкою. Цей формат довідки має потенціал замінити собою. CHM і стати новою стандартною системою довідки в майбутньому.
       


      HTML (. HTML) – являє собою просто набір звичайних HTM / HTML файлів. Зрозуміло, що такий формат досить обмежений і зазвичай не має жодних переваг перед. CHM – окрім повної підтримки Unicode.
       


      Portable Document Format (. PDF) – формат, створений Adobe Systems в 1993. Зазвичай цей формат використовується для друку довідки (ще точніше – керівництва) на папері, а не як файл довідки у програмі.
       


      Web / Online – взагалі не файлова довідка. Являє собою відкриття web-сайту зі сторінкою довідки на ньому.
       


      Офіційно рекомендації Microsoft на жовтень 2010-го виглядають так:

      • Не використовуйте. HLP.

      • Для програм загального призначення використовуйте. CHM.

      • Якщо ви OEM партнер MS, який хоче розширити центр довідки та підтримки Windows в Windows Vista або Windows 7 – то використовуйте. H1S.

      • Якщо вам потрібна інтеграція в довідкову систему Visual Studio 2002 – 2008 (примітка від мене, не від MS: або Delphi), то використовуйте. HxS.

      • Якщо вам потрібна інтеграція в довідкову систему Visual Studio 2010, то використовуйте. MSHC.

      • . H1S,. HxS і. MSHC НЕ доступні для програм загального призначення, а. HLP застарів.

      Отже, якщо підсумувати – для Delphi програм у вас є вибір з трьох варіантів:

      • .HLP (WinHelp 4.0)

      • .CHM (HTML Help 1.x)

      • Web/Online

      З них. CHM і Web / Online є основними, а. HLP використовується тільки в особливих випадках.


      Підтримка форматів довідки в Delphi


      .HLP


      Підтримка цього формату є у всіх версіях Delphi. В Delphi 7 і нижче вам нічого спеціально робити не треба. У Delphi 2005 і вище вам потрібно підключити модуль WinHelpViewer в будь-яку секцію uses.


      .CHM


      Штатна підтримка цього формату є в Delphi 2005 і вище. Для цього вам потрібно тільки вказати в будь-якому uses модуль HTMLHelpViewer (Як завжди: чим раніше – тим краще).

      Примітка: не підключайте одночасно WinHelpViewer і HTMLHelpViewer. Або перший, або другий, або ні один, але не обидва одразу.

      Для Delphi 7 і нижче ви можете використовувати моє рішення. Використовувати його не менш просто – просто розпакуйте архів в папку вашого проекту і додайте модуль HTMLHelpViewerExв будь- uses вашого проекту.

      Це рішення також може бути використано в Delphi 2005 і вище, якщо вас не влаштовує стандартне рішення (модуль HTMLHelpViewer). І знову: підключайте в uses тільки один модуль (або WinHelpViewer, Або HTMLHelpViewer, Або HTMLHelpViewerEx, Або жодного).

      Див табличку нижче для порівняння можливостей форматів та їх реалізації.


      Web/Online


      Оскільки стандарту на ці системи довідок не існує, то в Delphi немає ніякої стандартної підтримки довідки цього формату. Вам доведеться робити її самостійно. Найпростіше це зробити, призначивши обробник події Application.OnHelp. В обробнику вам потрібно організувати реакцію на команди, які реально використовує ваш додаток, наприклад:






      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      51
      52
      53
      54
      55
      56
      57
      58
      59
      60
      61
      62
      63
      64
      65
      66
      67
      68
      69
      70
      71
      72
      73
      74
      75
      76
      77
      78
      79
      80
      81
      82
      83
      84
      85
      86

      type
        TForm1 = class(TForm)
          procedure FormCreate(Sender: TObject);
          function ApplicationHelp(Command: Word; Data: Longint; var CallHelp: Boolean): Boolean;
          
        end;
        

        
      procedure TForm1.FormCreate(Sender: TObject);
      begin
        Application.OnHelp := ApplicationHelp;
      end;
        
      function TForm1.ApplicationHelp(Command: Word; Data: Longint; var CallHelp: Boolean): Boolean;
        
        procedure OpenURL(const AURL: String);
        var
          SEI: TShellExecuteInfo;
        begin
          FillChar(SEI, SizeOf(SEI), 0);
          SEI.cbSize := SizeOf(SEI);
          {$IFDEF UNICODE}
          SEI.fMask := SEE_MASK_UNICODE;
          {$ENDIF}
          SEI.Wnd := Handle;
          SEI.lpVerb := open;
          SEI.lpFile := PChar(AURL);
          SEI.nShow := SW_SHOWNORMAL;
          if not ShellExecuteEx(@SEI) then
            RaiseLastOSError;
        end;
        
      var
        DataStr: String;
      begin
        // Пока установим признак успешного выполнения
        Result := True;
        
        case Command of
          // Открытие заголовочной страницы
          HELP_FINDER, HELP_TAB, HELP_CONTENTS:
            OpenURL(Application.HelpFile);
          // Поиск по ключевому слову
          HELP_KEY:
            OpenURL(Application.HelpFile + ?q= + PChar(Data));
          // Открытие темы по номеру
          HELP_CONTEXT, HELP_CONTEXTPOPUP:
            OpenURL(Application.HelpFile + /article + IntToStr(Data) + .html);
          // Расширенные команды:
          HELP_COMMAND:
          begin
            DataStr := PChar(Data);
        
            // Открытие индекса
            if StartsStr(SEARCH(, DataStr) then
              OpenURL(Application.HelpFile)
            else
            // Открытие поиска
            if StartsStr(FIND(, DataStr) then
              OpenURL(Application.HelpFile)
            else
            // Переход к теме по её имени
            if StartsStr(JI(, DataStr) then
            begin
              // Обрезали JI(
              DataStr := Trim(Copy(DataStr, 4, MaxInt));
              // Обрезали )
              SetLength(DataStr, Length(DataStr) – 1);
        
              OpenURL(Application.HelpFile + / + DataStr + .html);
            end
            else
            // Прочие команды – считаем поиском по ключевому слову
              Result := ApplicationHelp(HELP_KEY, Integer(DataStr), CallHelp);
          end;
          // HELP_QUIT: – здесь можно закрыть окно браузера
          // … <- тут прочие команды, если надо
        else
          // Все прочие команды обрабатывать не умеем – указываем, что завершились неудачно
          Result := False;
        end;
        
        // Мы сделали всю работу, делать больше нечего
        CallHelp := False;
      end;


      Зазвичай ключовими командами є HELP_KEY (А також її обгортка через HELP_COMMAND), HELP_CONTEXT/HELP_CONTEXTPOPUP, HELP_COMMAND з командою JI, А також якась команда "відкриття довідки взагалі" (наприклад, HELP_FINDER).

      Подія Application.OnHelp викликається при виконанні будь-якої команди з довідкою у вашій Delphi програмі, дозволяючи вам відреагувати на неї і відкрити web-сторінку.

      Тільки не забудьте встановити властивість HelpFile! Інакше Delphi програма буде вважати, що у вас немає довідки. Ви можете встановити в цю властивість URL довідкової системи (як це передбачається в прикладі вище). Приміром, для прикладу вище ви можете встановити властивість в http://www.google.com/search. Тільки зрозуміло, що відкриття теми по контекстного номеру або імені працювати не буде. Зате відкриття теми за ключовим словом призведе до пошуку цього слова в Google.


      Порівняння можливостей форматів


      Як я говорив вище, чи підтримується та чи інша команда – залежить від вибраного формату і версії Delphi. Я підсумують основні можливості, які ми розглядали, на прикладі Delphi 7 і Delphi XE. Для наочності, я додав колонку з web-довідкою, де + і – стоять за прикладом трохи вище. Ви повинні розуміти що це тільки приклад і ваша конкретна реалізація може мати як більше можливостей, так і менше.

      Я думаю, що табличка досить зрозуміла, за винятком колонки D7/DXE – це я так позначив стороннє (не штатний) рішення з підключенням модуля HTMLHelpViewerEx.



































































































      Можливість .HLP .CHM Web
      Команда або метод Опис Delphi 7 Delphi XE Delphi 7 Delphi XE D7/DXE Приклад вище
      HelpJump Тема по ID +  +    +  2  + 
      HelpContext Тема по контексту +  +    +  +  + 
      HelpKeyword Тема за ключовим словом 1  1    +  +  + 
      HELP_CONTENTS Тема за замовчуванням +  +    +  +  +/- 
      HELP_FINDER Відкрити вікно довідки +  +      +  +/- 
      HELP_TAB Зміст +  +      +  +/- 
      SEARCH() Індекс +  +      +  +/- 
      FIND() Пошук +  +      +  +/- 
      HELP_QUIT Вихід +      +  +   

      + означає підтримку можливості, означає відсутність підтримки, +/- означає, що сама команда працює, але її результат нічим не відрізняється від звичайного відкриття довідки, а цифра – Часткову підтримку (баг) з посиланням на обхідний шлях (код нижче).

      Виправлення / обхідний шлях для 1:






      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18

      procedure TForm1.btByKeywordClick(Sender: TObject);
      var
        SaveOld: String;
        OldDir: String;
      begin
        SaveOld := Application.HelpFile;
        OldDir := GetCurrentDir;
        try
          ChDir(ExtractFilePath(Application.HelpFile));
          Application.HelpFile := ExtractFileName(Application.HelpFile);
        
          Application.HelpKeyword(example);
        
        finally
          Application.HelpFile := SaveOld;
          SetCurrentDir(OldDir);
        end;
      end;



      Виправлення / обхідний шлях для 2:

      Замість:






      1

      Application.HelpJump(mytopic);


      Потрібно використати один із наступних варіантів:






      1

      Application.HelpJump(JI(mytopic));






      1

      Application.HelpJump(::/mytopic.htm);






      1

      Application.HelpJump(::mytopic.htm);




      Висновок


      Сподіваюся, що ця стаття допоможе вам з інтеграцією довідки у ваші програми.
       
      У цьому керівництві були розглянуті стандартні можливості використання довідкових систем в Delphi, універсальні для будь-яких встановлених систем. Проте можливості конкретного формату довідки цим не вичерпуються. До примі

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


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

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

      Ваш отзыв

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

      *

      *