Home

JavaHelp System User's Guide

1. Localized HelpSet English Localized HelpSet Japanese IdeHelp mock IDE For the merge demo For the object demo Demo HelpSets in JARs api hs HelpSet HolidayHistory hs HelpSet IdeDemo HelpSet Object demo HelpSet Localized HelpSet German Localized HelpSet English Localized HelpSet Japanese Sources for the demos JDK1 2 Browser demo Classviewer Navigator used in apiviewer Mock up of an IDE using JavaHelp Alternate search engine Example of how to merge HelpSets Object demo In addition the rt packages include jre Java 31 Keeping in Touch 32 Keeping in Touch The following is a list of ways to obtain and share information about the JavaHelp system Feedback Comments and questions about the JavaHelp system software are welcome Please review the FAQ at our home page before sending email to javahelp comments eng sun com Your email message will be read However due to the large volume of email we may not be able to respond personally Mailing List The JavaHelp team maintains a mailing list for disseminating information about JavaHelp system updates and events To subscribe send mail to listserv javasoft com In the body of the message type SUBSCRIBE JAVAHELP INFO Discussion group JAVAHELP INTEREST Sun maintains a mailing list as a JavaHelp community resource where interested parties can post and exchange information and inquiries about the JavaHelp system in a
2. The applet is downloaded from the server and executed The user requests help The applet forwards the request to the JavaHelp system Help data is downloaded from the server and displayed in the JavaHelp system viewer or browser window AB WN Applet 2 In the second scenario the JavaHelp system classes are downloaded along with the applet Because the JavaHelp system is a Java optional package it is possible that a fully compliant Java 2 SDK browser may not have the the JavaHelp system classes in its CLASSPATH In this case the JavaHelp system classes must be downloaded from the server Since the JavaHelp system is quite small this approach is often practical Browsers may choose to provide additional means for installing extensions downloaded through this mechanism Presentation and Deployment 46 Web Browser m applet jar jh jar oo00000 TT JavaHelp This topic intro duces the wer w network great product P gt Help Data The HTML page that contains the applet tag is loaded into the browser The applet is downloaded from the server and executed JavaHelp system classes are downloaded from the server The user requests help The applet forwards the request to the JavaHelp system Help data is downloaded from the server and displayed in the JavaHelp system viewer or browser window NnP WN Applet 3 The third scenario describes the case in which the applet is downl
3. 1 0 encoding ISO 8859 1 gt lt DOCTYPE toc PUBLIC Sun Microsystems Inc DID JavaHelp TOC Version 1 0 EN http java sun com products javahelp toc_1_0 dtd gt lt toc version 1 0 gt lt tocitem image toplevelfolder text Java Development Environment gt lt tocitem target jde intro gt Introduction to JDE Online Help gt lt tocitem text IDE Tutorial target tut starttoc gt lt tocitem text Introducing JDE target tut intro gt lt tocitem text Tutorial One target tut quickstart gt lt tocitem text Tutorial Two target tut edit gt lt tocitem text Tutorial Three target tut errors gt lt tocitem gt lt tocitem text Beans in JDE target bean jbeanstory gt lt tocitem text Tips on Using Beans Effectively target bean beantips gt lt tocitem gt lt toc gt This example produces the following TOC display amp Java Development Environmer C Introduction to JDE Online C IDE Tutorial D Introducing JDE D Tutorial One C Tutorial Two C Tutorial Three G Beans In JDE Tips on Using Beans Effe The TOC Tags The following table describes the TOC tags Table of Contents File 74 lt toc gt Defines the TOC It contains lt tocitem gt tags lt tocitem gt Defines a TOC entry Nesting entry within entry2 defines entry2 to be hierarchically contained within entry Uses the following attributes text Specifies the text for the entry t
4. 5 fo oO demos src In addition to the locations described below most of the demo programs are available through shortcuts program groups desktop icons links that you may have created during the installation of the JavaHelp system The demo programs use the JRE JDK that you designated during installation In order to run them using a different JRE JDK change your PATH variable to use the new JRE JDK instead Demonstration Programs 16 IDE Demo The IDE Demo is a mock up of an IDE Integrated Development Environment application that contains a complete fully featured help system IDE demo demonstrates the following functionality Standard TOC keyword index and full text search navigators navigators Synchronization The TOC display is synchronized with the content pane The topic displayed in the content pane is always highlighted in the TOC Content pane Help topics displayed in the content pane contain images hyperlinks and other 3 2 HTML tags Lightweight Java The top level topic Building Projects uses the JHSecondary Viewer components lightweight component to implement a popup window and a secondary window In this topic click on the blue term project to see the popup window and click on the button at the end of the first paragraph to see the secondary window These components are also demonstrated and described in the Context The JavaHelp system supports three types of context sensitive help Sensi
5. JAR Files 71 457 Fri Mar 13 13 30 06 PST 1998 JavaHelpSearch OFFSETS 465 Thu Mar 19 2 26 56 PST 1998 JavaHelpSearch POSITIONS 234 Thu Mar 19 2 26 56 PST 1998 JavaHelpSearch SCHEMA 3214 Thu Mar 19 2 26 56 PST 1998 JavaHelpSearch TMAP 3113 Thu Mar 12 07 28 36 PST 1998 topics topicl subtopicA topic html 230 Thu Mar 19 2 26 56 PST 1998 topics topicl subtopicB topic html 661 Wed Feb 18 14 40 46 PST 1998 topics topic2 subtopicA topic html 3181 Wed Feb 18 14 40 46 PST 1998 topics topic2 subtopicB topic html 667 Thu Mar 19 2 26 56 PST 1998 topics topic3 subtopicA topic html 9072 Thu Mar 12 07 28 36 PST 1998 topics topic3 subtopicB topic html 3673 Thu Mar 19 2 26 56 PST 1998 topics topic3 subtopicC topic html 551 Fri Mar 13 13 30 12 PST 1998 topics topic3 subtopicD topic html Extracting Files from JAR Files Use the x option to extract files from the JAR file C gt jar xvf my_help jar extracted META INF MANIFEST MF extracted my_helpset hs extracted my_map jhm extracted my_toc xml extracted my_index xml extracted JavaHelpSearch DOCS extracted JavaHelpSearch DOCS TAB extracted JavaHelpSearch OFFSETS extracted JavaHelpSearch POSITIONS extracted JavaHelpSearch SCHEMA extracted JavaHelpSearch TMAP extracted topics topicl subtopicA topic html extracted topics topicl subtopicB topic html extracted topics topic2 subtopicA topic html extracted topics topic2 subtopicB topic html extracted to
6. Presentation and Deployment 43 HI gt faveHelp lt H1 gt lt P gt Chis topic intro jure the wer W great product P gt Help Data lt Hi gt faveHelp lt H1 gt lt P This topic intro jure the wer w i great product P gt Bean2 Help Data In this case the help information from the red JavaBean Bean1 and from the green JavaBean Bean2 is merged in the help viewer table of contents The merge operation can be performed by the developer ahead of time or completed when the application or JavaBeans component is installed by the user In the JavaHelp 1 0 release merging is accomplished by appending TOC and index information and searching merged full text search databases Help Server In some environments it is useful to separate the process that presents the help information from the application For example Applications that are written in a language other than the Java language for example C C Visual Basic can use the JavaHelp system to display online help when deployed on diverse computing platforms A suite of applications might be installed together or separately In this case the help server can be used to display help for the entire suite rather than each of the constituent applications providing their own help system In the following scenario applications not written in the Java language make requests to a JavaHelp system process help server
7. return 3 Create a HelpBroker object hb hs createHelpBroker 4 Create a Help menu item to trigger the help viewer JMenu help new JMenu Help menuBar add help menu_help new JMenulItem helpsetLabel menu help addActionListener new CSH DisplayHelpFromSource mainHB HelpSet The first thing your application does is read the HelpSet file specified by the application The HelpSet file defines the HelpSet for that application A HelpSet is the set of data that constitutes your help system The HelpSet file includes the following information Adding the JavaHelp System to Applications 103 Map file View information HelpSet title Home ID Sub HelpSets The map file is used to associate topic IDs with the URL or path name of HTML topic files Information that describes the navigators being used in the HelpSet The standard navigators are table of contents index and full text search Information about custom navigators is included here as well The name of the top level TOC folder The name of the default ID that is displayed when the help viewer is called without specifying an ID This optional section can be used to statically include other HelpSets using the tag The HelpSets indicated using this tag are merged automatically into the HelpSet that contains the tag More details about merging can be found in Merging HelpSets For more information about the HelpSet file see HelpSet
8. you will notice that different forms of the word builder built builds are not highlighted because the 100 match limit was met with the exact match build This should not be a problem with more complex multi word natural language queries NullPointerException in Search Navigator A NullPointerException sometimes occurs when search results are displayed This can be ignored program execution proceeds normally jhindexer Does Not Parse Correctly n The jhindexer does not treat the character correctly As as result a search for javax help in the apiviewer returns no matches Context Sensitive Help Field level help ActionListener JDK 1 1 The field level help ActionListener in the default implementation of the HelpBroker is disabled for JDK 1 1 JDK 1 1 doesn t allow the creation of custom cursors and doesn t support a predefined question arrow cursor Developers who want to support field level help on JDK 1 1 can implement a field level ActionListener that sets the cursor to one of the predefined cursors in java awt Cursor and then follow the steps described in the JavaHelp System User s Guide chapter Implementing Context Sensitive Help Field Level Help Button In the idedemo if the field level help button is clicked before the help viewer has been accessed for example Help gt Demo JDE Help a NullPointerException occurs F1 Help Solaris OpenWindows On Solaris OpenWindows manager the F1 key does n
9. Sets the HelpBroker s HelpActionListener on comp public void enableHelp MenuItem comp String id HelpSet hs Enables help activation for a MenulItem This method Registers the helpID and HelpSet on comp Sets the HelpBroker s HelpActionListener on comp Implementing Context Sensitive Help 108 public void enableHelpOnButton Component comp String id HelpSet hs Enables help for a Component This method sets the helpID and HelpSet for the Component and adds an actionListener When an action is performed it displays the Component s helpID and HelpSet in the default viewer If the Component is not a Jjavax swing AbstractButton or a java awt Button an MlegalArgumentException is thrown public void enableHelpOnButton MenuItem comp String id HelpSet hs Enables help for a Menultem This method sets the helpID and HelpSet for the Component and adds an actionListener When an action is performed it displays the helpID and HelpSet in the default viewer CSH Inner Classes The CSH class contains three inner classes that provide support for context sensitive help CSH DisplayHelpAfterTracking An ActionListener that displays help on a selected object after tracking context sensitive events Its constructor takes a HelpBroker object CSH DisplayHelpFromFocus An ActionListener that displays the help of the object that currently has focus This method is used to enable HelpKey action listening for components other than the
10. Supplemental Information You will probably find the following supplemental documentation and source code useful Programming with the JavaHelp System 101 API The javadoc generated documentation of the JavaHelp API is included with this release You can view the API using the JavaHelp API viewer demos bin apiviewer or using a web browser doc api index htm1 Specification The JavaHelp 1 0 specification is included in this release and can be found at doc spec index html Sample Source Files This release includes demo programs that demonstrate JavaHelp system functionality Sources for the demo programs are included in the release at demos sre See also Adding the JavaHelp System to Applications Implementing Context Sensitive Help Embedding JavaHelp Components Creating Lightweight Java Components Adding the JavaHelp System to Applications 102 Adding the JavaHelp System to Applications The process of adding the JavaHelp system to your application is summarized in the following steps 1 Import the JavaHelp system classes import javax help z Be sure to add one of the JavaHelp system libraries for example jh jar to your application s CLASSPATH 2 Find the HelpSet file and create the HelpSet object try URL hsURL HelpSet findHelpSet null help myHelpSet hs hs new HelpSet null hsURL catch Exception ee System out printin HelpSet t thelpsetName not found
11. The locale of a HelpSet is usually set through the HelpSet file The locale for the entire HelpSet can be specified through the HelpSet file although portions of it can be be selectively overridden in the data files Finding the HelpSet File When the application activates the JavaHelp system the application uses the HelpSet findHelpSet method to find the correct HelpSet file and return its location URL The full name of the HelpSet file is constructed based on the name of the HelpSet file specified as an argument to HelpSet findHelpSet and the locale based on either the system default locale or a locale specified as an optional argument The name of the locale specific HelpSet file is constructed and then searched for in the following order from most to least specific name_language_country_variant hs name_language_country hs name_language hs name hs name_defaultlanguage_defaultcountry_defaultvariant hs name_defaultlanguage_defaultcountry hs name_defaultlanguage ns z The defaults are derived from the system using the Locale getDefault method Setting Locales in the HelpSet File The HelpSet file can be used to control the locale of different aspects of the help system The XML language controls used to set locale are discussed in more detail in Localizing XML Data The xml lang attribute can be used within the lt helpset gt tag to specify the locale of the entire HelpSet the other elements in
12. demos bin demos bin idedemo demos bin hsviewer demos bin apiviewer demos bin merge demos bin object demos bin UserGuide demos bin lax demos lib demos lib classviewer jar demos lib idedemo jar demos lib searchdemo jar demos lib merge jar demos hs demos hs holidays demos hs il18n de The Swing 1 1 library Demos JavaHelp viewer running in an applet on a web browser Instructions for building the demos Demonstration programs Starts a mock up of an IDE HelpSet viewer JavaHelp API viewer Demonstrates HelpSet merging Demonstrates popup and secondary window functionality Displays the JavaHelp System User s Guide LaunchAnywhere files used to launch JavaHelp demos JARs containing different extensions JDK1 2 Classviewer used in apiviewer and idedemo Classes for IdeDemo Alternate search engine includes documentation Merge example Expanded unJARed helpsets Holidays Localized HelpSet German List of Files in the JavaHelp 1 1 Release demos hs il8n en demos hs il8n ja demos hs idehelp demos hs merge demos hs object demos hsjar demos hsjar apidoc jar demos hsjar holidays jar demos hsjar idehelp jar demos hsjar object jar demos hsjar idehelp_de jar demos hsjar idehelp_en jar demos hsjar idehelp_ja jar demos sre demos src sunw demo browser demos src sunw demo classviewer demos src sunw demo idedemo demos src sunw demo searchdemo demos src sunw demo merge demos src sunw demo object
13. generally work with developers to determine which topics are assigned to each object The developer assigns JavaHelp IDs to the application s GUI objects then the help author associates those IDs with topic URLs in the map file The fact that hard URL addresses are not embedded in the application code allows the author to change topics without requiring the developer to change the application For details about how context sensitive help is implemented for an application see Context Sensitive Help Types of Context Sensitive Help The JavaHelp system provides mechanisms for two types of context sensitive help user initiated help and system initiated help User Initiated Help User initiated help delivers information to users when they explicitly ask for it The JavaHelp system includes the following user initiated mechanisms Window Level Help Field Level Help Window Level Help Users can obtain help about container objects such as application windows and dialog boxes that have focus by pressing the F1 function key on systems with a Help key the Help key also works An object is considered to have focus when it is in a state that allows the user to interact with it By default help information is displayed in the help viewer Field Level Help Users can use field level help to obtain help about any GUI object To use field level help the user 1 Clicks the field level help button i2 or chooses the Help gt Fie
14. red white yellow See also The JHSecondary Viewer Component 92 The JHSecondaryViewer Component 93 The JHSecondaryViewer Component The JavaHelp 1 0 release provides popup and secondary window support through the JHSecondary Viewer lightweight component Popups and secondary windows are added to help topics by means of the lt OBJECT gt tag This topic describes how to use the lt OBJECT gt tag for this purpose To see how popups and secondary windows work you can experiment with the object demo located in demos bin You can also launch the object demo program using shortcuts program groups desktop icons links that you may have created during the installation of the JavaHelp system The topic files used in that demo provide examples of the lt OBJECT gt tag in use These files are located in demos hs object The following example creates a popup that is activated by clicking on the text object Click here lt OBJECT classid java com sun java help impl JHSecondaryViewer gt lt param name content value topicB glossary_def html gt param name viewerActivator value Jjavax help LinkLabel gt param name viewerStyle value javax help Popup gt param name viewerSize value 300 400 gt param name text value Click here gt param name textFontFamily value SansSerif gt param name textFontSize value x large gt param name textFontWeight value plain gt para
15. 65 lt helpset gt Defines the HelpSet It can contain all of the following tags lt title gt Names the HelpSet This string can be accessed by the application and used in the presentation for example in the viewer header stripe lt maps gt Specifies the default topic and URL of the map file used in the HelpSet Contains the following tags lt homeID gt Specifies the name of the default ID that is displayed when the help viewer is called if an ID is not explicitly specified lt mapref gt Specifies the map files Note that in the 1 0 release only one map file may be specified Contains the following attribute location URL of the map file lt view gt Defines the navigators used in the HelpSet Each navigator is defined by its own lt view gt May contain all of the following tags lt name gt Names the view lt label gt Specifies a label associated with the view This string can be accessed by the application and used in the presentation for example in the navigator s tab lt type gt Specifies the path to the navigator class lt data gt Specifies the path to the data used by the navigator When used with the search navigator it contains the following attribute engine Path to the search engine class lt subhelpset gt This optional tag can be used to specify HelpSets you want merged with the HelpSet that contains the tag See Merging HelpSets for more information Contains the following attrib
16. ClassLoader including standard URLClassLoader enables the easy creation of new ClassLoaders An improved security model Access to the SystemEventQueue from an applet when permitted by the security manager enables some context sensitive help features in applets Improved I18N support including input methods 2D graphics support Swing The JavaHelp 1 1 release requires Swing version 1 1 or higher Swing 1 1 and higher is included as part of the Java 2 SDK If you are using the JavaHelp release with JDK1 1 you must include Swing 1 1 or higher with your application A copy of Swing 1 1 1 is included in the JavaHelp 1 0 release in the swing folder Note that the JavaHelp viewer is part of the Swing package the viewer behaves slightly differently depending on which version of Swing you use Tested Java Platforms The JavaHelp 1 1 release should work with any compliant version of JDK1 1 or the Java 2 SDK We have tested this release against JDK1 1 8 and the Java 2 SDK JDK 1 2 2 on the following systems Windows 95 Windows NT4 0 Windows 98 Solaris 2 5 1 SPARC Solaris 2 6 SPARC Changes Since the 1 0 Release 8 Changes Since the 1 0 Release This page describes the most significant changes since the 1 0 release Changes made since the JavaHelp 1 1 Beta release are listed at the end Printing A print button has been added to the JavaHelp viewer toolbar Click the print button to print the page currently loaded
17. Full Text Search 79 Full Text Search The JavaHelp system full text search engine uses a natural language search technology that not only retrieves documents but locates specific passages within those documents where answers to queries are likely to be found The technology involves a conceptual indexing engine that analyzes documents to produce an index of their content and a query engine that uses this index to find relevant passages in the material As the help author you create the search database that is searched by the JavaHelp system full text search engine The process of creating the search database is described in Creating the Full Text Search How Searching Works To initiate a search the user enters a natural language query in the search navigator Find text box The results are reported back to the user in the following display Find full text search results 2 Limitations and Bugs 3 Full Text Search 1 Requirements amp 3 Full Text Search 3 Programming with the Java 2 Localizing the Full Text Sea 2 The jhindexer Command 2 The jhsearch Command 2 JavaHelp Libraries and Too 1 Merging HelpSets 1 Localizing HelpSets 1 Preface 1 The HelpSet File 1 Localizing Help Information The circle in the first column indicates the franking of the matches for that topic The more filled in the circle is the higher the ranking There are five possible rankings from highes
18. HelpSet is loaded into the hsviewer Plain Text Files Supported in Viewer Plain text non HTML files can now be displayed in the help viewer PDF Version of the JavaHelp System User s Guide The PDF version of the JavaHelp System User s Guide includes a table of contents printed at the end Swing 1 1 1 in swing Folder The 1 1 1 version of swingall jar is included in the JavaHelp 1 1 swing folder swingall jar Added to jhsearch CLASSPATH swing swingall jar has been added to the CLASSPATH of the jhsearch command JRE 1 2 2 in rt Packages JRE1 2 2 is included in the self extracting JavaHelp 1 1 packages that contain a JRE rt suffix Discussion Group JAVAHELP INTEREST Sun now maintains a mailing list as a JavaHelp community resource where interested parties can post and exchange information and inquiries about the JavaHelp system in a public forum Subscribers to this list can receive inquiries either as they are posted or in regular digest versions To subscribe send mail to listserv javasoft com In the body of the message type SUBSCRIBE JAVAHELP INTEREST To view archives manage your subscription or to unsubscribe http archives java sun com archives javahelp interest html Changes Since the 1 0 Release 13 Changes Since JavaHelp 1 1 Beta The following changes were made since the JavaHelp 1 1 Beta release Modal Dialog Boxes JavaHelp 1 1 now works correctly with JDK 1 1 modal dialogs JavaHelp 1 1 no
19. JAR file from your help files make the top level help folder the current folder The jar command descends recursively through the different directories and copies all of the files to the JAR file Use the following steps to create a JAR file named my_help jar from the hierarchy example above 1 C gt ed help where is the path above the help folder 2 C help gt jar cvf my_help jar The jar cvf command copies all the files in the help folder and in all folders hierarchically beneath it into a JAR file named my_help jar As the command creates the JAR file it reports its progress with output like the following adding my_helpset hs in 5757 out 2216 deflated 61 This indicates that the file my_helpset hs was added to the JAR file and compressed 61 from 5272 bytes to 2150 bytes When you create a JAR file the jar command automatically creates a manifest file for you The manifest file consists of a list of files present within the archive itself Listing JAR Files Use the t option to list the files included in a JAR file C gt jar tvf my_help jar 5272 Fri Apr 03 14 48 04 PST 1998 META INF MANIFEST MF 5757 Fri Apr 03 12 21 04 PST 1998 my_helpset hs 1345 Wed Feb 18 14 40 16 PST 1998 my_map jhm 1478 Wed Feb 18 14 40 16 PST 1998 my_toc xml 4678 Thu Mar 12 07 28 54 PST 1998 my_index xml 2345 Thu Mar 12 07 28 32 PST 1998 JavaHelpSearch DOCS 3456 Thu Mar 19 11 26 56 PST 1998 JavaHelpSearch DOCS TAB
20. JavaHelp system is activated by your application the first thing it does is read the HelpSet file specified by the application The HelpSet file defines the HelpSet for that application A HelpSet is the set of data that comprises your help system The HelpSet file includes the following information Map file The map file is used to associate topic IDs with the URL or path name of HTML topic files View Information that describes the navigators being used in the HelpSet The standard information navigators are table of contents index and full text search Information about custom navigators is included here as well HelpSet title The name of the top level TOC folder Home ID The name of the default ID that is displayed when the help viewer is called without specifying an ID Sub HelpSets Optional section can be used to statically include other HelpSets using the lt subhelpset gt tag The HelpSets indicated using this tag are merged automatically into the HelpSet that contains the tag More details about merging can be found in Merging HelpSets After your product is installed on your user s system it must be able to find the HelpSet file The application specifies the path to the HelpSet file when it starts the JavaHelp system By convention the name of the HelpSet file ends with the hs extension HelpSet File Format The format of the HelpSet file is based on the World Wide Web Consortium Extended Markup Language XML 1 0
21. build is included in a search string matches that contain built builder building and builds are returned In the 1 0 release the morphing feature is only available for the Engish en locale See also reating the Full Text Search Database he jhindexer Command he jhsearch Command Localizing the Full Text Search Database Q 4 Creating the Full Text Search Database 81 Creating the Full Text Search Database When a user initiates a full text search the JavaHelp system full text search engine searches a special search database to find matches quickly You use the jhindexer command to create the search database for your help topics The search database created by the jhindexer command consists of six files located in a folder named JavaHelpSearch As described in Setting Up a JavaHelp System the search database folder is usually located in the same folder as the rest of the help metadata files Example The following example describes how to use the jhindexer command in its simplest form For details about other features of the jhindexer command see The jhindexer Command The example assumes that your help information is arranged in the following hierarchy help my_helpset hs my_map jhm my_toc xml my_index xml topict topic2 topic3 subtopicA subtopicA subtopicA topic html topic html topic html subtopicB subtopicB subtopicB topic html topic html topic html subtopicC top
22. gt tag can be used create empty entities such as lt DD gt lt BR gt lt TD gt lt BR gt lt TD gt A couple of memory leaks that effect the JavaHelp system have been fixed in Swing 1 1 1 Modal Dialogs In release 1 0 of the JavaHelp system modal dialogs blocked access to the help viewer this is fixed for applications running on JDK 1 2 and higher If a modal dialog activates help in a DefaultHelpBroker the current help frame is changed to a help dialog parented to the activating modal dialog this makes full interaction in the help presentation possible Because the help dialog is parented to the activating modal dialog the help dialog is dismissed when the modal dialog is dismissed z See Changes Since JavaHelp 1 1 Betajbelow for additional changes made since the Beta release The Initial Size of the Viewer Can Now be Set The setSize and getSize methods have been added to the DefaultHelpBroker class Anchor Targets in Frames It is now possible to link to anchor targets from one HTML frame to another Context Sensitive Cursor Fixed In some cases the context sensitive cursor wasn t reset correctly This has been fixed Merging Search results are now updated correctly if HelpSets are added or removed after a search has been done Missing lt subhelpset gt specifications are now correctly ignored Changes Since the 1 0 Release 12 Search Highlighting Search highlights are now removed from the display when a new
23. help If you do not set help for a given component CSH getHelpID recursively searches through the component s ancestors until it finds the first ancestor with a helpID or until it reaches the last ancestor After you set the helpID HelpSet for all components create a field level help button or menu item Set an ActionListener on the button or menu item with a HelpBroker object using getOnItemActionActionListener For example JToolBar toolbar new JToolBar CSH setHelpID toolbar toolbar main helpbutton addButton toolbar images help gif help helpbutton addActionListener new CSH DisplayHelpAfterTracking mainHelpBroker Help Menu Button Help To implement or Help button help 1 Create a menu item or button 2 Set the helpID and if you use multiple HelpSets HelpSet on the object 3 Enable help on the object with the HelpBroker The CSH class provides the CSH DisplayHelpFromSource class to enable help on objects with types other than AbstractButton Button or Menultem For Example JButton helpButton new JButton Help mainHelpBroker enableHelpButton helpButton browse strings null System Initiated Help Although system initiated help is rarely implemented using the help viewer it is simple to do When help is presented internally within an application pass a valid helpID to a HelpBroker object For example try mainHelpBroker setCurrentID helpID catch Exception ee System e
24. in the viewer Notes about printing Print support in JDK 1 2 and JDK 1 2 2 is not as efficient as it will be in JDK 1 3 you may notice that extremely large print files are created especially if they contain images The JRE included with the Win32 version of the JavaHelp 1 1 release includes a back port of the 1 3 printing features to JDK 1 2 2 JDK 1 2 2 002 which greatly enhances print performance z If you want the enhanced print functionality to be available in your application s help JDK 1 2 2 002 must be used in the application It is available in the JavaHelp 1 1 jre folder On the JDK 1 2 x platforms a shrink to fit algorithm is used to ensure that pages that contain large images or long lines of preformatted text fit the width of the printed page Images are scaled and text sizes are reduced to accomplish this On JDK 1 1 systems large images or long lines of preformatted text can cause the page size to be set wider than the width of the paper this causes text to be clipped on the right margin Unless the shrink to fit algorithm is used see above the font used to render the page in the viewer is used on the printer The top margin on the first printed page is inappropriately large This is fixed in JDK 1 3 On Win32 JDK 1 2 and higher systems there are two print buttons The left button prints the current page with default settings and the right button can be used to change the page setup The setup button will be
25. included on the other platforms in the forthcoming JDK 1 3 p3 Changes to default settings in the Page Setup dialog box are not remembered between activations Print functionality is not available from a viewer implemented on JDK 1 1 running inside a web browser JRE 1 2 2 in rt Packages JRE1 2 2 is included in the self extracting JavaHelp 1 1 packages that contain a JRE rt suffix Changes Since the 1 0 Release 9 jhindexer The correct file separator character is now used in the search database on Win32 systems Plain text files are now indexed correctly JDK 1 2 2 Changes If you use JavaHelp with JDK 1 2 2 or Swing 1 1 1 with JDK 1 1 you will notice the following changes in the JavaHelp viewer Changes Since the 1 0 Release Partial CSS1 support You can use Cascading Style Sheets Level 1 with Swing 1 1 1 or JDK 1 2 2 and higher Style sheet support is not yet complete but it is quite useful External style sheets work correctly with the JavaHelp 1 1 release p3 kd r p p Due to a bug in the viewer tags in style sheets must be specified using lowercase letters If they are not they are ignored kd The default style sheet used with JDK 1 2 2 is included for reference in the javahelp doc css folder The following styles are supported in JDK 1 2 2 ont family ont style ont size supports relative units ont weight ont color background color with the exception of transparent backgrou
26. is an overview of the main features of the JavaHelp system Help Viewer The standard JavaHelp system viewer consists of a toolbar and two panes Content pane Displays help topics formatted using HTML 3 2 plus embedded lightweight Java Navigation A tabbed interface that allows users to switch between the table of contents index pane and full text search displays Ey Java Devetog ment Ermrormi Y trromuction to JOE ntad CIOE Tetris Debugging in the Source Editor When you open a project the source edor automaticaly bads your progam sourtes into ts window The EdtDOebug toolbar S Shove he source edio window provides rine dedugang buttons These bullons are activated at dierent umes CEPeNnding On BEN you can pafon the debugging funcdon For DO Cetuge rg Promete example afer you cick we Restart dunon all of the debugging Detugging wh Jove f buttons are actre C Steting Oesugpirg D Owtug ging is tte Sow D Spouhmnp Pragam A T Restart e C Preting Promcts C throwing Source C version c 3 CI Preferences the demugger ecw Toutos D Breakpoint te Starts of restarts debuggng of me project Al CNIS and GxLepiorrs are retained ater restarting Sets and removes breakpoints in the selected line of a tass Ifyou ciek a line that does not have a breakpoint i Table of Contents Collapsible expandable display of topics in the help system Supports unlimited lev
27. javahelp impl ViewAwareComponent These components implement the method setViewData The component can determine information from the View about the environment in which it is executing For example in the code snippet below the Document object is derived from the View private View myView static private URL base public void setViewData View v myView v Document d myView getDocument System err println myDocument is d j base HTMLDocument d getBase System err println base is base For more information about the Document interface see the Swing API http java sun com products jfc swingdoc api 1 1 javax swing text Document html Text formatting information can be derived from the View by querying its attribute set Use the method getAttributes as illustrated below AttributeSet as v getAttributes Format attributes can be used by the component when the AttributeSet is passed as a parameter to a StyleConstants method Methods exist to determine a number of attributes that include the font family font size font weight font style underlining background color foreground color For example to Creating Lightweight Java Components 114 determine what the default background color of an object Color color StyleContants getBackground as For a full list of formatting attributes and corresponding methods see http java sun com products jdk 1 2 docs api javax swing text StyleCons
28. proposed recommendation http www w3 org TR PR xml1 971208 The following is an example of a HelpSet file description follows lt xml version 1 0 encoding ISO 8859 1 gt lt DOCTYPE helpset PUBLIC Sun Microsystems Inc DID JavaHelp HelpSet Version 1 0 EN http java sun com products javahelp helpset_1_0 dtd gt lt helpset version 1 0 gt lt title gt lt title gt Java Development Environment Help lt title gt lt maps gt lt maps gt lt homeID gt top lt homeID gt lt mapref location Map jhm gt The HelpSet File lt maps gt lt views lt lt view gt lt name gt TOC lt name gt lt label gt Table Of Contents lt label gt lt type gt javax help TOCView lt type gt lt data gt lt view gt lt view gt lt name gt deHelpTOCc xml lt data gt ndex lt name gt lt label gt Index lt label gt lt type gt javax help IndexView lt type gt lt data gt lt view gt lt view gt deHelpIndex xml lt data gt lt name gt Search lt name gt lt label gt Search lt label gt lt type gt javax help SearchView lt type gt lt data engine com sun java help search DefaultSearchEngine gt JavaHelpSearch lt data gt lt view gt lt subhelpsets gt lt subhelpset location file c Foobar HelpSet2 hs gt lt helpset gt The HelpSet Tags The following table describes the HelpSet tags 64 The HelpSet File
29. public forum Subscribers to this list can receive inquiries either as they are posted or in regular digest versions To subscribe send mail to listserv javasoft com In the body of the message type SUBSCRIBE JAVAHELP INTEREST To view archives manage your subscription or to unsubscribe http archives java sun com archives javahelp interest html Web Site Other information can be obtained at our web site http java sun com products javahelp Keeping in Touch We hope to hear from you 33 The JavaHelp System 34 JavaHelp System Overview This overview consists of the following sections Introduction General introduction to the JavaHelp system JavaHelp System Features A brief overview of the main features of the JavaHelp system Scenarios that illustrate many ways the JavaHelp system can be used with different applications in a variety of network environments JavaHelp System A brief description of the lightweight component functions provided Lightweight Components with the JavaHelp system Introduction 35 Introduction Most interactive applications require online help Java applications are no exception The JavaHelp system is specifically tailored to the Java platform The JavaHelp system provides developers and authors a standard fully featured easy to use system for presenting online information to Java application users Providing a help system standard that is part of the Java platform stan
30. somewhere within the code try mainHelpBroker setCurrentID helpID catch Exception ee System err println trouble with visiting id tee See also Context Sensitive Help Programming with the JavaHelp System Adding the JavaHelp System to Applications Embedding JavaHelp Components Embedding JavaHelp Components 111 Embedding JavaHelp Components JavaHelp system components can be embedded directly into the application The following pared down steps are taken from the idedemo sample program included with the JavaHelp release A TOC navigator is added to the main application frame and the content pane is added to a tabbed display at the bottom of the main application frame You can find the complete sources for the sample program at demos src sunw demo idedemo 1 Find the HelpSet file and create the HelpSet object try ClassLoader cl ApiDemo class getClassLoader URL url HelpSet findHelpSet cl api apiHS new HelpSet cl url catch Exception ee System out println API Help Set not found return 2 Create the content pane JHelpContentViewer viewerl new JHelpContentViewer apiHS 3 Add the content pane to a container messages setComponentAt miscTabIndex viewerl messages setSelectedIndex miscTabIndex 4 Create a navigator TOC xnav JHelpNavigator apiHS getNavigatorView TOC createNavigator viewerl getModel Use the same model for both the c
31. the JavaHelp 1 1 Release Keeping in Touch The JavaHelp System JavaHelp System Overview JavaHelp System Features erging avaBeans Support Descriptive Scenarios Invocation Mechanisms Invocation Mechanisms Menus and Buttons ee Q ies A E Context Sensitive Help Presentation and Deployment Presentation and Deployment Standalone Application Component Help Full Text Search Full text Search Client Side Server Side i i 30 30 32 32 34 34 35 35 36 36 36 36 36 37 37 37 37 37 37 37 37 38 38 39 39 39 39 39 40 40 40 40 41 42 43 44 44 45 46 48 48 48 49 49 51 51 Authoring Help Information Authoring Help Information Java Platform gt zn Setting Up a JavaHelp System Links File Separators The HelpSet File HelpSet File HelpSet File Format The HelpSet Tags The Map File The Map File The Map Tags VS mr Using JAR Files ample Help Hierarchy he jar Command he JAR Protocol Table of Contents File Table of Contents File The TOC Tags Index File Index File The Index Tags Context Sensitive Help Context Sensitive Help Types of Context Sensitive Help User Initiated Help Window Level Help Field Level Help System Ini
32. to activate the window The font characteristics of this text can be controlled using these parameters textFontFamily textFontSize textFontWeight textFontStyle The JHSecondaryViewer Component jtextColor Example lt param name text value Click here gt textFontFamily The font family of the text object Valid values are Serif SansSerif Monospaced Dialog DialogInput Symbol Additional fonts will be supported in future versions of Java TM 9 SDK Example lt param name textFontFamily value SansSerif gt textFontSize The size of the font in the text object Valid values are xx small x small small medium large x large xx large bigger Increases the current base font size by 1 smaller Decreases the current base font size by 1 nnpt Sets the font size to a specific pt value of nn n Increases the current base font size by a value of n n Decreases the current base font size by a value of n n Sets the font size to the point size associated with the index n Example lt param name textFontSize value x large gt 97 The JHSecondaryViewer Component textFontWeight The weight of the font in the text object Valid values are plain bold Example lt param name textFontWeight value plain gt textFontStyle The style of the font in the text object Valid values are plain italic Example lt par
33. window contains four tabs Genera Information about the project nduding name tpe aud source arectory Working with Popups and Secondary Windows This section describes the different aspects of popups secondary windows that you the help author can control To see examples of popups and secondary windows try the object demo located in demos bin The lt OBJECT gt tag used to add these windows to your help topics is described in Tag Using Popup and Secondary Windows 90 Content The content of popup secondary windows is rendered by the same HTML engine used in the main help viewer Anything that is rendered in the main help viewer can be used in popup secondary windows including links graphics and lightweight components for example popup secondary windows Topics displayed in the windows can be specified using URLs or JavaHelp system IDs Activation Users activate popup secondary windows by clicking on one of the following Button fl A standard button provided as part of the popup secondary window component You can use the button as pictured to the left or you can specify a string of text or an image to replace the gt character on the button Text object A specified string of text inserted inline with the text of the topic The author can control font characteristics of the text to make it stand out Graphic object A GIF or JPG image Window Size You can specify the height and width of the popup se
34. with the following command hsviewer helpset C my_app help myhelpset hs The hsviewer command sets the classpath to be C my_app help You cannot reference files above the C my_app help folder For example in this case an image in C my_app images referenced like this Limitations and Bugs 25 lt IMG SRC images foo gif gt will not be displayed You can work around this problem by using the demos bin hsviewerl_1 command This command allows you to specify the classpath separately from the HelpSet file that way you can set the classpath to include the folder that contains the image and specify the HelpSet file relative to that folder For example hsviewerl_1 help myhelpset hs C my_app Duplicate Lines Displayed JDK1 2 2 If a TOC or index entry points to an anchor target specified at or near the top of the page in the first scroll zone Swing1 1 1 also part of JDK1 2 2 positions the lines incorrectly this results in lines being displayed twice Anchor Targets Anchor targets lt A NAME foo gt lt A gt are displayed in the center of the viewer display rather than at the top as is the case in most browsers If the TOC or index is used to access a topic file that contains anchor targets within the first scroll zone in the viewer text will be duplicated in the display Named anchors cause a space to be added at the beginning of the object that follows them The best way to work around this problem is
35. 4 124 125 125 126 126 126 126 126 126 127 127 127 128 128 129 129 130 130 130 vi Dataless Master HelpSets 131 132
36. C htm140 Using the lt OBJECT gt Tag You add lightweight components to JavaHelp topics by means of the lt OBJECT gt tag and its classid attribute The help viewer only recognizes classid values prefixed with the java tag All other classid tags are ignored The following example creates an ALabel within the HTML topic lt OBJECT CLASSID java sunw demo object ALabel lt OBJECT gt You can use standard lt OBJECT gt tag attributes see the HTML 4 0 specification for more details but to be recognized the lightweight component must have getter and setter methods for those attributes The getter and setter methods must operate on Strings For example in the following example width and height for the ALabel are set if there are getWidth setWidth and getHeight setHeight methods in ALabel lt OBJECT CLASSID java sunw demo object ALabel width 400 height 500 gt lt OBJECT gt Creating Lightweight Java Components 116 Parameters are passed to lightweight components using the lt param gt tag A parameter is only recognized if the component has getter and setter methods for that parameter The getter and setter methods must operate on Strings In the example below the help viewer passes a number of parameters and their values to a the JHSecondary Viewer component lt OBJECT classid java com sun java help impl JHSecondaryViewer gt lt param name content value topicB glossary_def html gt param
37. File HelpBroker The HelpBroker is an agent that negotiates and manages the display of help content for your application The HelpBroker also provides convenience methods that you can use to implement context sensitive help See Implementing Context Sensitive Help for details You can implement a help system without using the HelpBroker However without the HelpBroker you have to write code to directly manage the HelpViewer and JHelp objects navigators and context sensitive help functionality F1 key on dialogs help button activation and on item help button menu activation For a list and description of the HelpBroker methods see the API at doc api javax help HelpBroker html See also Programming with the JavaHelp System Implementing Context Sensitive Help Embedding JavaHelp Components Implementing Context Sensitive Help 104 Implementing Context Sensitive Help The JavaHelp system provides classes and methods that help you implement context sensitive help in your applications The following sections Summarize the context sensitive help system Describe the basic elements of the system Describe how to implement context sensitive help Summary The following table summarizes the context sensitive help system Object for Which Help Is Provided Implementation Steps Activation Mechanism Set helpIDs for components Capture F1 key press Press F1 or Help key Window with focus Get window that
38. Help system is activated by your application the first thing it does is read the HelpSet file The HelpSet file contains all the information needed to run the help system As you can imagine your application must be able to find the HelpSet file after the product is installed on your user s system The HelpSet file contains the location of the and in most cases the map file is read when the HelpSet is initialized The map file is used to associate topic IDs with URLs paths to HTML topic files The following diagram shows how a help hierarchy might be set up to include the HelpSet file and map file Setting Up a JavaHelp System 59 help my_helpset hs my_map jhm my_toc xml my_index xml WavaHelpSearch search db files rt ee topic1 topic2 topic3 subtopicA subtopicA subtopic topic html topic htm topic html subtopicB subtopicB subtopicB topic html topic htm topic html l subtopicC topic html subtopicD topic html To JAR or not to JAR You will generally package your help information into JAR files for delivery to your users Usually you package the HelpSet file and map file in the JAR file along with the topic files and navigational files On JDK1 1 systems this is the only option applications running on JDK1 1 which does not support the jar protocol must include all help information including the HelpSet file and map file in the JAR file On the Java 2 Platform the jar protocol makes other pack
39. ISO639 2 alpha characters TonaCode il I alpha characters UserCode x X alpha characters subcode alpha characters For more information about the lang attribute please refer to the HTML 4 0 specification at the World Wide Web Consortium web site http w3c org TR REC htm140 lt META gt Declaration The HTML lt META gt declaration can be used to specify the file s language Language is specified using the Content Language parameter lt META http equiv Content Language content en US gt HTTP Protocol If the HTML file is provided by a server via the HTTP protocol the server can specify the language for that file using the HTTP Content Language header for example Cont ent Language en US See also ocalizing Help Information ocalizing Help Presentation ocalizing HelpSets ocalizing XML Data ocalization and Fonts ocalizing the Full Text Search Database al iw Localization and Fonts 128 Localization and Fonts The JavaHelp system displays information using the host default fonts If a HelpSet contains information that cannot be presented using the default fonts an alternate font glyph usually a square is displayed in its place The JavaHelp presentation font can be changed either by modifying the font properties file in the JRE or by setting the font in the HelpBroker or JHelp components The HelpBroker setFont Font f m
40. JavaHelp System User s Guide 1 JavaHelp System User s Guide JavaHelp 1 1 November 1999 This user s guide contains the following chapters Release Information A description of the contents of the JavaHelp release avaHelp System Overview A general overview of the JavaHelp system Describes features usage scenarios and other technical details 5 o oO 9 pn oO a e B 5D a 5 Authoring Help Information A guide for help authors Describes how to set up a help system use popups and secondary windows use context sensitive help use full text search and package help information for delivery to users vu A guide for developers Describes how to add JavaHelp to System applications implement context sensitive help embed JavaHelp components into applications and develop lightweight Java components that can be added to help topics Localizing Help Information A guide for localizers of JavaHelp systems HelpSets Information about how to statically and dynamically merge HelpSets ee This guide is available in PDF format at doc jhug pdf The JavaHelp HelpSet for this guide can be found at doc jhug Copyright 1999 Sun Microsystems Inc All rights reserved Use is subject to license terms Sun Sun Microsystems the Sun Logo Solaris Java the Java Coffee Cup Logo JDK Java Foundation Classes J F C Java Plug in and JavaHelp are trademarks or registered trademarks of Sun
41. L file is provided by a server via the HTTP protocol the server can specify the character set using the charset parameter in the HTTP Content Type field lt META gt Declaration The HTML lt META gt declaration can be used to specify the character encoding Encoding is specified using the charset parameter lt META HTTP EQUIV Content Type CONTENT text html charset x euc jp gt Specifying a Language The language can be set in HTML files in the following ways listed in order of precedence The Tang anru Inheritance from the closest element tag The METAS declaration The HTTP protocol cont ent Language header The default locale of the HelpSet The default locale of the application Localizing HTML Data 127 The HTML lang Attribute The lang attribute specifies the language of a specific element tag gt It can be applied to every HTML element except the following lt APPLET gt lt BASE gt lt BASEFONT gt lt BR gt lt FRAME gt lt FRAMESET gt lt HR gt lt IFRAME gt lt PARAM gt and lt SCRIPT gt The following is an example of the lang attribute being used with the lt P gt tag lt P lang en US gt Any elements tags nested within a tag automatically inherit the parent tag s language The syntax of the lang attribute is lang language code language code primarycode subcode primarycode ISO639 IonaCode UserCode
42. Microsystems Inc in the U S and other countries DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS REPRESENTATIONS AND WARRANTIES INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE OR NON INFRINGEMENT ARE DISCLAIMED EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID JavaHelp System User s Guide 2 RESTRICTED RIGHTS LEGEND Use duplication or disclosure by the U S Government is subject to restrictions as set forth in subparagraph c 1 i of the Rights in Technical Data and Computer Software Clause at DFARS 252 227 7013 Oct 1988 and FAR 52 227 19 c June 1987 Release Information 3 The JavaHelp 1 1 Release This chapter describes the contents of the JavaHelp 1 1 release In addition to the JavaHelp system libraries the release contains a variety of demos examples and documentation How you explore and use the release depends on your interests For example gt If you are a developer interested in adding the JavaHelp system to an application you might Run the demonstration programs and examine the source code for those programs Read the chapters of the JavaHelp System User s Guide that pertain to developers Review the specification and the APIs gt Tf you are an online help author you might Run the demonstration programs Read the chapters of the JavaHelp System User s Guide that pertain to help authors Examine the exampl
43. RootPane or window This listener determines if the object with the current focus has a helpID if it does the helpID is displayed If the object does not have a helpID the helpID on the action s source is displayed if one exists CSH DisplayHelpFromSource An actionListener that gets the helpID for the action source and displays the helpID in the help viewer Its constructor takes a HelpBroker object Window Level Help Start your window level helpjimplementation by setting the helpID and if you use multiple HelpSets the HelpSet for each component for which you want help If you do not set help for a given component CSH getHelpID recursively searches through the component s ancestors until it finds the first ancestor with a helpID or until it reaches the last ancestor For example JTextArea newText new JTextArea j hb enableHelp newText debug overview hs After you set the helpID HelpSet for all components use the HelpBroker enableHelpKey method to enable the F1 key for the frame s RootPane The hb getHelpKeyActionListener method enables the F1 key on ActionListener objects other than root panes For example Implementing Context Sensitive Help 109 rootpane frame getRootPane j mainHelpBroker enableHelpKey rootpane top null Field Level Help Start your field level help implementation by setting the helpID and if you use multiple HelpSets HelpSet for each component for which you want
44. W Full Text Search 48 Full text Search The JavaHelp system includes a full text search facility that is fully featured compact fast and extremely flexible The JavaHelp system is shipped with a search database indexer Help authors use the search database indexer to create a compact database that is distributed with the application s help data When a user initiates a search the search engine searches the database to determine matches Alternative search engines can be substituted for the standard JavaHelp system search engine The following scenarios illustrate some of the different ways that the full text search can be used Three scenarios are presented Standalone Client side Server side Standalone In a standalone search all of the components search engine search database and help topics are local to the application 4 HI gt mahelp lt H1 gt lt P gt This topic intro jure the wer w 1 great product P gt Help Content w ooo0oo00 1 Search is initiated 4 User or application chooses a hit 5 Content is loaded and displayed 2 Search engine loads database 3 Search engine searches database and delivers hits to application Full Text Search 49 Client Side From an implementation point of view the client side search is identical to the previously described standalone search except that the components are downloaded from a server This arrangement is common w
45. aging options available The inclusion or exclusion of the HelpSet and map files from the JAR file has an effect on how you deliver the help information and how you can later update it The following two sections describe some of the issues to consider when making that decision HelpSet File Under some installation conditions the HelpSet file could be excluded from the JAR file while the map file is included The following diagram illustrates this arrangement Setting Up a JavaHelp System lt maps gt 60 HelpSet File lt mapref location jar file c Ajar jar MyMap jhm gt lt maps gt File1 html File2 h tml Ajar jar lt maplD target file1 url File1 html gt lt maplD target file2 url File2 html gt lt HI gt Introduction lt fHi gt lt P gt This topic introduces the user to a qreat product lt HIi gt Getting Started lt fHI gt lt P gt In order to install this product you must insert Note that the map file is referred to using the jar protocol The HelpSet file is the only help system file referenced explicitly by the application the JavaHelp system derives all information about the help system from that file If the HelpSet file is outside of the JAR file the installation program can update the HelpSet file so the JAR files can be installed anywhere in the user s file system This is not possible if the HelpSet file is included in the JAR file Another advan
46. am name textFontStyle value italic gt textColor The color of the font in the text object Valid values are black blue cyan darkGray gray green lightGray magenta orange pink red white yellow Example lt param name textColor value red gt 98 The JHSecondaryViewer Component gt See also Using Popup and Secondary Windows Creating Lightweight Java Components 99 Programming with the JavaHelp System Programming with the JavaHelp System The topics in this chapter of the JavaHelp System User s Guide describe the aspects of the JavaHelp system of primary interest to application developers The JavaHelp classes are distributed in the following JAR files The JAR files are located in the javahelp 1ib folder jh jar jhbasic jar jhtools jar jhall jar jsearch jar The standard library it includes everything needed to use the help viewer and the standard navigator types TOC index full text search A subset of jh jar that does not include support for the full text search engine This may be useful for very simple help systems that do not require a full text search database or help systems where size is important Includes the classes needed to view build and query the full text search database Includes all of the JavaHelp system classes including the tools required to create a search database The default full text search engine used in the JavaHelp system
47. anksgiving url hol thanks html gt lt mapID target thanksgiving_turkey url hol thanks html turkey gt lt mapID target 1thanksproc url hol thanks2 html gt lt mapID target gwthanksproc url hol thanks3 html gt lt mapID target althanksproc url hol thanks4 html gt lt mapID target valentine url hol val html gt lt mapID target onlove url hol love html gt lt map gt Note that images referred to as IDs for example in the TOC can also be associated with an ID in this example toplevel folder is associated with the GIF image toplevel gif The Map Tags The following are descriptions of the map tags lt map gt Defines the map It contains lt mapID gt tags lt mapID gt Defines a map entry Uses the following attributes target Specifies the ID to associate with the URL specified in the ur1 attribute url Specifies the URL to associate with the ID specfied in the target attribute See also The Map File The HelpSet File AR Files Table of Contents File ndex File Creating the Full Text Search Database 68 JAR Files 69 JAR Files This topic describes how JAR files are used in the JavaHelp system sing JAR files he jar command Creating JAR files isting JAR files he JAR protocol ti 4 Using JAR Files After you create your help information you will usually encapsulate it into a single file and compress it for delivery to your
48. ar Programs that demonstrate JavaHelp system functionality Source code for these programs illustrate how you can implement these features in your JavaHelp systems demos bin and demos src HelpSets that you can use to familiarize yourself with the capabilities of the JavaHelp system You can also use these HelpSets as templates for creating your own help systems demos hs and demos hsjar Source files for the JavaHelp system except the full text search engine src jar The DTDs Document Type Definition that define the XML based metadata files HelpSet map TOC Index are included in javahelp lib dtd The default style sheet for the JDK 1 2 2 viewer is included in doc css Contents of the Release For a detailed list of the files included in the release see List of Files in the Release Requirements 7 Requirements The following describes what is required to use the JavaHelp 1 1 release JDK The JavaHelp 1 1 release is an optional package of both JDK1 1 and the Java 2 SDK Standard Edition As a result it works well with both versions Java 2 SDK Features Java 2 SDK contains some functionality not available on JDK1 1 As a result the following JavaHelp system features are available only with the Java 2 SDK The jar protocol provides a general and consistent way to refer to files within a JAR file The ability to create temporary files improves full text search performance A more flexible
49. arget optional Specifies the ID to display when the entry is chosen by the user IDs are defined associated with a URL in the image optional Specifies the image displayed in front of a TOC entry The argument to this attribute is an ID defined associated with a GIF or JPEG image in the If this attribute is not specified the default folder file images are displayed See also JAR Files The Map File Index File Creating the Full Text Search Database Index File 75 Index File The index file describes to the index navigator the content and layout of the index The format of the index file is based on the World Wide Web Consortium Extended Markup Language XML The following is a very small example of a index file lt xml version 1 0 encoding ISO 8859 1 gt lt DOCTYPE index PUBLIC Sun Microsystems Inc DTD JavaHelp Index Version 1 0 EN http java sun com products javahelp index_1_0 dtd gt lt index version 1 0 gt lt indexitem text prof extension profile data target prof profile gt lt indexitem text accelerators keyboard see keyboard commands gt lt indexitem text adding an existing portfolio target proj import gt lt indexitem text adding an existing project gt lt indexitem text naming the project target proj importdirectory gt lt indexitem text naming the storage directory target proj importdirectory gt lt indexitem text pro
50. back new PropertyDescriptor 15 try back 0 new PropertyDescriptor content JHSecondaryViewer class back 1 new PropertyDescriptor id JHSecondaryViewer class back 2 new PropertyDescriptor viewerName JHSecondaryViewer class back 3 new PropertyDescriptor viewerActivator JHSecondaryViewer class back 4 new PropertyDescriptor viewerStyle JHSecondaryViewer class back 5 new PropertyDescriptor viewerLocation JHSecondaryViewer class back 6 new PropertyDescriptor viewerSize JHSecondaryViewer class back 7 new PropertyDescriptor iconByName JHSecondaryViewer class back 8 new PropertyDescriptor iconByID JHSecondaryViewer class back 9 new PropertyDescriptor text JHSecondaryViewer class back 10 new PropertyDescriptor textFontFamily JHSecondaryViewer class back 11 new PropertyDescriptor textFontSize JHSecondaryViewer class back 12 new PropertyDescriptor textFontWeight JHSecondaryViewer class back 13 new PropertyDescriptor textFontStyle JHSecondaryViewer class back 14 new PropertyDescriptor textColor JHSecondaryViewer class return back catch Exception ex return null Parameter Names When naming parameters be sure to avoid names reserved in the HTML 4 0 specification for use as lt OBJECT gt tag attributes For a complete list of lt OBJECT gt attributes see the HTML 4 0 specification http w3c org TR RE
51. bout localizing HelpSets see Localizing Help Information p3 To view these HelpSets the correct fonts must be installed on your system Due to a bug in the JDK the content pane can only display the default character set of the system on which it is running German This HelpSet is a portion of the idedemo HelpSet localized in German This HelpSet can be found in demos hs il8n de gt To view this HelpSet Windows 95 and Windows NT Java 2 Platform javahelp bin hsviewer helpset demos hs il18n de IdeHelp de hs JDK1 1 javahelp bin hsviewerl_1 IdeHelp_de hs demos hs il8n de IdeHelp_de hs Solaris Example HelpSets 22 Java 2 Platform demos bin hsviewer helpset demos hs il8n de IdeHelp_de hs JDK1 1 demos bin hsviewer1_1 IdeHelp_de hs demos hs il18n de Japanese This HelpSet is a portion of the IDE demo HelpSet localized in Japanese To view the Japanese HelpSet the correct Unicode fonts must be installed This HelpSet can be found in demos hs il8n ja gt To view this HelpSet Windows 95 and Windows NT Java 2 Platform javahelp bin hsviewer helpset demos hs i18n ja IdeHelp_ja hs JDK1 1 javahelp bin hsviewerl_1 IdeHelp_ja hs demos hs il8n ja Solaris Java 2 Platform demos bin hsviewer helpsetdemos hs il8n ja IdeHelp_ja hs JDK1 1 demos bin hsviewer1_1 IdeHelp_ja hs demos hs il8n ja JavaHelp Libraries and Tools 23 The JavaHelp Libraries and Tools The JavaHelp librarie
52. capabilities of the JavaHelp system You can also use these HelpSets as templates for creating your own help systems The HelpSets are described below JavaHelp System User s Guide The HelpSet that comprises the JavaHelp System User s Guide this document can be found in doc jhug History of the Holidays This HelpSet is interesting because it shows how a help system can be set up with two different TOCs This HelpSet can be found in demos hs holidays gt To view this HelpSet Windows 95 and Windows NT JavaTM 2 Platform javahelp bin hsviewer helpset demos hs holidays HolidayHistory hs JDK1 1 javahelp bin hsviewerl_1 HolidayHistory hs demos hs holidays Solaris Java 2 Platform demos bin hsviewer helpset demos hs holidays HolidayHistory hs JDK1 1 demos bin hsviewerl_1 HolidayHistory hs demos hs holidays IDE Demo This is the HelpSet used in the IDE Demo This HelpSet can be found in Example HelpSets 21 demos hs idehelp gt To view this HelpSet Windows 95 and Windows NT Java 2 Platform javahelp bin hsviewer helpset demos hs idehelp IdeHelp hs JDK1 1 javahelp bin hsviewerl_1 IdeHelp hs demos hs idehelp Solaris Java 2 Platform demos bin hsviewer helpset demos hs idehelp IdeHelp hs JDK1 1 demos bin hsviewer1_1 IdeHelp hs demos hs idehelp Localized HelpSets Two localized HelpSets German and Japanese are included in the release For more information a
53. cedures for target proj importproject2 gt lt indexitem gt lt indexitem text analyzing program performance see profiler gt lt index gt This example produces the following index display Find sisi prof extension ea le data accelerators keyboard see ke adding an existing portfolio adding an existing project naming the project naming the storage directory procedures for analyzing program performance The Index Tags The following table describes the index tags lt index gt Defines the index It can contains lt indexitem gt tags lt indexitem gt Defines a index entry Nesting entry within entry2 defines entry2 to be hierarchically contained within entry Uses the following attribute text Specifies the text for the entry target optional Specifies the ID to display when the entry is chosen by the user IDs are defined associated with a URL in the Index File gt See also fe fa 4 76 Context Sensitive Help 77 Context Sensitive Help The JavaHelp system provides a number of features that enable you to provide context sensitive help to your users Context sensitive help is information provided to users based on the context of the task in which they are involved Implementing context sensitive help involves associating help topics with objects in the application s graphical user interface GUI such as menu items buttons text boxes and windows Help authors
54. ch the IDs used internally in the application See also Localizing Help Information ocalizing Help Presentation ocalizing XML Data ocalizing HTML Datal ocalization and Fonts ocalizing the Full Text Search Database HelpSet File able of Contents File ndex File i T a iw 4 Localizing XML Data 124 Localizing XML Data The XML data that defines the TOC index and HelpSet files can be localized as specified in the XML 1 0 specification http w3c org XML Both the character encoding and language can be set for these files Character Encoding Character encoding is an unambiguous mapping of the members of a character set letters ideographs digits symbols or control functions to specific numeric code values The specified encoding applies to the entire file Character encoding can be set for XML files using the following methods listed in order of precedence The HTTP protocol The XML prolog declaration z Only one encoding can be specified for any file HTTP Protocol If the XML file is provided by a server via the HTTP protocol the server can specify the character set using the charset parameter in the HTTP Content Type field XML Prolog Declaration Typically the encoding attribute in the prolog to all of the XML metadata files is used to specify the encoding used for its character set For example the following prolog specifies the Lat
55. condary window When content exceeds the size of the window scroll bars are automatically added to the window Window Location secondary windows only You can specify the position of secondary windows on the screen Named Windows secondary windows only You can name secondary windows This enables you to reuse an already active window Text When you add text to a button or use a text object as an activator you can control the following font characteristics Using Popup and Secondary Windows 91 Font family You can set the font family to Additional fonts will be supported in future versions of the Java Serif SansSerif Monospaced Dialog DialogInput Symbol M9 Platform Font size You can set the size of the font to xx small x small small medium large x large xx large bigger Increases the current base font size by 1 smaller Decreases the current base font size by 1 nnpt Sets the font size to a specific point value of nn n Increases the current base font size by a value of n n Decreases the current base font size by a value of n n Sets the font size to the point size associated with the index n Font weight You can set the weight of the font to plain bold Font style You can set the style of the font to plain italic Using Popup and Secondary Windows Font color You can set the color of the font to black blue cyan darkGray gray green lightGray magenta orange pink
56. dard extension to the JDK relieves developers and authors of the task of inventing their own proprietary help systems The JavaHelp system consists of a fully featured highly extensible specification and an implementation of that specification written entirely in the Java language The implementation based on the Java Foundation Classes JFC provides a very simple interface that allows application developers and authors to quickly and easily add online help to their applications The specification enables developers to optionally customize and extend the help system to fit the style and requirements of their applications In addition the JavaHelp system has been designed to work especially well in a variety of network environments The JavaHelp system is platform independent and works in all browsers that support the Java platform The JavaHelp system enables Java developers to provide online help for Applications both applet and standalone JavaBeans M components Applets in HTML pages Authoring support for the JavaHelp system will be available through the major online help authoring tool vendors Tool vendors including Blue Sky Software ForeFront Quadralay CreativeSoft Hyperact and Virtual Media have publically announced that their products will provide authoring support for the JavaHelp system Next Overview Topic JavaHelp System Features JavaHelp System Features 36 JavaHelp System Features The following
57. details in exchange using the HelpBroker limits the flexibility of your implementation For example if you use the DefaultHelpBroker you must display help information in the standard help viewer You can implement context sensitive help without using the HelpBroker or use it for some tasks and not for others For example if your implementation requires something not provided in the HelpBroker for instance you want to display context sensitive help in a different viewer you must use the basic classes CSH JHelp directly For information about those classes use the JavaHelp system apiviewer command A HelpBroker s convenience methods enable Window level help for a dialog box Help buttons for dialog boxes Buttons and menu items that activate field level help The following illustration shows how the HelpBroker and its context sensitive methods hb are used with other JavaHelp system components Dialog Root hb enableHelpKey hs createHelpBroker hb enableHelp CSH DisplayHelp After Tracking hb enableHelp Field Level a mr Implementing Context Sensitive Help 107 HelpBroker Context Sensitive Methods A HelpBroker provides the following context sensitive methods public void setHelpSet HelpSet hs Sets the HelpSet for the current HelpBroker there can be only one HelpSet per HelpBroker If you use this method to change HelpSets the displays in the corresponding JHelp com
58. e HelpSets Create a HelpSet and view it using the fasviewer command Contents of the Release 4 Contents of the Release There are two installation packages available for both the Solaris and Win32 platforms Packages with the _rt suffix install the JavaHelp system with the Java 2 Runtime Environment JDK 1 2 2 packages with the no_rt suffix use a JDOK JRE already installed on your system If you installed the package that includes the JRE the JRE is installed in the folder named jre contained in the JavaHelp system installation folder All three packages contain the following Contents of the Release README file LICENSE txt JavaHelp System User s Guide this document Specification Libraries and tools Swing library Demonstration programs Example HelpSets JavaHelp source files DTDs Default Style Sheet Information about this release text document The JavaHelp license agreement text document Available in both PDF doc jhug pdf and JavaHelp HTML format doc jhug Defines the API between the application and the help system and the formats of the underlying files used by the JavaHelp system doc spec javadoc generated documentation of the JavaHelp API Can be viewed using the JavaHelp API viewerjor using a web browser doc api index htm1 The libraries javahelp 1ib and tools javahelp bin used to create online help systems The Swing 1 1 classes Swing swingall j
59. e gt TOC lt name gt lt label gt Table Of Contents lt label gt lt type gt javax help TOCView lt type gt lt view gt lt view gt lt name gt Index lt name gt lt label gt Index lt label gt lt type gt javax help IndexView lt type gt lt view gt lt view gt lt name gt Search lt name gt lt label gt Search lt label gt lt type gt javax help SearchView lt type gt lt view gt lt subhelpset location appl1 hs gt lt subhelpset location app2 hs gt lt subhelpset location app3 hs gt lt subhelpset location app4 hs gt lt helpset gt p3 A master HelpSet can contain a mixture of both dataless and datafull views Dynamic Merging HelpSets can also be merged programmatically using the JavaHelp API The basic API consists of the add HelpSet method and its corresponding remove HelpSet method These methods fire HelpSetEvent events to the HelpSetListeners that have registered interest in them The ComponentUIs for the TOC index and search views register for these events and react to changes The semantics of merging is implemented by individual NavigatorViews and JHelpNavigators There are three basic methods Merging HelpSets 133 canMerge NavigatorView merge NavigatorView remove NavigatorView The canMerge NavigatorView method is present in both NavigatorView and JHelpNavigator the JHelpNavigator method just calls into its corresponding NavigatorView meth
60. e online help that describes graphical components in an application GUI The user makes gestures that activate context sensitive help and then specifies the component in question The ID associated with the component is displayed Next Overview Topic Presentation and Deployment Presentation and Deployment 40 Presentation and Deployment The JavaHelp system is designed to be deployed in a number of different types of applications and in a variety of different network environments The following scenarios illustrate some of the different ways that the JavaHelp system can be used to present and deploy information Standalone Application A Java standalone application is one that runs independent of a web browser In this scenario the Java application runs locally and accesses help data installed on the same machine 4 lt Hi gt faveHelp lt H1 gt lt P gt This topic intro duces the wer w great product P gt Help Data The application 1 Requests the creation of a JavaHelp instance 2 Loads the help data on it 3 Presents the requested help topic Network Application The JavaHelp system provides the means to transparently load help data from networks intranet and internet When the help data is accessed across a network the scenario is essentially the same as in the standalone scenario the location of the data is transparent to the application Presentation and Deployment 41 4 HI gt faveHe
61. econdary Viewer Component 117 Localizing Help Information 118 Localizing Help Information This chapter contains information useful to localizers of JavaHelp systems The following topics describe how to localize the various components of the JavaHelp system Localizing Help Presentation Describes how the presentation aspects of JavaHelp primarily the help viewer are localized Describes how to localize HelpSets Describes how to localize XML based metadata files Describes how to localize HTML base topic files Describes the interaction of fonts with the localization of help information Localizing the Full Text Search Describes how to create localized full text search databases Localizing Help Presentation 119 Localizing Help Presentation The JavaHelp system viewer generally inherits the locale from the application For information about how applications are internationalized see the internationalization section of The Java Tutorial at http java sun com docs books tutorial il8n index html The culturally dependent data for example messages and labels for the presentation components is contained in the property file named javahelp properties in the javax help resources package If the locale of the help viewer is different from the locale of the application the locale of the HelpBroker can be set using the He lpBroker setLocale method Setting the locale of the HelpBroker sets the locale for all subordinate c
62. elpIDString Component comp String helpID Sets the helpID for a component public static String getHelpIDString Component comp Returns the helpID for a component public static void setHelpSet Component comp HelpSet hs Sets the HelpSet for a component public static HelpSet getHelpSet Component comp Returns the HelpSet of a component public static void setHelpIDString MenuItem comp String helpID Sets the helpID for a menu item public static String getHelpIDString MenuItem comp Returns the helpID for a menu item public static void setHelpSet MenuItem comp HelpSet hs Sets the HelpSet for a menu item public static HelpSet getHelpSet MenuItem comp Returns the HelpSet of a menu item Tracking Context Sensitive Events The context sensitive help class provides a method you can use to easily track context sensitive events This method traps all non navigational events until an object is selected It returns the selected object public static Component CSH trackCSEvents Implementing Context Sensitive Help 106 Implementing Context Sensitive Help The following sections describe how to use the JavaHelp system to implement the different forms of context sensitive help The HelpBroker The JavaHelp system defines a HelpBroker interface that provides convenience methods that greatly simplify the job of implementing context sensitive help HelpBroker methods hide much of the underlying implementation
63. els and merging of multiple TOCs The underlying file format follows World Wide Web Consortium W3C standards The TOC display is synchronized with the content viewer the topic being displayed is highlighted in the TOC Index Supports merging of multiple indexes The underlying file format follows World Wide Web Consortium W3C standards The index display is synchronized with the content viewer the topic being displayed is highlighted in the index JavaHelp System Features 37 Full Text Search The flexible full text search engine can be used in a variety of network environments Matches returned from searches are ranked for relevancy using relaxation rules Compression and Encapsulation The standard JAR format is used to encapsulate the help information into a single compressed file The JavaHelp system works equally well with help information that is not compressed into JAR files this flexibility allows authors to view files during development without taking the time to compress them Embeddable Help Windows Help windows individually or in combination can be embedded directly into application interfaces Context Sensitive Help Help can be activated from within programs using a number of different mechanisms Flexible Packaging Flexible packaging of help information for product delivery makes it easy to incrementally update help information in the field Customization The JavaHelp system is designed to permit grea
64. en buen your programs You can choose to use Ine Me standard savason Java Compiler instead of the detautt Java WorkShop comp er both are inchuded wth Java WorkShop The Jya WOreSrap Conger G truth fewer bul oes NO Super Secondary windows Can be displayed anywhere on the screen Can be iconified resized and moved by the user Persist until they are dismissed or the help viewer is dismissed E gt v jajj lt gt o OIS R ma Onarenerie recrei papp a Projects Dy wtroductes to 06 Onini Ce Toris D Booms noe lt 5 3 LD Tps se Using Beare ging JOUr buses Editing Project Attributes E maraging Proite sourte fies C Ett Bouree Fies edate whe C Daking Projectie iH orget ouad Projecti Mave amp set OF EDA a Gane Peer naua C Debugging Propects stitutes 2 Charactertics such as the optons to use when buiding the CI Preteen Propcts project You supply watues for some attributes when you Cl Browsing Boce Faes Tues commar create he pregect Java WorkShop suppers gerast vane for Pa baccent wae a ai other atributes You can view and edk attributes using me wea Ol wers tii Secondary Tomas You may wani gt To edt project attributes ind haptics Window 1 Okk the Project Qg button on the JOE main toolbar ms 2 in Me project manager select the project name tor Vane stich you want to view or edt atinbutes L hes 3 Choose Propa gt mot Tre Edt Project
65. ethod sets the font for a JavaHelp presentation and propagates the font to all of the presentation components JHelp components can set their fonts using the setFont method For more information about Unicode font support and adding fonts to the JRE please refer to the Fonts section in the following documents e JDK 1 1 http java sun com products jdk 1 1 docs guide intl ed ava M 9 Platform http java sun com products jdk 1 2 docs guide internat See also ocalizing Help Information ocalizing Help Presentation ocalizing HelpSets ocalizing XML Data ocalizing HTML Datal ocalizing the Full Text Search Database eel val ow Localizing the Full Text Search Database 129 Localizing the Full Text Search Database The JavaHelp system is constructed using the The jhindexer command parses HTML topic files according to each file s If the document format HTML GIF text supports a the document text is tokenized according to the language attributes for its elements By default jhindexer assumes the default locale use the Locale option to specify the locale directly to the jhindexer command The syntax for the locale option is jhindexer locale language_country_variant The argument to the option is the name of the locale as described in java util Locale for example en_US English United States or en_US_WIN English United States Windows variant See al
66. ets 53 Viewing HelpSets A HelpSet viewer is provided with the release to enable you to view HelpSets that you create A different command is used to start the viewer depending on which JDK your system is running Java 2 Platform hsviewer exe Win32 and hsviewer Solaris e JDK JRE1 1 hsviewer1_1 bat Win32 and hsviewer1_1 Solaris All of the programs display the HelpSets in the JavaHelp system help viewer the same viewer used to provide help in applications z The JDK JRE that you use to run hsviewer does not have to be the one your application is deployed on You can for example use the Java 2 Platform to run the demo programs including hsviewer even if your application is deployed on JDOK JRE1 1 e If you installed one of the packages with the extension rt you are using the Java 2 Platform If you installed one of the packages with the extension no_rt you are using the JOK JRE that you chose during installation For a list of limitations bugs and idiosyncrasies that pertain to the JavaHelp system HTML viewer see Limitations and Bugs In this release of JavaHelp the viewer toolbar does not include a reload button The easiest way to reload a file after you change it is to click the previous and next buttons Java TM 2 Platform If you use the Java 2 Platform to run the JavaHelp system demos the Java 2 Platform is the default if you ve installed the full JavaHelp installation u
67. files that JavaHelp uses to present information as well as the topics that inform the application s users Together the metadata and topic files are referred to as a HelpSet p3 If you use a help authoring tool to create your help system most of the details described in this chapter are managed for you by the tool The following is a summary of the tasks required to create a HelpSet All of these tasks are described in this chapter of the JavaHelp System User s Guide Create HTML topics Create a HelpSet file Create a map file Create a table of contents file Create an index file Create a full text search database Compress and encapsulate the help files into a JAR file for delivery to customers Consider the following strategy as a way to get started 1 Use the included with the release to acquaint yourself with JavaHelp system features The most useful demo for this purpose is idedemo This program demonstrates a fully functional help system 2 Read the remainder of this chapter of the JavaHelp System User s Guide and explore the HelpSet files created for idedemo demos hs idehelp 3 Create your own HelpSet 1 Create HTML topics using an editor of your choosing be sure to use only HTML 3 2 tags 2 Copy the metadata files from demos hs idehelp to the folder that contains your topic files 3 Edit the metadata files to match your help information 4 Use the hsviewer command to display your HelpSet Viewing HelpS
68. g Lightweight Java Components Creating Lightweight Java Components 79 79 80 80 81 81 81 83 83 83 84 84 85 85 87 87 88 88 88 89 93 93 94 100 100 102 102 104 104 104 104 105 105 106 106 107 108 108 109 109 109 110 111 111 113 113 View Information Using Parameters BeanInfo Class Parameter Names Using the lt OBJECT gt Tag Supplemental Information Localizing Help Information Localizing Help Information Localizing Help Presentation Localizing Help Presentation Data Input in the Viewer Localizing HelpSets Localizing HelpSets The HelpSet File Te Finding the HelpSet File Setting Locales in the HelpSet File Navigation View Locale hipping Multiple Locales Map Data Localizing XML Data L nN ocalizing XML Data Character Encoding HTTP Protocol XML Prolog Declaration The xml lang Attribute Localizing HTML Data _ The HTML lang Attribute Localization and Fonts Localization and Fonts s Localizing the Full Text Search Database Localizing the Full Text Search Database Merging HelpSets Static Merging va a i oa T oO i gs N Q e N 113 113 114 114 114 115 115 116 118 118 119 119 119 120 120 121 121 121 122 122 123 123 124 124 124 124 12
69. gt tags can be included in a HelpSet file HelpSets are appended in the order in which they occur in the HelpSet file If a HelpSet specified in a lt subhelpset gt tag is not found it is ignored and no error is issued The lt subhelpset gt location attribute takes a URL as its argument Indexes are merged in the same manner as TOCs by appending the merged indexes to the master HelpSet Merged search databases are searched sequentially however query results are collated and presented together Dataless Master HelpSets It is possible to create dataless master HelpSets that do not contain any view or map data of their own a dataless master serves only as a container for specifying sub HelpSets This is accomplished by omitting the lt dat a gt for the views All the notes listed above still apply Merging HelpSets 132 The following example HelpSet file could serve as an dataless master for a suite of applications The JavaHelp system constructs a help display with whichever of the application sub HelpSets app1 hs app2 hs are found installed on the user s system lt xml version 1 0 encoding ISO 8859 1 gt lt DOCTYPE helpset PUBLIC Sun Microsystems Inc DTD JavaHelp HelpSet Version 1 0 EN http java sun com products javahelp helpset_1_0 dtd gt lt helpset version 1 0 gt lt title gt lt title gt JavaHelp System User s Guide lt title gt lt views gt lt view gt lt nam
70. has focus Get helpID for window Display help Set helpIDs for components 1 Activate field level help cia a leyel help button a i with mouse or Selected object Track context 3 Select object sensitive events Get helpID for selected object Display help Create button or menu object Click button or choose Topic associated with button Set helpID on object menu item or menu item Get helpID on object Display help System Initiated Internal varies Internal varies Display help Basic Elements This section describes the low level elements used in implementing context sensitive help a If you use the convenience methods in the HelpBrokerjobject to implement context sensitive help these low level elements are managed for you The basic steps for implementing context sensitive help are Implementing Context Sensitive Help 105 1 Set and get Component help properties for GUI objects 2 Track context sensitive events Setting and Getting Component Help Properties In order to provide context sensitive help for GUI Components and menu items you must associate a help ID with that Component or menu item To make that association you set the helpID property and if you use multiple HelpSets the HelpSet for the Component or menu item The JavaHelp system CSH class provides the following convenient methods for setting and getting the he 1pID for Components and menu items public static void setH
71. ic html subtopicD topic html gt To create a full text search database 1 Make the help folder the current folder 2 Specify the top level folders as arguments to the jhindexer command jhindexer topicl topic2 topic3 2 Note that the jhindexer command is located in the javahelp bin folder of the JavaHelp system release The jhindexer command recursively descends the help hierarchy indexing all the files it encounters When finished jhindexer places the search database files in a folder named JavaHelpSearch in the current folder Creating the Full Text Search Database help my_helpset hs my_map jhm my_toc xml my_index xml WavaHelp Search DOCS DOCS TAB OFFSETS POSITIONS SCHEMA TMAP topic1 topic2 subtopicA subtopicA topic html topic html subtopicB subtopicB topic html topic html gt To verify the validity of a full text search database 1 Make the help folder the current folder 2 Specify the JavaHelpSearch folder as the argument to the command jhsearch JavaHelpSearch See also The jhindexer Command TH topic3 subtopicA topic html subtopicB topic html subtopicc topic htm subtopicD topic html The jhindexer Command 83 The jhindexer Command The jhindexer creates a full text search database used by the JavaHelp system full text search engine to locate matches You can use the command to verify the validity of the database To bui
72. iew gt lt name gt TOC lt name gt lt label gt Table Of Contents lt label gt lt type gt javax help TOCView lt type gt lt data gt hs1TOC xml lt data gt lt view gt lt subhelpset location HelpSet2 hs gt lt helpset gt HelpSet2 hs lt xml version 1 0 encoding ISO 8859 1 gt lt DOCTYPE helpset PUBLIC Sun Microsystems Inc DID JavaHelp HelpSet Version 1 0 EN http java sun com products javahelp helpset_1_0 dtd gt lt helpset version 1 0 gt lt title gt HelpSet 2 lt title gt lt maps gt lt homeID gt hs2_filel lt homeID gt lt mapref location hs2 jhm gt lt maps gt Merging HelpSets 131 lt view gt lt name gt TOC lt name gt lt label gt Table Of Contents lt label gt lt type gt javax help TOCView lt type gt lt data gt hs2TOC xml lt data gt lt view gt lt helpset gt 4 Helpset 1 CHs1 HelpSett Filet HelpSett File2 J HelpSet 2 E Hs2 HelpSet2 File1 HelpSet2 File2 The HelpSet that contains the lt subhelpset gt tag is considered to be the master HelpSet all HelpSets are merged with appended to the master HelpSet When HelpSets are merged only views with the same name lt name gt tag as a view in the master HelpSet file are merged Note that in the example above both views are named TOC Any views in the sub HelpSets that do not match the views in the master HelpSet are not displayed Multiple lt subhelpset
73. in 1 ISO 8859 1 character set lt xml version 1 0 encoding ISO 8859 1 standalone yes gt Setting the Language The language can be set for the XML files using the following methods listed in order of precedence The xm1 lang attribute which can be set for any XML element tag By finheritance from the closest parent element tag The HTTP protocol JContent Language header The default locale of the HelpSet The default locale of the application z It is possible to mix languages within these files A different language can be specified for each tag however only one character encoding can be specified for each file Localizing XML Data 125 The xml lang Attribute The language for any element tag in XML files can be set using the xml lang attribute For example lt tocitem xml lang de target jde intro gt Homepage der JDE Online Hilfe lt tocitem gt sets the language for that table of contents entry to German Any elements lt tocitem gt tags nested within that tag automatically inherit that language Typically the xml lang attribute is set in the opening tag for example lt toc xml lang de gt so all of the other elements in the TOC inherit the attribute In this case the entire TOC is in German The syntax of the lang attribute is lang language code language code primarycode subcode primarycode ISO639 IonaCode UserCode ISO639 2 alpha characters TonaC
74. ing shortcuts program groups desktop icons links that you may have created during the installation of the JavaHelp system Differences Between Popups and Secondary Windows Popups and secondary windows are functionally very similar They are both fully capable HTML windows that can include graphics links and lightweight components Most of the features described in this topic apply to both types of windows The following lists describe their differences Popups Are always displayed directly adjacent to the object the user clicks to activate the popup Cannot be resized or moved by the user Are dismissed whenever focus is changed to another part of the help viewer Using Popup and Secondary Windows 89 Benoni Building Projects C reoactes b uce oea S CE Turis a When you cick on the Java WorkShop Budd bution the D Bams h JDE D Tipa as Uang Dean tre oY ker buac Me Curreri project haset on the rttorreaion C Maraging frets source Mes comptes o C Eding Source Fies Species wren you crealg gt Glossary Term Preject C Daang Projecti project s build informas P C Detegory Preowxct trist J Projects organize the fies required to buid Java programs opup C Progeny Promets Window CI Browsing Bource Fies D version Corman Bad commands can asof tated tapit I Anais a Project Tris page describes the mos e YOU may wart H conser Pe fotkrwirey egnons wh
75. invocation methods available through the JavaHelp system Menus and Buttons Online help is often invoked when a user chooses an item from a Help menu or clicks on a Help button in an application GUI The JavaHelp system provides a simple interface by which an application requests that a topic ID be displayed The JavaHelp system then associates the topic ID with the appropriate URL and displays it IDs are mapped to URLs in a JavaHelp system metadata file called the map file For example when coding a file chooser dialog box a developer requests that the topic ID fc_help be displayed when the Help button at the bottom of the dialog box is clicked In the map file the ID fc_help is defined to be a file named FileChooser htm1 using the following XML syntax lt mapID target fc_help url html help FileChooser html gt Separating the specification of file names or URLs from the program code provides content authors the freedom to control the information that is associated with the topic ID Tooltips A tooltip is a brief message presented to the user when the cursor remains over a button for an interval longer than a given threshold Although tooltip information could be included in the JavaHelp system data it will usually be delivered as part of the application and will be co located with the code Tooltip functionality is provided as a component in Swing Context Sensitive Help The JavaHelp system provides the ability to invok
76. irectly after a heading the first number in the list is rendered in the same font as the heading You can work around this by inserting a tag for example lt BR gt between the heading and the list Empty Entities fixed in JDK1 2 2 Using the lt BR gt tag to create empty entities such as lt DD gt lt BR gt lt TD gt lt BR gt lt TD gt causes the following error Exceptions occurred during event dispatching javax swing text StateInvariantError infinite loop in formatting Full text Search Parsing of Asian Languages The JDK word break iterator that the JavaHelp search indexer and search navigator use to parse Asian Japanese Chinese Korean Thai languages uses a heuristic that is not well suited to searching As a result topic files are not parsed into words that users are likely to enter into the Find input field However because the parser works on the same model that is used to highlight words when the user double clicks in the content pane as a workaround albeit an inconvenient one the Asian language user can conduct a full text search using the following process Limitations and Bugs 28 1 Double click on words in the content pane 2 Copy paste them into the search navigator Find field 3 Press Return Match Limit To enhance full text search performance in this release the search navigator only reports the 100 most relevant matches For example in the idedemo program if you search for the word build
77. it as easy as possible to link the topics together It is also important to organize topics to easily package them into a compressed JAR file for delivery to your users For both of these reasons it is usually best to organize your topics in a folder hierarchy that you can tear off and place in the JAR file The following diagram shows such a hierarchy help topict topic2 topic3 subtopicA subtopicA subtopicA topic html topic html topic html subtopicB subtopicB subtopicB topic html topic html topic html subtopicC topic html subtopicD topic htm Links In most cases the destination of a link should be specified relative to the file that contains the link The following is an example of such a relative link lt A HREF subtopicB topic html gt new topic lt A gt In contrast the following link uses a full path name to describe the path to the destination of the link Setting Up a JavaHelp System 57 lt A HREF C product help subtopicB topic html gt new topic lt A gt Relative links will remain valid when the topic hierarchy is packaged into a JAR file and then installed on the user s computer File Separators vs All files within the JavaHelp system are specified as URLs The separator between elements files in a hierarchy should be In some cases works on the Win32 platforms however when the files that contain these references are added to JAR files or moved to differe
78. ith browser based applications applets where the help data usually resides on the same server as the applet code When a search is initiated the search data is downloaded from the server read into the browser s memory and searched The topic files are downloaded only when they are presented lt HI gt faveHelp lt H1 gt lt P gt This topic intro duces the wer great product P gt Help Content network 1 Search is initiated 4 User orapplication chooses a hit 5 Content is loaded and displayed 2 Search engine loads database 3 Search engine searches database and delivers hits to application During the initial search time is required to download the search database Once downloaded the data can be kept in memory or in a temporary file on the client machine and the searches are quite fast Server Side In a server side search the search data topic files and the search engine are all located on the server side only the results of the search are downloaded to the client Full Text Search 50 4 HI faveHelp lt H1 gt lt P gt This topic intro dure the wer 1 great product P gt Help Content 1 Search is initiated 4 User or application chooses a 2 JavaHelp requests search from ji server 5 Contentis loaded and displayed 3 Server side search engine searches database and delivers hits to application This option also works well fo
79. l gt TABS in lt PRE gt Tag not Recognized TABS used in text within lt PRE gt tags are not recognized Space characters are recognized correctly Viewer Cannot Load Image Files Directly The help viewer aborts if you attempt to load a graphic file gif jpg directly The images must be included in an HTML file using the lt IMG gt tag Page Setup Settings not Preserved Printing Changes made to the default settings in the Page Setup dialog box are not preserved between activations The default settings are always set upon activation Null Pointer Exception fixed in JDK1 2 2 Due to a timing problem in the underlying Swing JEditorPane component the following exception occurs occasionally Limitations and Bugs 27 Exception occurred during event dispatching java lang NullPointerException at javax swing text View preferenceChanged View java 121 at javax swing text html ImageView run ImageView java 414 This problem is benign Client side Image Maps fixed in JDK1 2 2 The tags required to implement client side image maps are not implemented lt MAP gt lt IMG USEMAP gt lt TT gt and lt CODE gt Tags fixed in JDK1 2 2 The lt TT gt and lt CODE gt tags do not change characters to a monospaced font Also other formatting tags for example lt b gt lt i gt located within these tags are not recognized lt OL gt Tag After Headings fixed in JDK1 2 2 If the lt OL gt tag is used d
80. ld Level Help menu item to change the cursor to the special field level help cursor 2 Selects a GUI object Context Sensitive Help 78 By default help information is displayed in the help viewer and the cursor returns to its original state Help Menu The Help menu can be used to provide help to users about specific tasks or objects The following Help menu contains a submenu of items that provide help about completing various tasks Help Contents Field Level Help Task based Help Managing Projects Menu Help Building Projects Tutorial Debugging Projects ea AEO Ero BCS eS En Source Files Serial NumberLicense Creating GUIs Release Notes Registration Browsing Source Files Send Comments Using Version Control Java API Documentation 1 13 The Java Language Specification About Java WorkShop Help Button It is common for dialog boxes to contain a Help button that provides help information about how to use the dialog box Clicking the Help button is usually equivalent to pressing the F1 key while the dialog box has focus System Initiated Help Most applications provide information automatically when the user performs a particular action Most commonly this information consists of status warning or error messages It is also possible for the application to use the help viewer to provide more detailed help based on user actions See also Implementing Context Sensitive Help
81. ld a full text search database use the following commands Win32 jhindexer options file folder Solaris SPARC jhindexer options file folder If the argument is a folder the folder is searched recursively for JavaHelp system content files The following options are available c file A configuration file name See Config File below db dir The name of the database output folder By default the output folder is named JavaHelpSearch and is created in the current folder locale The name of the locale as described in java util Locale For lang_country_variant example en_US English United States or en_US_WIN English United States Windows variant logfile file Captures jhindexer messages in a specified file You can use this option to preserve jhindexer output on Win32 machines where the console window is dismissed after execution terminates nostopwords Causes to be indexed in the full text search database verbose Displays verbose messages while processing Stopwords You can direct the JavaHelp system full text search indexer to exclude certain words from the database index these words are called stopwords By default the indexer ignores does not index the following stopwords when it encounters them in your help topics The jhindexer Command 84 a all am an and any are as at be but by can could did do does etc for from goes got had has have he her him his how if in is IE let me more much must my
82. line program that you can use to query the JavaHelp system full text search database created with the jhindexer command The jhsearch command can be used to verify the validity of a search database without invoking the help viewer To use jhsearch Win32 jhsearch database_folder Solaris SPARC jhsearch database_directory By default the jhindexer command creates the database files in a database folder named JavaHelpSearch See also Creating the Full Text Search Database The jhindexer Command Using Popup and Secondary Windows 88 Using Popup and Secondary Windows The JavaHelp system supports two types of HTML based secondary windows Popup Windows Secondary Windows Both types of secondary windows are implemented as a lightweight component class that can be added to HTML topics by means of the lt OBJECT gt tag This topic describes the functionality and characteristics of these windows For information about how to use the lt OBJECT gt tag to add popups secondary windows to your topics see The JHSecondary Viewer Component If you are using an authoring tool the tool will handle these details for you a Popups and secondary windows are not used in the JavaHelp System User s Guide because they cannot be included in the PDF version To see actual examples of how these windows can be used experiment with the ob ject demo located in demos bin You can also launch the object demo program us
83. lp lt H1 gt lt P gt This topic intro duces the wer i great produrt P gt Help Data network The application 1 Requests the creation of a JavaHelp instance 2 Loads the help data from the network 3 Presents the requested help topic Embedded Help Both navigational and content information can be embedded directly in application windows Embedding is accomplished by adding the JFC components that implement JavaHelp system components directly into the application frame Presentation and Deployment 42 4 cHI gt faeHelp lt H1 gt lt P gt This topic intro jure the wer w grer product P gt Help Data In this illustration the content viewer is embedded along the bottom of the application window and the navigation viewer is embedded in a different portion of the window The application can directly control the contents of the content viewer by programmatic means Likewise JavaHelp system navigators can be used to control information displays other than the JavaHelp system content viewer Component Help Many modern applications are composed of a collection of interacting components Examples range from large applications like Netscape Navigator with plugins to applications where JavaBeans components are connected together using JavaScript or Visual Basic In the case of JavaBeans each component may be shipped with its own help data The following illustrates such a case
84. m name textFontStyle value italic gt lt param name textColor value red gt lt OBJECT gt lt lt lt lt lt lt lt lt The lt param gt element specifies parameters to the JHSecondaryViewer component The lt param gt element takes two attributes name and value Parameters may be specified in any order if parameters conflict the one specified last is used Valid parameter names are viewerStyle content id viewerActivator viewerSize viewerLocation viewerName iconByName iconByID Cea textFontFamily textFontSize textFontWeight The JHSecondaryViewer Component 94 textFontStyle textColor Parameter Definitions viewerStyle Specifies whether the window is a popup or secondary window see Using Popup and Secondar Windows for a list of differences The valid values for this parameter are javax help Popup and Javax help SecondaryWindow If the viewerStyle parameter is omitted the window is created as a secondary window Example lt param name viewerStyle value javax help Popup gt lt param name viewerStyle value javax help SecondaryWindow gt content The URL of the topic displayed in the popup or secondary window The URL must be specified relative to the base address of the containing topic Example lt param name content value topicB glossary_def html gt id The ID of the topic displayed in the
85. name viewerActivator value Jjavax help LinkLabel gt param name viewerStyle value javax help Popup gt param name viewerSize value 300 400 gt param name text value Click here gt param name textFontFamily value SansSerif gt param name textFontSize value x large gt param name textFontWeight value plain gt param name textFontStyle value italic gt lt param name textColor value red gt lt OBJECT gt lt lt lt lt lt lt lt lt Supplemental Information The following information is provided to supplement the information in this topic Lightweight Java Components For general information about lightweight Java components see http java sun com products jdk 1 2 docs guide awt demos lightweight index html JavaHelp Components As a reference the sources to the lightweight components that implement JavaHelp system popups and secondary windows JHSecondaryViewer java and JHSecondaryViewerBeanInfo java can be found in src jar at com sun java javahelp impl For a description of how the lt OBJECT gt tag is used to implement popups and secondary windows see The JHSecondary Viewer Component HTML 4 0 Specification You can find a detailed description of the lt OBJECT gt tag as part of the HTML 4 0 specification http w3c org TR REC htm140 Creating Lightweight Java Components See also Using Popup and Secondary Windows The JHS
86. nd image background repeat background position background background repeat text decoration with the exception of blink and overline vertical align only sup and super text align justify is treated as center text indent margin top margin right margin bottom margin left margin padding top padding right padding bottom padding left border style only supports inset outset and none list style type ist style position The following styles are modeled but not rendered in JDK 1 2 2 ont variant background attachment background always treated as scroll word spacing etter spacing text transform ine height border top width indicates whether a border should be used border right width border bottom width border left width border width border top border right border bottom border left border width height float clear display white space ist style Changes Since the 1 0 Release 11 The lt tt gt and lt code gt tags now work correctly Client side maps lt MAP gt lt IMG USEMAP gt are supported The width attribute of the lt t d gt tag now works when specified in absolute pixels the use of percentages is still not supported The following exception does not occur Exception occurred during event dispatching java lang NullPointerException at javax swing text View preferenceChanged View java 121 at javax swing text html ImageView run ImageView java 414 The lt BR
87. nor not now of off on or our own see set shall she should so some than that the them then there these this those though to too us was way we what when where which who why will would yes yet you You can override the indexer s default stopword behavior in two ways Use the nostopwords option with the jhindexer command This forces the indexer to ignore stopwords and to index every word in your help topics Use the config file to specify your own list of stopwords Config File You can use the config file to Change the path names of the files as they are stored in the search database This is useful when you create the search database using paths to topic files that are different from the paths the help system will later use to find them Explicitly specify the names of the topic files you want indexed Specify your own list of stopwords Changing Path Names You can remove and prepend portions of the topic file names as they are stored in the search database This is useful when the path to the topic files you use during development is different from the path the help system will later use to find the topic files during searches gt To remove a portion of the path name from all of the indexed files Add the following line to the config file IndexRemove path where path is the portion of the path you want removed For example to change public_html JavaHelp demo docs file html to docs file html add the foll
88. nt platforms these references no longer work Packaging In addition to the topic files the help information includes metadata files that contain information about the help system Where you locate these metadata files can affect how you package deliver and update the help information for your users In JavaHelp systems there are two kinds of metadata Navigational data HelpSet data Navigational Data Navigational data files contain information that is used by the JavaHelp system navigators The standard JavaHelp system navigators are Table of contents i Q oO Pal PT ull text search Each of these navigators has a metadata file associated with it that contains navigational data These metadata files should be located in close hierarchical proximity to the topic files so you can conveniently package them into JAR files with the topic files for delivery to customers The following diagram displays an example Setting Up a JavaHelp System 58 help my_toc xml my_index xml WavaHelpSearch search dh files S stopic1 topic2 subtopicA subtopicA topic3 topic html topic html subtopicA topic html subtopic B subtopic B topic html topic html subtopicB topic html subtopicC topic html subtopicD topic html HelpSet Data HelpSet data is information that the JavaHelp system needs to run your help system It is contained in two files o Hepsi e Map ite When the Java
89. oaded to a browser environment that has neither the appropriate JRE nor the Javahelp system installed In this case the Java Plug in can be used to download the required JRE and the JavaHelp system standard extension classes The Java Plug in allows developers to specify a specific JRE on the HTML page that is required to run their applet If the correct JRE is not present on the user s system the Java Plug in software downloads the correct JRE and installs it on the user s system The new JRE is subsequently available to any applet that requires it Because the JavaHelp system is a standard extension to the Java platform the JavaHelp system classes can be downloaded along with the JRE Presentation and Deployment 47 Web Browser O o00000 a E JavaHela This topic intro duce the wer network great product P gt Help Data _ The HTML page that contains the applet tag is loaded into the browser The Java Plug in is downloaded It prompts user to download appropriate JRE and JavaHelp system classes JRE and JavaHelp system classes are downloaded from the server Java Plug in starts the JRE The applet is downloaded from the server and executed The user requests help The applet forwards the request to the JavaHelp system Help data is downloaded from the server and displayed in the JavaHelp system viewer or browser window Next Overview Topic Full text Search N OND MN B
90. od The other two methods are present only in JHelpNavigator For more information about these classes and methods refer to the JavaHelp API documentation API information can be viewed using a web browser doc api overview summary htm1 or by using the demos bin apiviewer command A demonstration program demos bin merge is included with the JavaHelp system release This program demonstrates how HelpSets can be merged and removed dynamically The sources for that program are available in demos src sunw demo merge JavaHelp System User s Guide Table of Contents JavaHelp System User s Guide JavaHelpgiS ystem User s Guide Release Information X s a The JavaHelp 1 1 Release Contents of the Release Contents of the Release EMT 2 SDK Features Tested Java Platforms Changes Since the 1 0 Release Changes Since the 1 0 Release Changes Since JavaHelp 1 1 Beta Search Example Localized HelpSets Example HelpSet Example HelpSets JavaHelp System User s Guide History of the Holidays The JavaHelp Libraries and Tools HTML Viewer Full text Search Context Sensitive Help Limitations on Running in Web Browsers JavaHelp 1 1 November 1999 OnNNAINANANAN AP PWWRK e NNNNNNNNNNNNNNNNWNWD PP RRR RRR rR ke OmoornrP PHP HRWWWWrR DOD TTTOOWDWAANIANANNW CO List of Files in the JavaHelp 1 1 Release List of Files in
91. ode il I alpha characters UserCode x X alpha characters subcode alpha characters For more information about the lang attribute please refer to the XML recommendation at the World Wide Web Consortium web site http w3c org XML HTTP Protocol If the XML file is provided by a server via the HTTP protocol the server can specify the language for that file using the HTTP Content Language header for example Content Language en US See also ocalizing Help Information ocalizing Help Presentation ocalizing HelpSets ocalizing HTML Datal ocalization and Fonts ocalizing the Full Text Search Database eel ual ow Localizing HTML Data 126 Localizing HTML Data The HTML data contained in topic files can be localized as specified in the HTML 4 0 specification http w3c org TR REC htm140 Both the character encoding and the language can be set Character Encoding Character encoding is an unambiguous mapping of the members of a character set letters ideographs digits symbols or control functions to specific numeric code values Character encoding can be set for HTML files in the following ways listed in order of precedence e HTTP protocol HTML KMETA gt declaration e HTML charset attribute on an external source not recognized by the JavaHelp system a Only one encoding can be specified for any file HTTP Protocol If the HTM
92. omponents If you do not use the HelpBroker set the locale of the JHelp components directly using their set Local methods Data Input in the Viewer There are two places in the JavaHelp system GUI where culturally dependent input is required Index Find and Search Query In both cases platform specific input methods are used Once text is entered in the Index Find or Search Query text boxes additional locale based processing is activated usually by pressing the Enter key In the Index Find case the input text is searched for within the index entries using locale based comparisons The locale used in Index Find is the locale of the Index navigator usually the locale of the application unless overridden using the JHelpIndexNavigator setLocale method In the Search Query case the input text and the locale of the Search navigator are passed to a HelpSearch class The HelpSearch class tokenizes the query text into words using the locale specific tokenizer The locale used in Search Query is the locale of the Search navigator usually the locale of the application unless overridden using the HelpBroker setLocale or JHelpSearchNavigator setLocale methods See also Localizing Help Information Localizing HelpSets ocalizing XML Data Localizing HTML Datal ocalization and Fonts Localizing the Full Text Search Database Localizing HelpSets 120 Localizing HelpSets The portal to all JavaHelp s
93. ontent pane and navigator components viewerl so changes generated by one component are reflected in the other component Note that the TOC can be created using either the HelpSet getNavigatorView method or the JavaHelpNavigator getNavigatorView method Both methods produce the same results however using HelpSet reduces the dependency on the GUI 5 Add the navigator to the container content add xnav Center classViewerIFrame setContentPane content Embedding JavaHelp Components See also Programming with the JavaHelp System Adding the JavaHelp System to Applications Implementing Context Sensitive Help 112 Creating Lightweight Java Components 113 Creating Lightweight Java Components This topic describes how you can create lightweight Java components and add them to HTML topics using the HTML lt OBJECT gt tag The last section in this topic contains references to supplemental information about lightweight components and the HTML lt OBJECT gt tag z References to supplemental information is included at the end of this topic Lightweight Components for HTML Topics Components intended for HTML topic pages are very similar to generic lightweight components Components that do not require information about the View or have setable parameters can be used without modification View Information Lightweight components that require information about the View must implement javax
94. orresponding topic is displayed in the content viewer Due to a bug in the underlying Swing component the TOC entry must be exposed expanded prior to the corresponding page being loaded in the content viewer or scrolling does not occur The index navigator now scrolls to display an index entry when its corresponding topic is displayed in the content viewer The search navigator has been synchronized with the TOC and index navigators Popups and Secondary Windows Titles of secondary windows are now correctly and consistently displayed in the secondary window title bar A memory Leak in JHSecondaryViewer was fixed Toolbar no Longer Detaches from the Help Window The viewer toolbar can no longer be detached from the viewer main window frame Removed the About Item from the IDE Demo Help Menu The About item was not used so it was removed from the IDE Demo Help menu Startup in Internet Explorer 5 The call to Window get Owner now uses reflection so that JavaHelp can load correctly in IE 5 Additional Localizations JavaHelp 1 1 is now localized in French and Chinese in addition to Japanese Russian and German The Page Setup dialog printing is now available in all locales Libraries Signed The JavaHelp libraries for example jh jar are now signed so they can used with the Java platform s mechanism for handling Optional Packages formerly known as extensions You can find more information about this mechanism at ht
95. ot get help on the the component with focus Limitations on Running in Web Browsers It is only possible to use the JavaHelp system in applets running in web browsers using JRE JDK1 1 6 or later with the Java Plug in JavaHelp does not run correctly in web browsers and the appletviewer due to a limitation in Swing 1 1 This limitation will be corrected in a future version of Swing In the meantime a description of how to work around this issue will be posted to the JavaHelp website Limitations and Bugs 29 Other Bugs Copy Paste on Solaris On Solaris systems follow these steps to copy and paste text from the help viewer 1 Highlight text in the viewer 2 Type Control C to copy the text 3 With focus in the target Solaris window press the Paste key jar Protocol Due to a bug the Java M 2 SDK jar protocol does not permit relative references to JAR files they must be fully qualified For example the following works correctly jar file c my_app help jar map jhm There is no way to make that reference relative from the location of a HelpSet file For that reason you must include the HelpSet and map files in the JAR file with the rest of the HelpSet Index Navigator If an index entry contains more that two hierarchical levels a turner mechanism like the one used in the TOC is added to the second n levels Popup Window Accessibility JavaHelp popup windows are not as accessible as they should be due to a bug in the
96. out invoking the help viewer Limitations and Bugs 24 Limitations and Bugs Start up Out of environment space error Win32 systems If you encounter an Out of environment space error while running any of the bat files you must increase the size of the environment table You can do this at the command line which is temporary or by editing a configuration file to make a permanent change which requires you to restart your computer To temporarily increase environment space enter the following at the DOS prompt command e 8192 To permanently increase environment space add the following line to the CONFIG SYS file and then restart your computer shell command com e 8192 p Once you ve increased the size of the environment table try running the HelpSet Viewer again HTML Viewer The JavaHelp HTML viewer is based on the Swing JEditorPane component HTML rendering differs somewhat depending on which version of Swing your application uses Differences between versions are noted below Images Distorted Occasionally images are distorted stretched Redisplaying the page corrects the problem You can avoid this problem by explicitly specifying height and width attributes with the lt IMG gt tag Classpath Limitations Due to Java security protocols it is not possible to reference images and files from your topics that are outside the classpath of your application or hsviewer For example if you start hsviewer
97. ow This makes it possible to reuse an active window Popups ignore this parameter Example lt param name viewerName value glossary_window gt iconByName The URL of a GIF JPEG image Images can be used in two ways The JHSecondaryViewer Component 96 The user clicks on an image to activate a window In this case iconByName is used in conjunction with the following parameter lt param name VviewerActivator value javax help LinkLabel gt The images added to the standard button the user clicks on to activate a window In this case iconByName is used in conjunction with the following parameter lt param name viewerActivator value Jjavax help LinkLabel gt Example lt param name iconByName value topicB glossary_icon gif gt iconByID The ID of a GIF JPEG image The ID must be defined in the map file for that HelpSet Images can be used in two ways The user clicks on an image to activate a window In this case iconByID is used in conjunction with the following parameter lt param name viewerActivator value javax help LinkLabel gt The images added to the standard button the user clicks on to activate a window In this case iconBy ID is used in conjunction with the following parameter lt param name viewerActivator value Jjavax help LinkLabel gt Example lt param name iconByID value gloss_icon gt text The string of text that the user clicks on
98. owing line to the config file The jhindexer Command 85 IndexRemove public_html JavaHelp demo gt To prepend a different path to the indexed files Add the following line to the config file IndexPrepend path For example to change docs file html to my_product install docs file html add this line to the config file IndexPrepend my_product install Specifying Files for Indexing You can also explicitly specify a list of the names of the files you want indexed In the config file specify the list in the following format File filename File filename File filename Dy Be sure to use as the file separator when specifying files for indexing Specifying Stopwords You can specify your own list of stopwords to the indexer using the config file When you specify your own list the default stopword list is not used You can specify a list of stopwords in two ways Add the list of words directly into the config file using the following format StopWords word word word Inthe config file specify the name of a file that contains a list of stopwords StopWordsFile filename StopWordsFile must contain a list of stopwords one stopword per line The jhindexer Command gt See also Creating the Full Text Search Database The jhsearch Command Localizing the Full Text Search Database 86 The jhsearch Command 87 The jhsearch Command The javahelp bin jhsearch command is a command
99. p system source files UninstallerData Information used by InstallAnywhere to uninstall JavaHelp software Uninstall_jhl_0fcs Program used to uninstall JavaHelp software doc Documentation doc images Images used in documentation doc jhug HelpSet folder for the JavaHelp System User s Guide doc jhug pdf PDF version of the JavaHelp System User s Guide doc api JavaHelp 1 1 javadoc API documentation doc css default css 1 2 2 JEditorPane default stylesheet doc spec Latest version of the spec javahelp JavaHelp system binaries and libraries system release javahelp lib JavaHelp libraries javahelp lib jh jar Standard JavaHelp libraries javahelp lib jhbasic jar Subset of jh jar that does not include search engine javahelp lib jhtools jar Tools required to build and query the search database javahelp lib jhall jar Everything javahelp lib jsearch jar The default search engine only javahelp lib dtd DTDs for JavaHelp system XML metadata files javahelp lib dtd helpset_1_0 dtd HelpSet file DTD javahelp lib dtd index_1_0 dtd Index file DTD javahelp lib dtd map_1_0 dtd Map file DTD javahelp lib dtd toc_1_0 dtd TOC file DTD javahelp bin JavaHelp executable programs javahelp bin jhindexer Creates the search database javahelp bin jhsearch Queries the search database javahelp bin jhwrap Auxiliary wrapper script swing swingall jar demos demos browser demos README
100. pics topic3 subtopicA topic html extracted topics topic3 subtopicB topic html extracted topics topic3 subtopicC topic html extracted topics topic3 subtopicD topic html Note that it is not necessary to extract files from the JAR file to use them with the JavaHelp system The JavaHelp system reads files directly from the JAR file as they are required The JAR Protocol The Java 2 SDK implements a protocol for referring explicitly to files within JAR files The syntax of the jar protocol is jar lt url gt entry The jar protocol can be used to refer to entries within JAR files the entire JAR file or a directory as base URLs JAR directory Examples An entry within a JAR file JAR Files jar http www foo com bar baz jar COM foo Quux class A JAR file jar file www foo com bar baz jar A JAR directory jar file www foo com bar baz jar COM foo z 1 is referred to as the separator For more information refer to the J ava TM 2 SDK documentation See also he HelpSet File he Map File able of Contents File Q reating the Full Text Search Database 72 Table of Contents File 73 Table of Contents File The table of contents TOC file describes to the TOC navigator the content and layout of the TOC The format of the TOC file is based on the World Wide Web Consortium Extended Markup Language XML The following is a very small example of a TOC file lt xml version
101. ponent and JHelpNavigator are changed public HelpSet getHelpSet Gets the current HelpSet for the HelpBroker public void setCurrentID Map ID id throws BadIDException Sets the current ID that is to be displayed in the help viewer If hs is null the HelpBroker s current HelpSet is used If hs is different than the current HelpSet and not contained in the current HelpSet the setHelpSet method is executed public void setCurrentURL URL url HelpSet hs throws BadIDException Displays the specified URL in the help viewer If hs is null the HelpBroker s current HelpSet is used If hs is different than the current HelpSet and not contained in the current HelpSet the setHelpSet method is executed public void enableHelpKey Component comp String id HelpSet hs Enables the Help key on a Component This method works best when the component is the rootPane of a JFrame in Swing based applications or a java awt Window or subclass thereof in AWT based applications This method sets the default helpID and HelpSet for the Component and registers keyboard actions to trap the Help keypress If the object with the current focus has a helpID the helpID is displayed when the Help key is pressed otherwise the default helpID is displayed public void enableHelp Component comp String id HelpSet hs Enables help activation for a help component for example a Help button This method Registers the helpID and HelpSet on comp
102. popup or secondary window The ID must be defined in the map file for that HelpSet Example lt param name id value gloss_def gt viewer Activator Specifies how the user activates the window see Using Popup and Secondary Windows for details about activation Valid values are The JHSecondaryViewer Component 95 javax help LinkButton User activates the window by clicking on the standard button provided as part of the popup secondary window lightweight component You can use the parameter to add text to the button or you can use the or iconByID parameters to add images to the button javax help LinkLabel User activates the window by clicking on a text object or GIF JPEG image The text object is specified by means of the text parameter and the image is specified by means of the and i conBy 1D parameters Examples lt param name viewerActivator value Jjavax help LinkButton gt lt param name viewerActivator value javax help LinkLabel gt viewerSize The width and height in pixels of the window Example lt param name viewerSize value 300 400 gt viewerLocation secondary windows only The x y position in pixels of the upper left corner of the secondary window on the screen 0 0 being the upper left corner of the screen Popups ignore this parameter Example lt param name viewerLocation value 300 400 gt viewerName secondary windows only Names a wind
103. r applets It permits developers to use alternate search engines for example Excite or Lycos and can be quicker to start because the search database is not downloaded it is especially fast if the search engine is already running on the server Note that this approach works very well with Java servlets Next Overview Topic JavaHelp System Lightweight Components JavaHelp System Lightweight Components 51 JavaHelp System Lightweight Components Functionality can be added to help topics using the lightweight component facility Lightweight components are similar to Java applets but are lighter weight and load and execute more quickly The first release of the JavaHelp system includes a lightweight component that implement popup windows and secondary windows For more information about popup windows and secondary windows see Popup and Secondary Windows Lightweight components can also be created by Java language developers to add functionality such as animation and multimedia to help topics The Java 2 Platform includes high quality audio and a video viewer that supports the common formats For more information see Creating Lightweight Components Authoring Help Information 52 Authoring Help Information The topics in this chapter of the JavaHelp System User s Guide describe the aspects of the JavaHelp system of primary interest to online help authors These topics assume that the author is responsible for creating the metadata
104. rr println trouble with visiting id tee Implementing Context Sensitive Help Sample Code 110 The following example shows the code required for the different types of context sensitive help using a default HelpSet try ClassLoader cl ApiDemo class getClassLoader URL url HelpSet findHelpSet cl helpsetName mainHS new HelpSet cl url catch Exception ee System out println Help Set thelpsetName not found return catch ExceptionInInitializerError ex System err println initialization error ex getException printStackTrace mainHB mainHS createHelpBroker Enable window level help on RootPane rootpane frame getRootPane j mainHB enableHelpKey rootpane top null Enable field level help on various components JToolBar toolbar new JToolBar CSH setHelpIDString toolbar toolbar main Enable Menu Button help on Help menu item helpbutton addButton toolbar images help gif help mainHelpBroker enableHelpButton helpbutton browser strings sourceIFrame new JInternalFrame Source true true true CSH setHelpIDString sourceIFrame edit editsource JTextArea newtext new JTextArea CSH setHelpIDString newtext build build newtext new JTextArea j CSH setHelpIDString newtext debug overview newtext new JTextArea j CSH setHelpIDString newtext browse strings System Level help
105. s and tools are located in the javahelp folder of the release All classes work with both JDK1 1 and the Java 2 Platform Standard Edition and use Swing 1 Libraries The JavaHelp classes are distributed in five different JAR files The JAR files are located in the javahelp lib folder jhjar jhbasic jar jhtools jar jhall jar jsearch jar Tools The standard library it includes everything needed to use the standard navigator types TOC index full text search A subset of jh jar that does not include support for the full text search engine This may be useful for very simple help systems that do not require a full text search database or help systems where size is critical Contains the classes needed to build and query the full text search database Contains all of the JavaHelp system classes including the tools required to create a search database Contains the default full text search engine used in the JavaHelp system The JavaHelp tools are used to view HelpSets and to build and query the full text search database These tools are located in the javahelp bin folder jhindexer Command line program that creates the full text search database used by the JavaHelp system full text search navigator to locate matches Command line program that queries the JavaHelp system full text search database created with the jhindexer command The jhsearch command can be used to verify the validity of a search database with
106. se the hsviewer command to view HelpSets You can start this program from a shortcut program group desktop icon link that you created during installation When the program starts specify the name of a HelpSet file and the path to that HelpSet file You can also use the file chooser to load a HelpSet Browse button Once loaded click Display to view the HelpSet in the JavaHelp system viewer You can also use the hsviewer command demos bin hsviewer exe to create batch files or script files that automate the viewing process The following describes the syntax of the hsviewer command line interface hsviewer helpset hs_name hs_path hs_jar classpath path Viewing HelpSets 54 helpset Specifies the HelpSet in one of the following ways hs_name_ The name of a HelpSet file The hsviewer searches the CLASSPATH and loads the first HelpSet file it encounters with that name For example C gt hsviewer helpset HolidayHelpSet hs hs_path The path to a HelpSet file For example C gt hsviewer helpset C jh1 0 demos hs holidays HolidayHistory hs hs_jar The path to a JAR file that contains a HelpSet hsviewer searches the JAR file and loads the first HelpSet file hs it encounters For example C gt hsviewer helpset C jh1 0 demos hsjar holidays jar classpath Augments the CLASSPATH to include the path to your HelpSet file or JAR file Use the helpset option to specify the HelpSet file name For example C g
107. see the online help available from the Help menu in the merge demo program gt Torun the Merge demo Windows 95 and Windows NT demos bin merge Solaris demos bin merge Browser Demo Demonstrates how the JavaHelp system can be used with applet based applications running in web browsers The demonstration can be run using both Navigator 4 and Internet Explorer 4 The demo creates an applet button on an HTML page when the button is clicked the JavaHelp viewer displays the holiday HelpSet This demo requires some setup Instructions for the demo can be found in demos browser demo_instructions Search Example The file demos src sunw demo searchdemo ClientSearch java shows how to extend the HelpSearch class to implement an alternate search engine Demonstration Programs 19 Localized HelpSets Localized demonstration HelpSets English German Japanese are included in the demos hs il8n folder Be sure to use the JavaHelp viewer Options gt Set Fonts dialog box to choose the appropriate font Dy The appropriate Unicode fonts must be installed to view the Japanese HelpSet Example HelpSets 20 Example HelpSets This release includes a variety of HelpSets packaged in different ways Many of these HelpSets are used by the demonstration programs but you can also use the psviewer command to view them HelpSets are described in detail injAuthoring Help Information You can view these HelpSets to familiarize yourself with the
108. so ocalizing Help Information a iw E al iw 4 Merging HelpSets 130 Merging HelpSets The JavaHelp system provides a mechanism for merging HelpSets You can use the merge functionality to append TOC index and full text search information from one or more HelpSets to that of another HelpSet An example of where this functionality might be useful is in an application suite The application suite may consist of a collection of constituent applications As constituent applications are purchased and installed their help information can be merged with help information from the other applications in the suite HelpSets can be merged statically or Static Merging To merge HelpSets statically add lt subhelpset gt tags to a master HelpSet file to specify other HelpSets that you want to merge with the original HelpSet The merge operation is performed whenever the containing HelpSet is instantiated In the following simple example HelpSet2 is merged with HelpSet1 to produce the unified TOC display shown below HelpSet1 hs lt xml version 1 0 encoding ISO 8859 1 gt lt DOCTYPE helpset PUBLIC Sun Microsystems Inc DID JavaHelp HelpSet Version 1 0 EN http java sun com products javahelp helpset_1_0 dtd gt lt helpset version 1 0 gt lt title gt HelpSet 1 lt title gt lt maps gt lt homeID gt hs1_filel lt homeID gt lt mapref location hs1l jhm gt lt maps gt lt v
109. t flexibility in customizing both the user interface and functionality Merging Help information from different sources can be combined and presented to the end user JavaBeans Support The JavaHelp API permits a JavaBeans component to specify help information that can be presented to the end user perhaps merged with additional information Next Overview Topic Descriptive Scenarios Scenarios 38 Descriptive Scenarios The following scenarios illustrate some of the many ways the JavaHelp system can be used to provide online help for different types of Java programs in a variety of network environments These scenarios attempt to illustrate the JavaHelp system s flexibility and extensibility Scenarios are presented in three areas nvocation Scenarios that describe different ways that the JavaHelp system can be invoked from applications O T jes 5 n a Scenarios that describe different ways that the JavaHelp system can be used to eployment present help information These scenarios also illustrate different methods for deploying the JavaHelp system classes and help data li Full text search Scenarios that describe different ways that full text search of help information can be implemented Next Overview Topic JavaHelp System Lightweight Components Invocation Mechanisms 39 Invocation Mechanisms Users invoke online help from within applications in a number of ways This section describes
110. t hsviewer helpset HolidayHistory hs classpath C jh1 0 demos hs holidays C gt hsviewer helpset HolidayHistory hs classpath C jh1 0 demos hs holidays holidays jar The trailing on the classpath argument is required If no arguments are specified on the command line the graphical interface is used JDK1 1 Systems For systems running JDK1 1 the following scripts are provided for viewing HelpSets no graphical interface is available Win32 hsviewerl_1 bat Solaris hsviewer The hsviewer1_1 commands work from the command prompt and require two arguments The name of a HelpSet file The path to the folder or JAR file where that HelpSet file is located For example to view a HelpSet named Viewing HelpSets C jh1 0 demos hs holidays HolidayHistory hs use the following command C gt hsviewerl_1 HolidayHistory hs C jh1 0 demos hs holidays 55 Setting Up a JavaHelp System 56 Setting Up a JavaHelp System There are two primary things to consider when you set up your help system How best to organize help information files to organize them logically and conveniently for authoring e How to organize help information to best package it for delivery to your users Authoring The JavaHelp system is fidi based topics are contained in files that are displayed in the help viewer one file at a time It is a good idea to group related topics together to keep them organized and to make
111. t to lowest eeood The number in the second column indicates the number of times the query was matched in the listed topic The text specifies the name of the topic as specified in the topic s lt TITLE gt tag in which matches are found Full Text Search 80 z To avoid confusion be sure the lt TITLE gt tag corresponds to the title used in the table of contents Relaxation Ranking The search engine uses a technique called relaxation ranking to identify and score specific passages of text that are likely to answer the user s query The relaxation ranking algorithm compares the user s query terms with occurrences of the same or related terms in the help topics The search engine attempts to find passages in the help topics in which as many as possible of the query terms occur in the same form and the same order The search engine automatically relaxes these constraints to identify passages in which Not all of the terms occur The terms occur in different forms The terms occur in a different order The terms occur with intervening words The search engine assigns appropriate penalties that lower the ranking to the passages for these deviations from the specified query p3 The ranking process improves when queries are more complex and include more information Morphing The JavaHelp search engine uses morphing technology to find words with common roots For example when the term
112. tage of locating the HelpSet file outside of the JAR file is that it can be updated independent of the rest of the HelpSet For example additional help information can be added to the user s help system by adding more JAR files and updating the HelpSet file Map File Excluding the map file from the JAR file is possible but usually not useful Setting Up a JavaHelp System lt maps gt HelpSet File lt mapref location c app help MymMap jhm gt lt maps gt lt maplD target file1 url Jar file c vappshelp Ajar jar File1 html gt lt maplD target file2 url Jar file c vappshelp Ajar jar File2 html gt File1 htnl File2 html lt HI gt Introduction lt fHI gt lt P gt This topic introduces che user to lt HIi gt Getting Started lt fHi gt lt P gt In order to install this product you must 61 If the map file is located outside of the JAR file all URLs in the map must use the jar protocol For example jar file c product help Ajar jar Filel html The JavaHelp system actually deals with URLs The URL may resolve to the contents of a file in a File system a file on the web a portion of a JAR file or may even be generated dynamically by a server See also The Map File AR Files able of Contents File ndex File fa Setting Up a JavaHelp System Creating the Full Text Search Database 62 The HelpSet File 63 HelpSet File When the
113. tants html Using Parameters If your component takes parameters you should follow these two additional steps 1 Add accessor methods for each setable parameter 2 Create a BeanInfo class that corresponds to the lightweight component class The component must accept parameter elements in any order Accessor Methods Add accessor methods that enable the component to access the parameters through the Java reflection mechanism In the following example the AButton class has implemented accessor methods for the parameter data in the methods getData and setData private String data public void setData String s data s public String getData return data z Even if the internal representation is not a String both the returned value for the getter method and the parameter in the setter must be a String BeanInfo Class Create a BeanInfo class that provides explicit information about the lightweight component The only method used by the ContentViewer from the BeanInfo classes is get PropertyDescriptors In the complete example below JHSecondary ViewerBeanInfo defines the property data accessible through the getData and setData methods in JHSecondary Viewer public class JHSecondaryViewerBeanInfo extends SimpleBeanInfo public JHSecondaryViewerBeanInfo Creating Lightweight Java Components 115 public PropertyDescriptor getPropertyDescriptors PropertyDescriptor
114. the HelpSet file automatically inherit the locale For example lt helpset xml lang fr gt The locale specified for the HelpSet in this manner overrides any locale acquired from the system or the application For this reason it is the most reliable means for setting the HelpSet locale The locale of the lt title gt element is always the same as locale of the HelpSet Any xml lang attributes specified for the lt t it le gt element are ignored Localizing HelpSets 122 Navigation View Locale The xml lang attribute can also be used to change the locale of the navigator views specified in the lt view gt elements for example the TOC and index Note however that this locale is overridden by any locale settings specified by xml lang attributes in the TOC and index XML definition files as described in XML Data The locale of the lt label gt element is always the same as the locale of the containing view Any xml lang attributes specified for lt label gt elements are ignored Shipping Multiple Locales JavaHelp makes it possible to simultaneously distribute multiple localized HelpSets for example German French and English As described the HelpSet findHelpSet method determines the correct HelpSet file based on the system s locale or as set by the application using HelpBroker setLocale You can include multiple localized HelpSet files and locate the appropriate version using this naming convention If you ship mul
115. through an RPC mechanism the RPC may be wrapped in a library and be invisible to the application developer Presentation and Deployment 44 App 1 Help Data d lt HI maHalp lt fH1 gt lt P gt This topic intro duces the wer w great product P gt This topic intro dure the wer w 4 great product P gt App 2 Help Data Browser Based Applications Applets Applications that run in browsers have a number of unique deployment issues that the JavaHelp system addresses The following three scenarios illustrate how the JavaHelp system can be used in three of the most common cases In the following scenarios an applet or some other triggering entity on an HTML page requests the JavaHelp system to display help information Applet 1 In the first scenario the browser contains a customized implementation of the JavaHelp system and an appropriate version of the JRE Java Runtime Environment This JRE may have been delivered with the browser or it may have been downloaded by the client into the CLASSPATH The implementation may use the JavaHelp system content pane or it may use the HTML viewer that is part of the web browser Presentation and Deployment 45 Web Browser e oooo0oo0o0 miia JavaHela d 4 cHi gt faveHelp lt H1 gt lt P This topic intro duce the wer network J Apea podar Help Data The HTML page that contains the applet tag is loaded into the browser
116. tiated Help Full Text Search Nn 4 Q 4 52 52 53 53 53 54 56 56 56 56 57 57 57 58 63 63 63 64 67 67 67 69 69 69 69 70 70 70 71 71 73 73 73 75 75 75 77 77 77 77 77 77 78 78 78 79 Full Text Search How Searching Works Relaxation Ranking Creating the Full Text Search Database Creating the Full Text Search Database The jhindexer Command Specifying Files for Indexing Specifying Stopwords The jhsearch Command The jhsearch Command Using Popup and Secondary Windows _ Differences Between Popups and Secondary Windows The JHSecondary Viewer Componen a ears The JHSecondary Viewer Componen is t Parameter Definitions Programming with the JavaHelp System Programming with the JavaHelp System Adding the JavaHelp System to Applications Adding the JavaHelp System to Applications Implementing Context Sensitive Help Implementing Context Sensitive Help Basic Elements etting and Getting Component Help Properties racking Context Sensitive Events Implementing Context Sensitive Help The HelpBroker HelpBroker Context Sensitive Methods SH Inner Classes I 72 Q System Initiated Help Sample Code Embedding JavaHelp Components Embedding JavaHelp Components Creatin
117. tiple locales you will probably organize your help information a little differently than is described in Setting Up a JavaHelp System The following diagram shows one way you can organize the help information by locale help my_helpset hs my_helpset_de hs my_helpset_fr hs J Wefault wde Vir my_map jhm my_map jhm my_map jhm my_toc xml my_toc xml my_toc xml my_index xml my_index xml my_index xml WavaHelpSearch WavaHelpSearch WavaHelpSearch search db files search dh files search db files topics topics topics topic topicA topicA topic html topic html topic html topicB topicB topicB topic html topic html topic html Note that the paths specified in the lt data gt sections of the localized HelpSet files must point to the appropriate locations For example Localizing HelpSets 123 lt maps gt lt mapref gt location de Map jhm gt lt maps gt lt view gt lt name gt TOC lt name gt lt label gt Holidays lt label gt lt type gt javax help TOCView lt type gt lt data gt de HolidayTOC xml lt data gt lt view gt Merging Localized HelpSets JavaHelp system HelpSets can be merged The locale of a HelpSet is maintained in a merge operation For instance if the master HelpSet locale en_US is merged with another Helpset locale fr_FR the locale of both HelpSets is maintained Map Data Map data should not be localized If IDs target attribute are localized they will no longer mat
118. tive Help Window Level Place the cursor in different areas of the Help application and press the F1 key This activates the help viewer and displays help that describes the GUI object that currently has focus Field Level Click on the ka button then move the field level Help cursor gt over an object in the GUI and click Java TM 2 Platform only select Help Button Choose Edit gt Find Click on the Help button in the dialog box to display a topic about the dialog box Demonstration Programs 17 Custom Choose Help gt Java API Reference This activates the help viewer and loads Navigator a HelpSet that includes the customized ClassViewer navigator The Class Viewer is an example of a navigator that is customized to assist in navigating through javadoc generated API documentation The behavior of the ClassViewer is described at API Viewer It is a fully functional navigator with its own specialized format Embedded Help Choose Window gt Class Inspector This activates the custom Class Viewer navigator described above but embeds it within the application Note that as you navigate the corresponding topic is displayed in the lower pane of the application gt Torun the IDE demo Windows 95 and Windows NT demos bin idedemo exe Solaris demos bin idedemo Once the demo starts choose Help gt Demo JDE Help to activate the help viewer Object Demo Lightweight Java components can be added to HTML topic pages
119. to nest the anchor within a tag For example lt H2 gt Working With Widgets lt A NAME widgets gt lt H2 gt Cascading Style Sheets Tag names in styles and style sheets must be specified using lowercase letters or they are ignored lt P gt and lt BR gt Tags In some cases for example within lt UL gt and lt OL gt lists the lt P gt tag does not create the expected vertical space In these cases the lt BR gt tag does incorrectly create the expected vertical space The lt SUP gt lt SUB gt Tags JDK1 2 2 The lt SUP gt lt SUB gt tags are ignored on JDK 1 2 2 systems Limitations and Bugs 26 The Width Attribute of the lt TD gt Tag The width attribute of the lt TD gt tag is ignored on JDK 1 2 The viewer assigns its own width to table columns On JDK 1 2 2 the width attribute works when specified in absolute pixels the use of percentages is not supported Named Anchors in Ordered and Unordered Lists If the first item after a list tag lt UL gt lt OL gt lt DL gt is a named anchor lt A NAME gt the list is rendered incorrectly This list is rendered incorrectly lt ul gt lt a name 17539 gt lt a gt lt li gt Transmitter reports lt a name 17540 gt lt a gt lt li gt Channel reports lt ul gt This one is rendered correctly lt ul gt lt li gt Transmitter reports lt a name 17539 gt lt a gt lt li gt Channel reports lt a name 17540 gt lt a gt lt u
120. tp java sun com products jdk 1 2 docs guide extensions spec html http java sun com products jdk 1 3 docs guide extensions spec html http java sun com docs books tutorial ext index html Demonstration Programs 15 Demonstration Programs This release includes a number of demo programs including source code and examples These programs demonstrate JavaHelp system functionality and provide code examples that illustrate how you can implement these features in your JavaHelp systems IDE demo A mock up of an Integrated Development Environment application The application includes a complete functional help system A demonstration of how the lt OBJECT gt tag can be used to embed Java components directly into HTML topic pages The JavaHelp system includes two components a popup window and a secondary window A specialized help viewer that includes a navigator that displays JavaHelp system API documentation gt O z Q rae i Q oO S lt a 3 g 5 jo A small application that demonstrates the dynamic merging of HelpSet information w S e wn Q A demonstration of the JavaHelp viewer running in an applet on a web browser Q oO B Source file that describes a simple alternate implementation of a full text search engine Localized Localized demonstration HelpSets English German Japanese D Source files for all of the demos can be found in mo oa a BIE 5 n 5 1c nw Q e n G
121. underlying AWT classes that prevents the popups from obtaining focus Popup windows can be accessibly dismissed by pressing the F10 key the Esc key does not work because the window cannot obtain focus In addition this same bug prevents scrollbars in popup windows from being accessible from the keyboard therefore it is important to set the size of popups so that all the information can be displayed in a single scroll zone Fonts Localization There are limitations in this release on the ability to display fonts in the help viewer content pane Due to a bug in the JDK the only character encoding that can be displayed in the HTML content pane is the system default Different locales that use that encoding are rendered correctly Installation If you uninstall the JavaHelp release while you are viewing any of the release directories using Explorer the MSDOS command prompt or Solaris shell the directories are not removed List of Files in the JavaHelp 1 1 Release 30 List of Files in the JavaHelp 1 1 Release The libraries include in this release support both JDK1 1 and the Java 2 Platform They should run in any JDK1 1 compliant Java platform The software uses Swing 1 1 which is included Launch programs are included for tools and demonstration programs the Win32 versions have the exe extension the Solaris versions have no extension README Initial README file LICENSE txt License file src jar JavaHel
122. users The JavaHelp system uses the JAR Java ARchive format for encapsulation and compression The JAR file format is based on the popular ZIP file format The JavaHelp system automatically extracts information from the JAR file when it is required Until support is available from GUI base help authoring tools the jar command located in the JDK bin folder must be used from a command line prompt to create read and extract data from JAR files Sample Help Hierarchy The following sections refer to this sample help hierarchy help my_helpset hs my_map jhm my_toc xml my_index xml WavaHelpSearch DOCS DOCS TAB OFFSETS POSITIONS SCHEMA TMAP E topic1 topic2 topic3 subtopicA subtopicA subtopicA topic html topic html topic html subtopicB subtopicB subtopicB topic html topic html topic html subtopic C topic html subtopicD topic html JAR Files 70 The jar Command The jar command syntax is jar ctxvfm jar file manifest file files Option flags are c create new archive list table of contents for archive extract named or all files from archive generate verbose output on standard error specify JAR file name include manifest information from specified manifest file Bms KX ct For more detailed information about the jar command or format please refer to http java sun com beans jar html z The jar command is located in the bin directory of the JDK Creating JAR Files To create a
123. using the lt OBJECT gt tag The JavaHelp system includes popup and secondary windows implemented using the JHSecondary Viewer component The object demo shows how popup and secondary windows work gt Torun the Object demo Windows 95 and Windows NT demos bin object exe Solaris demos bin object API Viewer The JavaHelp release includes an API Viewer This simple application is similar to the HelpSet viewer except that the CLASSPATH includes a special ClassViewer navigator The API Viewer presents javadoc generated information derived from the JavaHelp source files Demonstration Programs 18 The TOC in the API Viewer the Class Viewer navigator includes a top pane and a bottom pane The top pane displays a list of the classes interfaces and exceptions that comprise the JavaHelp system The bottom pane displays a hierarchy of components of a selected class interface or exception Select a class in the top pane to view its constituent components in the bottom pane Choose a component in the bottom pane to view it in the content viewer The data used by the ClassViewer Navigator is generated using a doclet doclets are a feature of the Java 2 SDK The API doclet is not included in this release of the JavaHelp system gt Torun the API Viewer demo Windows 95 and Windows NT demos bin apiviewer exe Solaris demos bin apiviewer Merge Demo Demonstrates JavaHelp system HelpSet merging capabilities For details
124. ute location URL of the HelpSet file to be merged The HelpSet File gt See also The Map File Table of Contents File Index File Creating the Full Text Search Database 66 The Map File 67 The Map File When the JavaHelp system is activated by your application the first thing it does is read the application s HelpSet file the next thing it does is read the map file listed in the HelpSet file The map file is used to associate topic IDs with URLs paths to HTML topic files By convention map file names include the Jhm suffix The format of the map file is based on the World Wide Web Consortium Extended Markup Language XML The following is an example of a short map file lt xml version 1 0 encoding ISO 8859 1 gt lt DOCTYPE map PUBLIC Sun Microsystems Inc DID JavaHelp Map Version 1 0 EN http java sun com products javahelp map_1_0 dtd gt lt map version 1 0 gt lt mapID target toplevelfolder url images toplevel gif gt lt mapID target hol_intro url hol hol html gt lt mapID target halloween url hol hall html gt lt mapID target jackolantern url hol jacko html gt lt mapID target jacko_carving url hol jacko html carving gt lt mapID target mluther url hol luther html gt lt mapID target reformation url hol inforefo html gt lt mapID target fawkes url hol guy html gt lt mapID target th
125. w works correctly with modal dialogs when the dialog is activated cancelled and then activated again To prevent the help viewer from being blocked when activating a modal dialog add the following code to the actionListener if HelpBroker isDisplayed HelpBroker setActivationWindow modalDialog HelpBroker setDisplayed true To prevent the same dialog being reactivated and blocking the help viewer when deactivating a modal dialog through a button add the following code to the actionListener if HelpBroker isDisplayed HelpBroker setActivationWindow null HelpBroker setDisplayed false If a help viewer is up and a modal dialog is active the help viewer is blocked The following code works around the problem if applied during the activation of the modal dialog if hb isDisplayed DefaultHelpBroker hb setActivationWindow modal hb setDisplayed true HelpBroker setSize The setSize method no longer ignores size requests during creation of the presentation or if the presentation was already displayed Search Navigator When using the Windows look and feel the search navigator did not display the number of matches found in topics This is fixed Fixed the problem that prevented search icons circles from being loaded when running JavaHelp in Internet Explorer Changes Since the 1 0 Release 14 Navigator Synchronization The TOC navigator now scrolls to display a TOC entry when its c
126. ystem help information is the HelpSet file which defines the HelpSet The HelpSet is the set of data that constitutes your help system and includes HelpSet file XML Map file XML TOC definition file XML Index definition file XML Topic files HTML Full text search database All HelpSet data can be localized often in multiple ways The process of localizing HelpSets can be viewed as a cascading process where each level of the cascade becomes more specific and takes precedence over the levels above it The following diagram shows the different levels in the JavaHelp system where the locale can be set and localization can occur starting with the host application and moving into the HelpSet Changes to locale are propagated down the hierarchy with a change at each level overriding the locale set above it Application default locale HelpSet File lt helpset xml lang gt Navigation Views HTML Files lt view xml lang gt HTTP protocol XML Files HTML Files HTTP protocol lt MET A gt XML prolog HTML Hements lt P lang gt XML Elements lt toc xml lang gt lt index xml lang gt XML Elements lt tocitem xml lang gt lt indexitem xml lang gt Legend C Described in Localizing Help Presentation Localizing HelpSets 121 C Described in the following sections C Described in Localizing XML Datal Described in Localizing HTML Data The HelpSet File

JavaHelp System User's Guide

Contents

Download Pdf Manuals

Related Search

Related Contents