Object
This service is used to find and display context-sensitive help topics from the IDE. In the local case, HelpSvc is also used to integrate new help into the help system's table of contents and search index.
When the IDE is started, HelpSvc
constructs a
help path
consisting of locations where help topics may be found. The help path includes help
provided with IDE extensions, help provided with third-party controls and API help
such as Javadoc for the J2SE and J2EE APIs.
When F1 is pressed in the IDE, the implementation of
IHelpDriver
(if any) for the
current view is found and
IHelpDriver.getHelpContextList(IElement)
is invoked (by the shell).
IHelpDriver.getHelpContextList(IElement)
returns an ordered array of context URNs that indicate
the context for which help is being sought.
The list of context URNs is passed to
HelpSvc.I.resolveContextAsync(URI[])
,
which attempts to resolve the context URNs against the entries in the help path. If
resolution is successful, the topic is displayed in a browser via
HelpSvc.I.displayHelp(URL)
Context-Sensitive Help
Context-sensitive help is a two step process. When help is desired for the current
UI context (typically, when F1 is pressed), the IDE looks for an implementation of
IHelpDriver
on the current view. The IHelpDriver is invoked and returns an
ordered list of context URNs (URNs).
Context URNs uniquely identify the
entity for which help is desired, such as a Java class, a language keyword,
or a JSP tag from a tag library. Once the list of context URNs has been generated,
the HelpSvc attempts to resolve the context URNs against a help path - a list of
potential help topic locations.
The Help Path
HelpSvc constructs and maintains a help path, which is a list of potential locations for context-sensitive help topics.
The help path consists of the following:<extension-xml id="urn:com-bea-ide:help"> <help-root [parent="parent"] dir="directory"/> <help-root url="url-to-help-root/> </extension-xml>
directory | the directory to be searched as a help root. directory is relative to parent and/or url. |
parent | a path to a directory relative to the extension directory of
workshop. an absolute path may be used, but it is not recommended. If
ommitted, the directory is assumed to be in the extension's own directory. |
url-to-help-root | an absolute URL that specifies a new help root. this may be any url, but will typically be htpp or file based. |
A help-root
may specify both a url
and a parent
.
When the IDE help mode is "online", url
will be used. When the help mode
is "local", parent
will be used.
Context URNs
Each context URN is of one of the following forms:Some example context URNs are:
urn:java-class:com.bea.control.package-summary
urn:java-class:com.bea.control.JwsContext
urn:java-class:com.bea.control.JwsContext#finishConversation
urn:java-class:java.lang.String#substring(int, int)
urn:javadoc-tag:jws.operation
urn:taglib:www.bea.com/workshop/netui-tags-html-1.0/button
urn:keyword:java.while
IHelpDriver
generates context URNs that are appropriate
for selected items in that view. For example, a Java source editor would generate
context URNs appropriate for the current location of the text cursor. This might be
a keyword, an annotation (Javadoc tag), a variable (resolving to a class) or a method
(also resolving to a class). In the case of a Java class, the list of URNs returned
would reflect the inheritance hierarchy of the class, so that the most specific
help topic would be found first, followed by less specific topics if the most
specific topics do not exist.
Context-Sensitive Help Resolution
The HelpSvc may also be used to resolve a list of context URNs to a URL using the help path. Context URNs are described above.
When HelpSvc.I.resolveContextAsync(URI[])
is called with a list of context URNs,
the help service attempts to resolve each context URN (converted to a relative URL)
against each entry in the help path. If a resolution occurs, the complete URL to the
resolved topic (which is "help path URL" + "context URL") is sent to a browser
for display.
HelpDrivers
DocumentViews and FrameViews may have anIHelpDriver
, which will generate
context URNs for the current context when
context-sensitive (F1) help is requested in that view.
Displaying Help
The HelpSvc provides three mechanisms for displaying help:HelpSvc
with the path to a specific help file,
relative to a help path entry. The help service will attempt to resolve the path against
the entries in the help path.HelpSvc
with an array of context URN URIs. The help service
will attempt to resolve each of the context URNs against each of the help path entries, in
order.HelpSvc
with a URL.$locale
in help path entries.
A locale is a 2-letter ISO language code optionally followed by a 2-letter country/region code. The following are examples of locales:
en
ja
ja_JP
zh_CN
$locale
placeholder with the following values, in order:
workshop.help.locale
en
Locale.getDefault()
.
Related Topics
Object
HelpSvc
Nested Class Summary |
public static interface | HelpSvc.I
The interface that must be implemented by a help service provider. |
Field Summary |
protected static |
|
Constructor Summary |
|
Method Summary |
public static |
|
Methods from class java.lang. |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
protected static HelpSvc.I
instance
Constructor Detail |
public HelpSvc()
Method Detail |
public static HelpSvc.I
get()
get the single instance of this service.