Online Hjælp Introduktion til online manualer samt online hjælp i.net-applikationer Jørgen Sørensen jososoft software development 1998-2005 Jørgen Sørensen
Indholdsfortegnelse Online hjælp Grundlaget for online hjælp HtmlHelp Workshop Projekt Brugerfladen Indholdsfortegnelse Stikordsregister Færdiggørelse Nyttige faciliteter Working with HelpProvider Working with Tooltips Creating What's This Help 3 3 5 5 9 10 12 13 15 17 18 18 Side 2
Online hjælp Opbygning af online hjælp til applikationer og online manualer er helt identisk. Der bygges på et antal html-filer med billeder, CSS, JavaScript m.m. I begge tilfælde bliver alt dette kompileret sammen til én HtmlHelp-fil, som kan: afvikles selvstændigt (f.eks. en kogebog) kaldes fra en applikation (f.eks. hjælp til et tekstbehandlingsprogram) Hvis online-hjælpen skal kaldes fra en applikation, kan det f.eks. være den nedenfor viste. I menuen Filer er indsat: Ny, Åbn, Gem, Gem som, Afslut I menuen Hjælp er indsat: Indhold, Index, Søg Endvidere er der en statusbar, en checkbox og en knap. I de sidste 3 afsnit i dette hæfte ("Working with HelpProvider", "Working with Tooltips" og "Creating What's This Help") vises, hvordan hjælpen integreres med en applikation. Grundlaget for online hjælp Til alle projekter skal vi bruge en række html-filer. Det kan f.eks. være html-filer, der: er opskrifter til en kogebog eller beskriver hvordan en applikation benyttes (som eksemplet herunder) file.htm <html> <head> <title>menuen Filer</title> </head> <body> Menuen Filer indeholder følgende: <li><a href=new.htm>ny</a> <li><a href=open.htm>åbn</a> <li><a href=save.htm>gem</a> <li><a href=saveas.htm>gem som</a> <li><a href=exit.htm>afslut</a> </body> </html> new.htm <html> <head> <title>menuen Filer Ny</title> Side 3
</head> <body> Menuen Filer Ny vil åbne et nyt tomt dokument. </body> </html> open.htm <html> <head> <title>menuen Filer Åbn</title> </head> <body> Menuen Filer Åbn vil åbne Fildialogvinduet. Her kan en eksisterende fil vælges og åbnes. </body> </html> save.htm <html> <head> <title>menuen Filer Gem</title> </head> <body> Menuen Filer Gem vil gemme den aktive fil. <br>hvis den aktive fil er en ny fil og ikke før har været gemt vil Fildialogvinduet blive åbnet og et filnavn skal indtastes. </body> </html> saveas.htm <html> <head> <title>menuen Filer Gem som</title> </head> <body> Menuen Filer Gem som vil åbne Fildialogvinduet og et filnavn skal indtastes. </body> </html> exit.htm <html> <head> <title>menuen Filer Afslut</title> </head> <body> Menuen Filer Afslut vil afslutte programmet. </body> </html> Brug aldrig æ, ø eller å i filnavne. Side 4
HtmlHelp Workshop Til at fremstille online hjælpen skal vi bruge programmet HtmlHelp Workshop fra Microsoft. Hvis HtmlHelp Workshop ikke er installeret kan den downloades fra (på én linie): http://msdn.microsoft.com/library/default.asp?url=/library/enus/htmlhelp/html/vsconhh1start.asp Navnet på installationsfilen er "htmlhelp.exe". Kør installationen og der oprettes genvej til selve workshoppen (filen hhw.exe) i Programmer HtmlHelp Workshop. Åbn HtmlHelp Workshop Projekt Vælg File New Vælg Project Her tilbydes det at konvertere gamle Windows 3/95 hjælpesystemer. Dette skærmbillede springes over ved at klikke på Næste. Side 5
Vælg på Browse hvilken mappe projektet skal gemmes i. Giv projektet et navn. Her vælges "mitprogram" Klik Næste Kryds af ved HTML Files (.htm) Klik Næste Klik Add og udvælg de html filer, der skal med i projektet. Grafikfiler, der er brugt som illustrationer i htmlfiler skal ikke tilføjes, det klarer systemet selv. Side 6
Klik Næste. Klik Udfør i næste dialogboks. Herefter åbnes Projectfanen i HtmlHelp Workshop. Gem projektet med File Save Project. Programmet har nu tre faner under toolbar'en og en række ikoner i venstre side: Side 7
Indlæggelse af flere htmlfiler på et senere tidspunkt: klik på ikonet Add/Remove topic files klik på knappen Add Indlæggelse af andre filtyper i projektet, f.eks. CSS-filer eller javascriptfiler: klik på ikonet Add/Remove topic files klik på knappen Add skriv *.* i feltet Filnavn klik på knappen Åbn Side 8
Brugerfladen Herefter skal brugerfladens udseende defineres. Klik Add/Modify window definitions. Navngiv vinduet i boksen, der kommer frem, f.eks. hovedvindue, og tryk OK På fanen General skrives teksten i vinduets titellinie øverst, f.eks. MitProgram På fanen Buttons vælges de knapper, der skal være øverst i vinduet. Der er ni standardknapper samt to knapper Jump 1 og Jump 2, der kan linkes til specielle emner. Skriv knap-tekst i de to underste bokse. Der kan også linkes til en internetadresse, f.eks. http://www.firma.com/enside.htm På fanen Navigation Pane vælges, om der skal være et navigationspanel i venstre side. Hvis ja, kan der nederst vælges en Søg-fane (fritekstsøgning), om søgningen skal være Advanced og en Foretrukne-fane (bogmærker). Afkryds Auto sync, hvis markering i Indholdsfortegnelsen af åbne emner ønskes. På fanerne Styles og Extended Styles kan vinduets udseende yderligere tilrettes. Fanen Files anvendes senere Vælg OK. Afhængig af de valgte faciliteter, kan der komme et eller flere af de følgende billeder. Klik Næste Side 9
Afkryds Compile full-text information og klik Næste Tilføj Knaptekster og http-adresser til eventuelle Jump knapper i det næste vindue. Indholdsfortegnelse Klik på fanen Contents. Vælg "Create a new contents file". Tryk OK. Navngiv indholdsfortegnelsen f.eks. mitprogram.hhc og gem den i projektbiblioteket (der hvor projektfilen er). Side 10
Ikonerne i venstre margin skifter nu. Vælg Hængemappe-ikonet (ikon 2 til venstre) til øverste niveau i indholdsfortegnelsen Vælg Dokument-ikonet (ikon 3 til venstre) til de næste niveauer. I feltet Entry title skrives den titel, der skal fremkomme i indholdsfortegnelsen. Klik herefter på Add Listen under HTML titles er de titler, der er angivet i de html-filer, der indgår i projektet. I html-filerne er det teksten mellem <title> og </title>. Husk altid at give html-filerne værdi i title-tagget. Ellers vil der stå: "ikke-navngivet emne" her og i den færdige online hjælp. Vælg "Menuen Filer". Hvis der skal knyttes et dokument til Bog-/Hængemappe-ikonet (Overskrift i Indholdsfortegnelsen) markeres dokumentet og der trykkes på knappen Add. Herefter trykkes på OK i dette og næste skærmbillede. Hvis der ikke skal tilknyttes et dokument til titlen i indholdsfortegnelsen, trykkes på Cancel i dette skærmbillede og OK i næste skærmbillede. Der kan også linkes til internetadresser. Den skrives da i det nederste felt: File or URL. Side 11
Ændring i rækkefølge og niveauer sker med de fire piletaster Ændring i sammenhæng mellem titel og dokumentet ændres med blyant-ikonet Ændring fra Bog-ikon til Dokument-ikon eller omvendt sker med blyant-ikonet: Klik på fanen "Advanced" og "ving af" ved "Change entry to a page / heading" Sletning af en titel sker ved at klikke på kryds-ikonet Fortsæt med de følgende filer og gem herefter indholdsfortegnelsen ved at klikke på det nederste ikon. Det færdige resultat kan f.eks. se sådan ud: Stikordsregister Klik herefter på fanen Index. Vælg "Create a new index file". Tryk OK. Gå videre, navngiv den f.eks. mitprogram.hhk og gem den i projektbiblioteket (der hvor projektfilen er). Side 12
Ikonerne i venstre margin skifter nu. Tryk herefter på Nøgle-ikonet i venstre side for at indlægge nye stikord. Herefter skrives stikordet i feltet Keyword, der trykkes på Add, der vælges det tilhørende dokument og der trykkes på OK. Hvis ét stikord skal knyttes til flere dokumenter, skal der igen trykkes på Add (i figuren ovenfor). Til slut trykkes på OK. Der kan også linkes til internetadresser. Den skrives da i det nederste felt: File or URL. Indlæg stikordene: "Afslut", der er tilknyttet filen exit.htm "Fildialogvindue", der er tilknyttet filerne open.htm og saveas.htm "Gem", der er tilknyttet filerne save.htm og saveas.htm "Gem som", der er tilknyttet filen saveas.htm "Ny", der er tilknyttet filen new.htm "Åben", der er tilknyttet filen open.htm Stikordene kan lyttes med piletasterne; og kan sorteres alfabetisk ved at trykke på AZikonet. Der kan indlægges under-stikord til stikord ved hjælp af højre-pil ikonet. Disse under-stikord forbliver "lænket" til det overliggende stikord ved flytning eller sortering. Gem stikordsregisteret ved at klikke på det nederste ikon. Færdiggørelse Færdiggørelse betyder, at alle dokumenter (htm-filer), projektfilen (.hhp), indholdsfortegnelsesfilen (.hhc) og stikordsregisterfilen (hhk) kompileres sammen til én fil med typenavnet chm. Før kompilering skal brugerfladen rettes til. Vælg Project fanen og gå til 3. ikon i venstre side (Add/Modify window definitions). På det skærmbillede der kommer frem vælges fanen Files. Vælg derefter følgende: Side 13
Herefter trykkes OK Tryk på nederste ikon (Save all files and compile) for at gemme og starte kompilering. Vigtigt: Kompilering kan ikke foretages hvis en tidligere version af det færdige system er åben på egen pc eller andre steder på netværket. Luk tidligere versioner før kompilering. Kompilering medtager ikke dokumenter (html-filer), der er åbne på egen pc eller andre steder på netværket. Luk alle indgående dokumenter før kompilering. Til slut kan den færdige online-hjælp ses ved at klikke på Brille-ikonet øverst. Det samlede projekt resulterer i: en online-hjælp (HtmlHelp-fil) med "efternavnet" chm, fx MitProgram.chm en indholdsfortegnelsesfil, fx MitProgram.hhc (c for contents) en stikordsfil, fx MitProgram.hhk (k for keywords) en projektfil, fx MitProgram.hhp (p for project) Ved distribution til andre brugere skal kun HtmlHelp-filen (chm-filen) distribueres. Side 14
Nyttige faciliteter Bemærk: I de følgende beskrivelser gælder generelt: Efter ændringer og/eller tilføjelser skal alle dokumenter gemmes og lukkes For at se ændringer og tilføjelser i online-hjælpen skal den altid kompileres om Links til emner i samme eller anden online-hjælp Hyperlinks mellem emner oprettes i html-editor. Oprettelse af bogmærker Bogmærker oprettes i html-editor. Links til bogmærker i emner Hyperlinks til bogmærker oprettes i html-editor. Spring til bogmærker fra indholdsfortegnelsen Gå til Contents fanen Opret et nyt punkt ved at klikke på Dokument-ikonet Klik på Add Udvælg det dokument, der skal springes til I feltet nederst vises dokumentets filnavn i feltet File or URL: Her tilføjes umiddelbart efter filnavnet: #bogm (ret til rigtigt bogmærkenavn) Spring til bogmærker fra stikordsregistret Gå til Index fanen Opret et nyt stikord ved at klikke på Nøgle-ikonet Klik på Add Udvælg det dokument, der skal springes til I feltet næstnederst vises dokumentets filnavn i feltet File or URL: Her tilføjes umiddelbart efter filnavnet: #bogm (ret til rigtigt bogmærkenavn) Ændring af indholdsfortegnelsens udseende Gå til Projects fanen Klik på det øverste ikon til venstre (Contents Properties) På første fane General afkrydes, hvis der ønskes bøger i stedet for hængemapper På anden fane Styles kan udseendet tilpasses med f.eks. streger mellem emner, +/- kasser foran emnet, automatisk lukning af mapper/bøger m.v. På forhånd er de viste 5 faciliteter valgt. En facilitet fjernes ved at markere denne og trykke på knappen Remove. Nye faciliteter kan vælges ved at trykke på knappen Add. Tryk OK, når udseendet er fastlagt. Side 15
Forskellige ikoner i indholdsfortegnelsen Der er 42 forskellige ikoner til anvendelse i indholdsfortegnelsen. Denne facilitet kan bruges til at markere forskellige typer af dokumenter. Ikoner indlægges sådan: Gå til Contents-fanen Markér det punkt i indholdsfortegnelsen, der skal have et nyt ikon Klik på Blyant-ikonet Vælg Advanced-fanen Vælg ikon ved at klikke på Pil-op eller Pil-ned knappen udfor: Image index Sammensætning af flere online-hjælp Hvis man ønsker at opbygge et stort online hjælpsystem i mindre moduler, kan flere chm-filer sammensættes så indholdsfortegnelser og stikordsregistre bliver fælles. Vælg Project-fanens øverste ikon (Change project options) og Merge Files Klik på Add for at udvælge filer, der skal knyttes sammen med den aktuelle fil Fortsæt til alle "sammenhørende" filer er tilføjet og tryk OK Vælg herefter Contents-fanen Marker i den eksisterende indholdsfortegnelse, hvor den "nye" fils indholdsfortegnelse skal indlægges Højreklik på musen og vælg Insert File Skriv i boksen, der fremkommer: nyfil.chm::/nyfil.hhc og fortsæt (Ret navne på den nye fil og dens indholdsfortegnelsesfil) Der kommer en meddelelse om, at den nye fil ikke eksisterer; svar ja til, at den alligevel skal med! I indholdsfortegnelsen kommer nu en titel: INCLUDE: nyfil.chm::\nyfil.hhc Flere vinduer Online-hjælpen kan have flere samtidige åbne vinduer, hvilket typisk anvendes, hvor man har forskellige typer af information, der kræver forskellige vinduesfaciliteter. Flere vinduer oprettes på samme måde som det første vindue. Omdirigering af emner til de forskellige vinduer kan ske fra såvel Indholdsfortegnelsen som fra Stikordsregistret. Hvis et emne ønskes vist i et bestemt vindue, vælges fanen Advanced, og vinduets navn skrives i øverste linie i den boks, der kommer frem. Emner som kaldes fra hyperlinks vises i samme vindue som de kaldes fra. Har man oprettet flere vinduer kan disse også indeholde deres egne indholdsfortegnelser og stikordsregistre. Sammenkædningen sker ved under Project fanen - 3. ikon i venstre side (Add/Modify window definitions) under fanen Files at vælge, hvilken indholdsfortegnelse og hvilket stikordsregister, der skal vises i det pågældende vindue. Side 16
Working with HelpProviders Det følgende er en bearbejdet udgave af http://www.helpware.net/mshelp2/demo2/h1xnet.htm The Windows Forms HelpProvider component is used to associate an HTML Help 1.x Help file, an HTMLHelp 2.0 help file, or a standalone.htm file with your Windows application. You can even specify an http:// address. Adding a HelpProvider component to your Windows Form allows the other controls on the form to expose the Help properties of the HelpProvider component. This enables you to provide help for the controls on your Windows Form. In addition to displaying topics in.chm files or.htm files, you can use the HelpProvider to display popup text. Important: Place the compiled htmlhelp file in the bin folder of the application. To open a help file set to the Contents, Index, or Search tab In the Toolbox, double-click the HelpProvider component. A new component will appear in the area below the form. Set the HelpNamespace property of the HelpProvider1 to "MitProgram.chm". The file name retrieved by this method identifies the file that provides Help support for all the controls for which this object provides Help. This file name can designate either a compiled Help file (.chm) or a raw HTML file. Double-click the Contents menu item and then add the following code to display the.chm file set to the Contents Tab: [Visual Basic] Private Sub MenuItem2_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MenuItem2.Click Help.ShowHelp(Me, HelpProvider1.HelpNamespace) End Sub [C#] private void menuitem2_click(object sender, System.EventArgs e) { Help.ShowHelp(this, helpprovider1.helpnamespace); } To display the.chm file set to the Index tab, double-click the Index menu item and then add the following code: [Visual Basic] Private Sub MenuItem3_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MenuItem3.Click Help.ShowHelpIndex(Me, HelpProvider1.HelpNamespace) End Sub [C#] private void menuitem3_click(object sender, System.EventArgs e) { Help.ShowHelpIndex(this, helpprovider1.helpnamespace); } To display the.chm file set to the Search tab, double-click the Search menu item and then add the following code: [Visual Basic] Private Sub MenuItem4_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MenuItem4.Click Side 17
Help.ShowHelp(Me, HelpProvider1.HelpNamespace, HelpNavigator.Find, "") End Sub [C#] private void menuitem4_click(object sender, System.EventArgs e) { Help.ShowHelp(this, helpprovider1.helpnamespace, HelpNavigator.Find,""); } Press F5 to Start. When the application displays the form, click the Help menu's items to see the results of your work. Working with Tooltips The Windows Forms ToolTip component displays text when the user points at controls. A ToolTip can be associated with any control. In the Toolbox, double-click a ToolTip component. The component will appear in the area below the form. Select the Button control on the Form and then press F4 to display the Button control's properties. Find the property named "ToolTip on tooltip1". Click in the text area to the right of the property name and enter the text, "Link til producenten". Press F5 to Start. After the application compiles, you'll see the Form. Move the mouse so that it hovers over the button on the form. The ToolTip appears. You can use the same ToolTip component to serve as the source of tooltip functionality for all the controls on a form. If you're writing code... [Visual Basic] ToolTip1.SetToolTip(Button1, "Link til producenten") [C#] tooltip1.settooltip(button1, "Link til producenten"); Creating What's This Help To create What's This Help, take the following steps. In design mode, make the Form active and press F4 to display its properties. Find the property named "HelpButton" and toggle its value to True. Look at the form; nothing has seemingly changed! To make the HelpButton visible you must change the value of two other properties, in effect turning the form into a dialog. Find the MaximizeBox property and toggle its value to False. Do the same for the Minimize Box. Look at the form now. You'll see that a HelpButton has been added. Side 18
Press F5 to Start. Click the HelpButton to enable What's This Help. The cursor changes. Now click on the CheckBox or one of the buttons. Nothing happens. We haven't specified a source for help yet. If you're writing code... [Visual Basic] ' Display a help button on the form. form1.helpbutton = True ' Define the border style of the form to a dialog box. form1.formborderstyle = FormBorderStyle.FixedDialog ' Set the MaximizeBox to false to remove the maximize box. form1.maximizebox = False ' Set the MinimizeBox to false to remove the minimize box. form1.minimizebox = False [C#] // Display a help button on the form. form1.helpbutton = true; // Define the border style of the form to a dialog box. form1.formborderstyle = FormBorderStyle.FixedDialog; // Set the MaximizeBox to false to remove the maximize box. form1.maximizebox = false; // Set the MinimizeBox to false to remove the minimize box. form1.minimizebox = false; To create popup help for a control using a text string Click on the form and then set the focus to the CheckBox. Press F4 to display the CheckBox control's properties. Set the HelpString on HelpProvider1 property to "Aktiver automatisk gem". Press F5 to Start. When the application displays the form, click the HelpButton and then click the checkbox. You'll see the popup topic. If you're writing code... [Visual Basic] HelpProvider1.SetHelpString(CheckBox1, " Aktiver automatisk gem ") [C#] helpprovider1.sethelpstring (checkbox1, " Aktiver automatisk gem "); To display a help topic in a.chm file as help for a control Click CheckBox1 and then press F4 to display its properties. Set the HelpKeyword on HelpProvider1 property to "save.htm". The HelpKeyword property provides the key information to retrieve the help associated with the control from the Help file specified by HelpNamespace. Side 19
Set the HelpNavigator on HelpProvider1 property to "Topic". The HelpNavigator property is an enumeration that specifies the Help command to use when retrieving Help from the Help file for the specified control. Press F5 to Start. When the application displays the form, click the HelpButton and then click CheckBox1 or set focus at CheckBox1 and press the F1 key. The help topic, "Filer Gem" appears. If you're writing code... [Visual Basic] HelpProvider1.HelpNamespace = "MitProgram.chm" HelpProvider1.SetHelpNavigator(Button1, HelpNavigator.Topic) HelpProvider1.SetHelpKeyword(Button1, "save.htm") [C#] helpprovider1.helpnamespace= "MitProgram.chm"; helpprovider1.sethelpnavigator(button1, HelpNavigator.Topic); helpprovider1.sethelpkeyword(button1, "save.htm"); To display a help topic in a.chm file by keyword Click Button1 and then press F4 to display its properties. Set the HelpKeyword on HelpProvider1 property to "Ny". Set the HelpNavigator on HelpProvider1 property to "KeywordIndex". This value for HelpNavigator directs HelpProvider to search for a topic containing a keyword that matches the value of the HelpKeyword property associated with the control. Press F5 to Start. When the application displays the form, click the HelpButton and then click Button1. The help topic associated with "Ny" appears. If you're writing code... [Visual Basic] HelpProvider1.HelpNamespace = "MitProgram.chm" HelpProvider1.SetHelpNavigator(Button2, HelpNavigator.KeywordIndex) HelpProvider1.SetHelpKeyword(Button2, "Ny") [C#] helpprovider1.helpnamespace= "MitProgram.chm"; helpprovider1.sethelpnavigator(button2, HelpNavigator.KeywordIndex); helpprovider1.sethelpkeyword(button2, "Ny"); To display help for a form or dialog using the contents of an.htm file In the area below the form, click on the HelpProvider component. Press F4 to display the HelpProvider component's properties. Set the HelpNamespace property to "http://www.softadvice.dk/mitprogram.htm". Set the HelpNavigator on HelpProvider1 property to "Topic". The HelpNavigator property is an enumeration that specifies the Help command to use when retrieving Help from the Help file for the specified control. Press F5 to Start. When the application displays the form, press F1. Your default browser will display the topic. Side 20