This is NSHelpPanel.rtf in view mode; [Download] [Up]
paperh18648 margl-907 margr0 margt0 margb0 fi0 ri0 ql sb0 f1 fs24 Copyright f3 'e3f1 1994 by NeXT Computer, Inc. All Rights Reserved.
s4 li100 fi0 ri1007 ql f0 b fs36 fs100
fs36 NSHelpPanel
pard s11 li2872 fi-2771 ri1007 ql tx2872 f1 b0 fs28 fs48
fs28 f0 b fs24 Inherits From:tab b0 fs28 f1 NSPanel : NSWindow : NSResponder : NSObject
fs20
fs28 s6 f0 b fs24 Conforms To:tab b0 fs28 f1 NSCoding (NSResponder)
fi0 NSObject (NSObject)
fs20
fs28 s7 fi-2771 f0 b fs24 Declared In:tab b0 fs28 f1 AppKit/NSHelpPanel.h
fs20
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs28 fs20
fs28 Class Description
fs14
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs2
fs28 The NSHelpPanel class is the central component of the OpenStep help system. It provides the Help panel that displays the text and illustrations that constitute your application'27s help information. The NSHelpPanel class object itself stores the table of associations between an application'27s user-interface objects and specific passages of the help text.
fs16
fs28 Users can display the Help panel by choosing the Help command from an application'27s Info menu. The panel employs the metaphor of a book: It displays a table of contents, body text, and an index. Users can browse through the text by clicking entries in the table of contents or index. The panel also supports hypertext-like help links, which appear as diamond-shaped images within the text and allow the user to easily follow cross references. By using the help cursor and clicking user-interface objects, the user can query the Help panel for information associated with those objects.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 The Help Text
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 An NSHelpPanel object looks in a language-specific directory within the application'27s file package for the text that it will display. (Some implementations may employ more efficient means of storage than files and directories.) For example, if the user'27s language preference is English, the panel searches for a directory named b Helpb0 within the b English.lprojb0 directory of the application'27s file package. It searches for two files: b TableOfContents.rtfb0 and b Index.rtfdb0 . There may also be one or more files containing the body text that the Help panel will display. The table-of-contents, index, and body files are interconnected byi i0 a system of i help linksi0 and i help markersi0 .
fs16
fs28 A help marker is a named position holder in the stream of text'd0in most cases, it'27s invisible to users. A help link is a diamond-shaped button embedded in the text. Help links store a file name and, optionally, a help marker name. When a user clicks a help link, the Help panel displays the named file. If the help link also stores a marker name, the displayed file is scrolled to the position of the marker, and the text is selected from the marker'27s position to the end of the line.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Table-of-Contents and Index Files
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 The table-of-contents and index files are specially designed documents in Rich Text Format (RTF). An NSHelpPanel object identifies these files by name (b TableOfContents.rtfb0 and b Index.rtfdb0 ) and processes them differently than it does other help files.
fs16
fs28 The table-of-contents file should contain one entry for each help text file in the help directory. Each entry begins with a help link that stores the name of the destination file for that entry. Following the link is the text of the entry, which may wrap and span several lines. Although the table of contents in the Help panel looks like it'27s displayed by an NSMatrix, it'27s actually displayed by a modified NSText object. Thus, you can use the full generality of RTF to format your table of contents.
fs16
fs28 The index file is structured similarly although there is no enforced one-to-one mapping. Generally, the help link that begins an index entry stores both a file name and a marker name, since an index entry usually points to a specific word or phrase within a file.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Generic Help Files
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 An application'27s Help directory can contain only table-of-contents and index files, and yet the application may be able to display numerous help subjects, each of a general nature. This is because OpenStep applications have access to generic help files contained in a directory found in a system-specific location.
fs16
fs28 When a help link is being resolved, the NSHelpPanel first looks for the specified file within the appropriate i languageb i0 .lproj/Helpb0 directory of the application'27s file package. If the file isn'27t found, it then searches the directory of generic help files. This search path is used for all links, whether they are in the table of contents, index, or body text.
fs16
fs28 If one of these generic help files is inappropriate for your application, you have two remedies: You can remove the table-of-contents and index entries that refer to it, or you can override the file with one that'27s more appropriate. By placing a file of the same name and relative location within your application'27s b Helpb0 directory, NSHelpPanel will display it rather than the generic file.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Associating Help Text with Objects
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 The NSHelpPanel class stores associations between user-interface objects and help text. When the user presses the Help modifier key (which varies depending on the hardware running the application), a question mark cursor appears. If the user clicks an object using this cursor, the Help panel displays the associated help text.
fs16
fs28 You can attach a help file to a user-interface object programmatically, by sending an b attachHelpFile:markerName:to: b0 messageb b0 to the NSHelpPanel class object. This method takes a file name, a marker name, and an object b idb0 as its arguments. The b detachHelpFrom:b0 message removes such an association.
fs16
fs28 Just as with help links, an NSHelpPanel searches both the application'27s file package and the generic help files in attempting to find the file associated with a particular user-interface object.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Hidden Files
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 Although in general there'27s a one-to-one relationship between table-of-contents entries and files in the b Helpb0 directory, you can force a single table-of-contents entry to represent multiple 'aahidden'ba files. This can be useful in reducing the overall length of the table of contents.
fs16
fs28 Hidden files can'27t be accessed from the table of contents; rather, the user must find them by Help-clicking an object in the application'27s user interface, by using the Help Panel'27s Find command, by using the index, or by following a help link from some other file. However, when a hidden file is displayed, the Help panel must select some entry in the table of contents.
fs16
fs28 Conversely, when the user selects such a table-of-contents entry, the Help panel must display one of the files in the directory of hidden files; by convention, this file must be named b Prolog.rtfdb0 . The prolog file typically informs users that they can get help on a particular user-interface object by Help-clicking that object.
fs16
fs28 The Help panel'27s Find button searches through all the files that are connected to table-of-contents entries, first looking in the application'27s b Helpb0 directory and then in the generic help material. If you don'27t want some hidden file in the generic help material to appear in your application'27s Help panel as the result of a Find operation, override the file with an empty file of the same name. Since the file is empty, no search string will ever be found in it, and it will effectively block the generic file of the same name from being searched.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Searching the Help Text
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 By clicking the Help panel'27s Find button, users can search the help text for strings. NSHelpPanel uses two approaches to locate text containing a specific string. First, it attempts to find the string in the currently displayed help text by sending the object that displays the text (an instance of NSCStringText) a b findText:ignoreCase:backwards:wrap:b0 message. If the search is unsuccessful, or if the search is continued past the last occurrence of the string in the current file, the NSHelpPanel object scans for the string in other help files, both within the application'27s help files and within the generic help files. Some implementations of NSHelpPanel may make use of a previously built index of all the help text to speed this search.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Help Supplements
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 Since in OpenStep an application may load executable modules dynamically (for example, a drawing program could allow the user to load a new drawing tool), an NSHelpPanel object provides the ability to load supplemental help information. When the application loads the module, it sends the NSHelpPanel object an b addSupplement:inPath:b0 message to inform the object of the location of the new help supplement. The NSHelpPanel object appends the contents of the supplement'27s b TableOfContents.rtfb0 to the existing table of contents, so the supplement should have a title that clearly sets it off from the main part of the table of contents, for example:
fs16
fs28 pard s20 li854 fi0 ri1007 ql tx4509 tx10180 f0 b fs24 'd0Pattern Tool Supplement'd0
fs6
fs24 pard s19 li1231 fi0 ri1007 ql tx1612 tx3614 tx3992 tx4370 b0 b Pattern Options
pard s19 li1231 fi0 ri1007 ql tx1612 tx3614 tx3992 tx4370 b0 tab Brick
fi0 tab Stucco
fi0 tab Wood
fi0 tab Tile
fi0 tab Custom
fi0 b Resizing and Rotating
pard s19 li1231 fi0 ri1007 ql tx1612 tx3614 tx3992 tx4370 b0 b Blending Patterns
pard s19 li1231 fi0 ri1007 ql tx1612 tx3614 tx3992 tx4370 b0 b Index to Supplement
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 The supplement'27s index is only accessible from the table of contents; the Help panel'27s Index button displays only the main index.
fs16
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs24
fs28 Accessing the Help Panel
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSHelpPanel *)b sharedHelpPanelb0 tab Creates, if necessary, and returns the NSHelpPanel object.
fi-6552 fs16
fs28 fi-6552 + (NSHelpPanel *)b sharedHelpPanelWithDirectory:b0 (NSString *)i helpDirectoryi0 tab
s9 li7030 fi-6553 fi-5796 tab Creates, if necessary, and returns the NSHelpPanel object. If the panel is created, it loads the help directory specified by i helpDirectoryi0 . The help directory must reside in the main bundle. If a Help panel already exists but has loaded a help directory other than i helpDirectoryi0 , a second panel will be created.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Managing the Contents
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (void)b setHelpDirectoryb0 :(NSString *)i helpDirectoryi0 tab Initializes the panel to display the help text found in i helpDirectoryi0 . By default, the receiver looks for a directory named 'aaHelp'ba.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b addSupplement:b0 (NSString *)i helpDirectoryi0 tab Append additional help entries to the Help panel'27s table of
s9 li7030 fi-6553 fi-5796 b inPath:b0 (NSString *)i supplementPathi0 tab tab contents.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b helpDirectoryb0 tab Returns the absolute path of the help directory.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b helpFileb0 tab Returns the path of the currently loaded help file.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Attaching Help to Objects
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (void)b attachHelpFile:b0 (NSString *)i filenamei0 tab Associates the help file i filenamei0 and i markerNamei0 with
s9 li7030 fi-6553 fi-5796 b markerName:b0 (NSString *)i markerNamei0 tab tab i anObjecti0 .
b to:b0 (id)i anObject
s8 li7029 fi-5794 fi-6552 i0 fs16
fs28 fi-6552 + (void)b detachHelpFrom:b0 (id)i anObjecti0 tab Removes any help information associated with i anObjecti0 .
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Showing Help
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b showFile:b0 (NSString *)i filenamei0 tab Causes the panel to display the help contained in i filename
s9 li7030 fi-6553 fi-5796 i0 b atMarker:b0 (NSString *)i markerNamei0 tab tab at i markerNamei0 .
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b showHelpAttachedTo:b0 (id)i anObjecti0 tab Causes the panel to display help attached to i anObjecti0 .
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Printing
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b print:b0 (id)i senderi0 tab Prints the currently displayed help text.
}These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.