9. Reference WinHelp
  1. WinHelp poskytuje množinu maker, které umožňují řídit a přizpůsobovat funkčnost nápovědy. Když vytváříme nápovědný soubor, pak můžeme makra nápovědy spouštět:
    2. Makra nápovědy imitují formát jazyka C, ale nepodporují proměnné a vyhodnocování výrazů. Příkaz makra nápovědy má dvě hlavní části: jméno makra a parametry makra uzavřené v závorkách. Jméno makra musí být zapsáno přesně tak, jak je dáno syntaxí makra a parametry musí být v pořadí dané syntaxí. Parametry poskytují informace pro makro např. makro JumpId, které provádí skok na prvek nápovědy se specifikovanou identifikací, má parametry pro jméno nápovědného souboru a identifikaci prvku nápovědy. Všechna makra nápovědy používají následující syntaxi:
    JmenoMakra(parametr1, parametr2, ...)
    Otevírací závorka, uzavírací závorka a čárky jsou požadované znaky vložené do syntaxe příkazu makra. Ve jménu maker není rozlišována velikost písmen. Help Workshop automaticky mění jména maker na jejich zkrácený tvar a odstraňuje všechny nadbytečné mezery. To umožňuje používat pro makra jejich dlouhá jména v .rtf souborech prvků nápověd pro zvýšení jejich čitelnosti.
    Parametry mohou být textové řetězce nebo čísla a oddělují se čárkami. Pokud poslední parametr makra je 0 nebo "", pak tento parametr můžeme vynechat. Některá makra nemají parametry, ale závorky jsou stále vyžadovány.
    Pokud vytvoříme uživatelské makro, pak jméno makra musí začínat písmenem, následované libovolnou kombinací písmen, číslic a znaků podtržení. Např.
    PlayAudio()
    Do řetězce makra můžeme vložit více než jedno makro a pak je nutno je navzájem oddělit dvojtečkami nebo středníky. WinHelp spouští makra sekvenčně. Zpětná lomítka jsou používána jako ESC sekvence a umožňují vkládat uvozovky do parametrů maker. Pokud potřebujeme použít v parametru zpětné lomítko (např. ve specifikaci adresářové cesty), pak musíme použít dvojité zpětné lomítko pro každou úroveň vnoření makra. Ve specifikaci cesty lze místo zpětných lomítek používat normální lomítka.
    Help Workshop testuje přípustnost každého makra vloženého do nápovědného souboru při překladu. Při zjištění chyby, je zobrazena chybová zpráva a zpracování tohoto makra je ukončeno. Help Workshop testuje zda: Pokud chceme k našemu nápovědnému souboru přidat funkčnost, kterou WinHelp nepodporuje, pak můžeme vyvinout uživatelské rozšíření podpory požadovaných funkcí. Můžeme použít volání funkcí v DLL jako makra nápovědy registrací funkcí v projektovém souboru pomocí makra RegisterRoutine.
    Program může zaslat parametr HELP_COMMAND ve volání API WinHelp, které specifikuje makro pro spouštění. Toto volání WinHelp vypadá takto:
    WinHelp(hwndProgram, "HelpFile[>WindowName]", HELP_COMMAND, "macro");
    Následující příklad používá makro ALink v souboru Myhelp.hlp:
    case IDM_HELP_KEYBOARD:
     WinHelp(hwnd,"myhelp.hlp",HELP_COMMAND,(DWORD)"AL('HELP_KEYBOARD\')");
     return 0;
    Když voláme makro z programu, pak nemůžeme použít Help Workshop k převodu maker do formátu, kterému WinHelp rozumí. To znamená, že musíme používat krátká jména maker, používat uvozovky okolo všech řetězcových parametrů, pro číselné parametry používat číselné hodnoty a používat všechny parametry maker. Není možno vynechat více parametrů jak je to možno provést v prvku nápovědy. Jediné parametry, které je možno vynechat jsou koncové parametry s hodnotou 0 nebo "".
    Help Workshop podporuje vnořená makra a makra která jsou vložena jako hodnota parametru jiného makra. Protože vnořená makra často mají své vlastní řetězcové parametry, musíme často specifikovat ukončení řetězce v jiném řetězci. Např. následující makro vytváří tlačítko nazvané Time, které používá makro ExecFile jako parametr. Když stiskneme tlačítko, pak je spuštěn program Clock MS Windows. Protože makro ExecFile přebírá jako svůj první parametr řetězec, musí být uzavřen v apostrofech:
    CreateButton("btn_time", "&Time", "ExecFile('clock', 0)")
    Pokud vnořené makro má nějaké řetězcové parametry, pak musí mít uvozovací znaky, které se liší od uvozovacích znaků obklopujícího makra. Pokud tedy okolo makra jsou použity uvozovky, pak vnořené řetězce musí být uzavřeny v apostrofech. Můžeme také použít znaky apostrofů k označení nejvíce vnějších parametrů.
  2. Následuje přehled maker nápovědy rozčleněný podle funkcí se stručným popisem maker. Tato makra můžeme používat ve svých nápovědných souborech.

    3. Makra tlačítek - tato makra můžeme použít pro zpřístupnění standardních tlačítek nápovědy, vytváření nových tlačítek nebo modifikaci funkčnosti tlačítek.
     
    Back Zobrazuje prvek nápovědy, který byl dříve zobrazen v současném okně.
    BrowseButtons Přidává tlačítko Browse k řádku tlačítek nápovědy.
    ChangeButtonBinding Mění makro přiřazené k tlačítku na řádku tlačítek.
    ChangeEnable Přiřazuje makro k tlačítku na řádku tlačítek a povoluje toto tlačítko.
    Contents Zobrazuje stránku obsahu nebo implicitní prvek současného nápovědného souboru.
    CreateButton Vytváří nové tlačítko a přidává je na řádek tlačítek.
    DestroyButton Odstraňuje tlačítko z řádku tlačítek.
    DisableButton Zakazuje tlačítko na řádku tlačítek.
    EnableButton Povoluje tlačítko na řádku tlačítek.
    Find Zobrazuje stránku Find v dialogovém okně Help Topics.
    Finder Zobrazuje dialogové okno Help Topics v jeho posledním stavu.
    Menu Zobrazuje místní nabídku, kterou obvykle zpřístupňujeme pravým tlačítkem myši.
    Next Zobrazuje následující prvek nápovědy ve vyhledávací sekvenci.
    Prev Zobrazuje předchozí prvek nápovědy ve vyhledávací sekvenci.
    Search Zobrazuje stránku Index v dialogovém okně Help Topics.

    Makra klávesnice - tato makra můžeme použít pro přidávání klávesnicového přístupu k makrům nápovědy.
     
    AddAccelerator Přiřazuje klávesu akcelerátoru k makru nápovědy.
    RemoveAccelerator Odstraňuje klávesu akcelerátoru od makra nápovědy.

    Makra vazeb - tato makra můžeme použít k vytvoření hypertextových vazeb na specifické prvky nápovědy.
     
    ALink Skok na prvek nápovědy, který obsahuje specifikované A-klíčové slovo.
    JumpContents Skok na prvek obsahu specifikovaného souboru nápovědy.
    JumpContext Skok na prvek nápovědy specifikovaný číslem kontextu.
    JumpHash Skok na prvek nápovědy specifikovaný hešovacím číslem prvku.
    JumpHelpOn Skok na prvek obsahu souboru How To Use Help.
    JumpId Skok na prvek nápovědy specifikovaný identifikací prvku.
    JumpKeyword Skok na prvek nápovědy obsahující specifikované K-klíčové slovo.
    KLink Skok na prvek nápovědy, který obsahuje specifikované K-klíčové slovo.
    PopupContext Zobrazuje vynořovací okno prvku specifikované číslem kontextu.
    PopupHash Zobrazuje vynořovací okno prvku specifikované hešovacím číslem prvku.
    PopupId Zobrazuje vynořovací okno prvku specifikované identifikací prvku.
    UpdateWindow Skok na specifikovaný prvek ve specifikovaném okně a návrat zaostření na okno, které volalo okno.

    Makra nabídky - tato makra můžeme použít k vytváření nebo modifikaci nabídky nebo prvku nabídky.
     
    AppendItem Připojuje prvek nabídky na konec nabídky.
    ChangeItemBinding Mění makro přiřazené k prvku nabídky.
    CheckItem Zobrazuje odškrtnutí vedle prvku nabídky.
    DeleteItem Odstraňuje prvek nabídky z nabídky.
    DisableItem Zakazuje prvek nabídky.
    EnableItem Povoluje zakázaný prvek nabídky.
    ExtAbleItem Povoluje nebo zakazuje prvek nabídky.
    ExtInsertItem Vkládá prvek nabídky na danou pozici nabídky v daném stavu.
    ExtInsertMenu Vkládá podnabídku v předem definované nabídce.
    InsertItem Vkládá prvek nabídky na danou pozici nabídky.
    InsertMenu Přidává novou nabídku.
    ResetMenu Uvádí nabídky do jejich implicitního stavu.
    UncheckItem Odstraňuje označení prvku nabídky.

    Makra programu - tato makra můžeme použít pro přístup k programům.
     
    ControlPanel Otevírá specifikovanou stránku v dialogovém okně Control Panel.
    ExecFile Spouští program nebo otevírá soubor a spouští program přiřazený k tomuto souboru.
    FileExist Zjišťuje zda specifikovaný soubor existuje na počítači uživatele.
    ShellExecute Otevírá, tiskne nebo spouští soubor nebo program.
    ShortCut Spouští nebo aktivuje program a zasílá zprávu WM_COMMAND.

    Makra označování textu - tato makra můžeme použít k vytvoření a manipulaci s označovači textu.
     
    DeleteMark Odstraňuje značku přidanou makrem SaveMark.
    GotoMark Skok na značku nastavenou makrem SaveMark.
    IfThen Spouští makro nápovědy, pokud daná značka existuje.
    IfThenElse Spouští jedno ze dvou maker pokud daná značka existuje.
    IsMark Testuje zda značka nastavená makrem SaveMark existuje.
    IsNotMark Testuje zda značka nastavená makrem SaveMark neexistuje.
    Not Neguje výsledek vrácený makrem IsMark.
    SaveMark Ukládá značku pro současný prvek nápovědy, okno a nápovědný soubor.

    Makra oken - tato makra můžeme použít k řízení nebo modifikaci chování různých oken nápovědy.
     
    CloseSecondarys Uzavírá všechna okna nápovědy mimo současného sekundárního okna.
    CloseWindow Uzavírá hlavní nebo sekundární okno nápovědy.
    FocusWindow Mění zaostření na specifikované okno nápovědy.
    HelpOnTop Umisťuje všechna okna nápovědy nad ostatní okna.
    PositionWindow Nastavuje velikost a pozici okna nápovědy.
    SetPopupColor Nastavuje barvu pozadí vynořovacích oken.

    Různá makra
     
    About Zobrazuje dialogové okno Version WinHelp.
    Annotate Zobrazuje dialogové okno Annotation.
    BackFlush Odstraňuje seznam historie ze současného okna.
    BookmarkDefine Zobrazuje dialogové okno Define, které je dostupné z nabídky Bookmark v hlavním okně nápovědy.
    BookmarkMore Zobrazuje dialogové okno Bookmark, které umožňuje uživateli volit, který založený prvek zobrazit.
    Compare Zobrazuje nápovědný soubor v další instanci WinHelp. Oba nápovědné soubory jsou zobrazeny vedle sebe.
    CopyTopic Kopíruje všechen text současně zobrazeného prvku do schránky.
    EndMPrint Opouští okno tiskových zpráv a ukončuje tisk více prvků.
    Exit Ukončuje WinHelp.
    FileOpen Zobrazuje dialogové okno Open, které je dostupné z nabídky File hlavního okna nápovědy.
    FloatingMenu Zobrazuje místní nabídku na současné pozici myši.
    Flush Nutí WinHelp k zpracování všech nevyřízených zpráv včetně dříve volaných maker.
    Generate Zasílá zprávu současnému aktivnímu oknu nápovědy.
    HelpOn Zobrazuje nápovědný soubor pro WinHelp.
    History Zobrazuje seznam historie, který zobrazuje až 31 prvků prohlédnutých v hlavním okně nápovědy od spuštění WinHelp.
    InitMPrint Inicializuje WinHelp v přípravě pro tisk více prvků.
    IsBook Zjišťuje, zda WinHelp je spuštěn jako samostatný systém nebo spuštěn z nějakého programu.
    Menu Zobrazuje místní nabídku pro současné okno nápovědy.
    MPrintHash Tiskne prvek identifikovaný hešovacím číslem.
    MPrintID Tiskne prvek určený identifikací.
    NoShow Zabraňuje zobrazení oknu nápovědy pokud již není zobrazeno.
    Print Zasílá současně zobrazený prvek na tiskárnu.
    RegisterRoutine Registruje funkci v DLL.
    SetContents Určuje specifikovaný prvek jako implicitní prvek v nápovědném souboru.
    TCard Zasílá zprávu programu, který je vyvolán WinHelp jako trénovací karta.
    Test Spouští interní test WinHelp.
    TestALink Testuje, zda makro ALink má efektivní vazbu alespoň na jeden prvek.
    TestKLink Testuje, zda makro KLink má efektivní vazbu alespoň na jeden prvek.

    Další informace o makrech a jejich syntaxi jsou uvedeny v nápovědě.

  3. Následuje tabulka popisující sekce, které mohou být použity v projektovém souboru:

    4.  
    Sekce Funkce
    [ALIAS]  Přezdívky jedné nebo více identifikací prvků na jiné identifikace prvků.
    [BAGGAGE]  Seznam souborů, které jsou umístěny do nápovědného souboru.
    [BITMAPS] Specifikace souborů bitových map. Tato sekce je udržována pouze pro zpětnou kompatibilitu.
    [BUILDTAGS]  Specifikuje vytvářecí značky. Tato sekce je udržována pouze pro zpětnou kompatibilitu.
    [CONFIG]  Specifikuje autorem definované nabídky a tlačítka použitá v nápovědném souboru a registrovaných DLL a funkcí DLL použitých makry v nápovědném souboru. Tato sekce je vyžadována pouze pokud nápovědný soubor používá tyto služby.
    [CONFIG:name]  Stejné jako  [CONFIG], ale používáno pro konfigurování jednotlivých oken.
    [EXCLUDE]  Specifikuje vytvářecí značky identifikující prvky, které chceme vyloučit z nápovědného souboru.
    [FILES] Specifikuje soubory prvků nápovědy, které mají být použity. Tato sekce je vyžadována.
    [FONTS]  Specifikuje písma v souborech prvků nápověd, které budou nahrazeny jiným písmem, velikostí nebo znakovou množinou.
    [INCLUDE] Specifikuje vytvářecí značky identifikující prvky, které mají být vloženy do nápovědného souboru.
    [MACROS]  Specifikuje spouštěná makra, když uživatel vybere z indexů jedno klíčové slovo uvedené v této sekci.
    [MAP] Přiřazuje identifikace prvků nápovědy s čísly kontextu, které program může použít k vyvolání nápovědného souboru.
    [OPTIONS]  Specifikuje volby pro řízení vytvářecího procesu. Tato sekce je povinná.
    [WINDOWS] Definuje charakteristiky hlavního okna nápovědy a typů sekundárních oken použitých v nápovědném souboru.

    Středníky jsou použity v projektovém souboru k označení komentářů (mimo sekce [MACROS]). V ostatních sekcích je ignorován text od středníku do konce řádku.
    Informace o obsahu jednotlivých sekcí najdete v nápovědě.

  4. V souborech prvků nápověd je možno používat následující příkazy:

    5.  
    {bmx}  Příkaz vkládá grafiku do prvku nápovědy při překladu nápovědného souboru.
    {button}  Příkaz vkládá tlačítko do nápovědného souboru a spouští specifikované makro, když uživatel tlačítko stiskne.
    {ewx} Příkaz vytváří vestavěné okno v nápovědném souboru.
    {mci} Příkaz vkládá soubor .avi do nápovědného souboru.

    Podrobnější informace o těchto příkazech najdete v nápovědě.

  5. WinHelp má pět standardních nabídek v hlavním okně: File, Edit, Bookmark, Options a Help. I když nelze modifikovat standardní nabídky nebo prvky nabídek, je možno přidávat další prvky nabídky k těmto nabídkám:

    6.  
    Mabídka/prvek Identifikace
    File mnu_file
    Edit mnu_edit
    Options mnu_options
    Help mnu_help
    Místní nabídka mnu_floating

    WinHelp nabízí následující standardní tlačítka v hlavním i sekundárních oknech:
     
    Tlačítko Identifikace Makro Popis
    Contents btn_contents Contents Zobrazuje stránku obsahu v dialogovém okně Help Topics. Pokud soubor obsahu neexistuje, pak zobrazuje implicitní prvek.
    Index btn_search  Search Zobrazuje stránku Index v dialogovém okně Help Topics.
    Find btn_find Find Zobrazuje stránku Find v dialogovém okně Help Topics.
    Help Topics btn_topics Finder Zobrazuje dialogové okno Help Topics s nejčastěji používanými záložkami. Pokud nepoužijeme toto tlačítko, pak nelze použít tlačítka Contents a Index.
    Back btn_back Back Skok na naposled zobrazený prvek v tomto okně.
    Options btn_menu Menu Zobrazuje místní nabídku současného okna.
    Print btn_print Print Tiskne současný prvek.
    << btn_previous Prev Skok na předcházející prvek v prohlížecí sekvenci.
    >>  btn_next Next Skok na následující prvek v prohlížecí sekvenci.

    Další informace o používání WinHelp naleznete v nápovědě.

  6. Pokuste se v nějakém nápovědném souboru použít nějaké makro.
9. Reference WinHelp