All Downloads are FREE. Search and download functionalities are using the official Maven repository.
  • Log In
  • Register

    • org.netbeans.api.javahelp.doc-files.api.html Maven / Gradle / Ivy

    There is a newer version: RELEASE240
    Show newest version
    



NetBeans JavaHelp Integration API





    Overview
    


    NetBeans JavaHelp Integration API
    


    It is possible to add JavaHelp and context help capabilities to modules.
This API module makes that possible. It also includes the JavaHelp standard
extension library itself.
    


    JavaHelp installation
    


    Helpset registration
    


    You can add JavaHelp via your XML layer. First you
need to add the helpset to the IDE. This has several effects: it ensures that
context help can use your helpset; it enabled help links to use help IDs
defined in this helpset; and assuming the helpset is marked to be merged into
the master helpset, this means that the menu item Help | Contents
will show any navigators you define in your helpset, merged into others.


    To add a helpset, you must register an object implementing javax.swing.HelpSet
into the IDE's lookup system. The normal way to do this is to use @HelpSetRegistration.


    By default such a helpset will be merged into the IDE's master help
navigators. You may opt out of this by specifying
merge="false". If
providing a custom help set instance via lookup, in order to turn off
merging you should set the "key data" on the helpset with the context
OpenIDE and key mergeIntoMaster to
Boolean.FALSE.


    Using nbresloc implies that the
helpset can be found in the module's classloader, for example in its
main JAR or in an extension ZIP or JAR referenced via the
Class-Path manifest attribute. There is a URL protocol
nbdocs which is similar to nbresloc and will load anything it can.
It also will try to load localized resources using
InstalledFileLocator
with a prefix of docs/.
Given the current implementation of the
NetBeans installation structure, this will permit the help set and
associated files to reside in a package hierarchy underneath the
docs/ folder (of the IDE installation or user directory),
if not in the module classloader.
    


    Shortcut registration
    


    To add a shortcut to a specific help ID in your help set, there is an
XML DTD you can use.
The shortcut XML specifies the help ID to display (which must be present in some
registered help set of course), for example:


    <?xml?>
<!DOCTYPE helpctx PUBLIC
          "-//NetBeans//DTD Help Context 1.0//EN"
          "http://www.netbeans.org/dtds/helpcontext-1_0.dtd">
<helpctx id="org.netbeans.modules.foo.some-topic"/>

    


    By default such a link will display a help window containing
navigators only for the help set from which it was taken. If you
prefer to display navigators for all merged help sets, specify
showmaster="true" on the <helpctx/>.


    This XML file's only use is that it has a menu/toolbar presenter
which opens the specified help page. (You can customize its display
name and icon using the normal means available to templates etc.)
You could provide an alternate means of displaying help shortcuts,
however the functionality of showing the master navigators is only
accessible via the presenters of this kind of XML file.


    Note that usage of help shortcuts is no longer recommended by NetBeans style
guidelines.
    


    Context Help
    


    When the help set is specified in the module, this permits the
IDE to associate context help with various features associated with
the module (or, technically, other modules - if you know their help
IDs and they do not themselves bind them). There are several ways
to associate help IDs with module features so that they may be used
by the IDE, mostly revolving around the API class

HelpCtx.


    This class has should be constructed with a help ID,
which should be a string constant uniquely identifying the feature, and
associated with an HTML page using the map file.
    


    


    For example, an action might include a method
implementation such as:


    public HelpCtx getHelpCtx() {
    return new HelpCtx("my.action");
}

    

Now the map file should include a line such as:


    <mapID target="my.action" url="this-action.html"/>

    


    


    There are a number of different points in the APIs where you may
specify a HelpCtx in this fashion:


    


    There are some other points where you may specify a help ID directly:
    


      


    •  On any (Swing lightweight) component you use in a GUI, by
means of

HelpCtx.setHelpIDString(...).

This is especially useful for custom property editor components.


    •  On any JavaBean, by adding the help ID as a (string) value to
the (FeatureDescriptor) attribute named
helpID in a BeanDescriptor, as described
by the JavaHelp specification in regards to beans. This will be
interpreted by any bean container (e.g.

InstanceDataObject

or

BeanNode

or *.ser files)

that uses

InstanceSupport.findHelp(...).


      This technique may also be used to add context help support to
the editor kits used in the

Editor API;

create the bean info for the subclass of

EditorKit,

and this help will be used for the editor pane.


      As of NetBeans 3.4, you may also use the attributes
propertiesHelpID and expertHelpID
on the BeanDescriptor in order to specifically supply
help for regular (resp. expert) property sets only. To provide
a specific help for just one property, use helpID on
the PropertyDescriptor.


    •  As the helpID

value

of a

Node.PropertySet

or

Node.Property.


    •  For services on the system filesystem (typically installed via layer) and the folders
they are in (typically beneath Services/), you may 
use the file attribute helpID
to specify the help ID right in the layer. See the
Services API for details.


    •  In the <homeID> tag of a help set file; in
this case, the specified help ID is understood as applying
generally to the module. Typically it should be some sort of index
page.


    •  In various navigational views used by JavaHelp, such as the table
of contents or the index.


    


    The proper help page for the selected component, if there is
one, is displayed by the IDE by default using F1.
This applies to various visual components (when they have focus),
the current TopComponent, and nodes (or the objects
they represent) when the node is selected in an Explorer window (or
custom windows using 
ExplorerUtils).

Programmatically, you may also display help by using
the

JavaHelp module API:
    


    String id = ...;
Help help = Lookup.getDefault().lookup(Help.class);
if (help != null && help.isValidID(id, true)) {
    help.showHelp(new HelpCtx(id));
} else {
    Toolkit.getDefaultToolkit().beep();
}

    


    However for most purposes you can use the simpler
HelpCtx.display
method and avoid a direct dependency on this API entirely:
    


    String id = ...;
if (id != null && !new HelpCtx(id).display()) {
    Toolkit.getDefaultToolkit().beep();
}

    


    If you are having trouble figuring out why you
are not seeing the help you expect, try running the IDE with the
command-line option -J-Dorg.netbeans.modules.javahelp=0
and look in your log file for details.
-J-Dorg.openide.util.HelpCtx=0 may also be used to get
further information on association between help IDs and GUI
components, and so on.
    


    External links in JavaHelp
    

    
Most of external links are not displayed correctly in internal java help viewer.
This lightweight component was added to invoke default IDE HTML browser
(it should be external browser). This component can be included in HTML content
within JHContentViewer. Component is displayed as a mouse enabled Label.
Only text is supported.

    
To use this class within HTML content use the <object> tag. Below is an
example usage:

    <object CLASSID="java:org.netbeans.module.javahelp.BrowserDisplayer">
    <param name="content" value="http://www.netbeans.org">
    <param name="text" value="Click here">
    <param name="textFontFamily" value="SansSerif">
    <param name="textFontSize" value="x-large">
    <param name="textFontWeight" value="plain">
    <param name="textFontStyle" value="italic">
    <param name="textColor" value="red">
</object>

    
or to get hyperlink style use:

    <object CLASSID="java:org.netbeans.modules.javahelp.BrowserDisplayer">
    <param name="content" value="http://java.sun.com/downloads/ea/index.html">
    <param name="text" value="<html><u>Early Access</u></html>">
    <param name="textFontSize" value="medium">
    <param name="textColor" value="blue">
</object>

    
HTML is used to get underlined text and value of text parameter must be properly escaped.


    
Valid parameters are:

      

    • content - a valid external url like http://java.sun.com

    • text - the text of the activator.

    • textFontFamily - the font family of the activator text.

    • textFontSize - the size of the activator text font. Size is specified
in a css termonolgy. Acceptable values are as follows:
      
        
      
      • xx-small
      
      • x-small
      
      • small
      
      • medium
      
      • large
      
      • x-large
      
      • xx-large
      
      • bigger - increase the current base font size by 1
      
      • smaller - decrease the current base font size by 1
      
      • xxpt - set the font size to a specific pt value of "xx"
      
      • +x - increase the current base font size by a value of "x"
      
      • -x - decrease the current base font size by a value of "x"
      
      • x - set the font size to the point size associated with the index "x"
      
      

    • textFontWeight - the activator text font weight. Valid weights are
      
        
      
      • plain
      
      • bold
      
      

    • textFontStyle - the activator text font style. Valid font styles are
      
        
      
      • plain
      
      • italic
      
      

    • textColor - the activator text color. The following is a list of supported Color names
      
        
      
      • black
      
      • blue
      
      • cyan
      
      • darkGray
      
      • gray
      
      • green
      
      • lightGray
      
      • magenta
      
      • orange
      
      • pink
      
      • red
      
      • white
      
      • yellow
      
      

    


    


    Extension of nbdocs protocol
    

    
As documentation is modular ie. it is defined across modules it is possible to define
link in documentation from one module to another module. When referred module is not
present or is not enabled such link becomes invalid. We extended nbdocs protocol to handle
such case by frendlier way. Now it is possible to place at URL host name position base name
of referred module. Instead of

    nbdocs:/org/nb/mod/foo/docs/somepage.html

    
it is possible (and in fact recommended) to use:

    nbdocs://org.nb.mod.bar/org/nb/mod/foo/docs/somepage.html

    
where org.nb.mod.bar is module base name. Referred module is checked if it is present
and enabled in IDE. If yes link is handled as usual. If not informational page is created and displayed.
Page template is located at core/javahelp/src/org/netbeans/modules/javahelp/resources as 
notEnabledModule.html
and notInstalledModule.html so they can be localized.

    

Example: In Users Guide module there is link to HTTP Monitor module:

    <a href="nbdocs:/org/netbeans/modules/web/monitor/docs/monitor/ctx_monitorintro.html">
Monitoring Data Flow on the Web Server</a>

    
After adding module base name it will be:

    <a href="nbdocs://org.netbeans.modules.web.monitor/org/netbeans/modules/web/monitor/docs/monitor/ctx_monitorintro.html">
Monitoring Data Flow on the Web Server</a>

    


    


    

    @FOOTER@




    © 2015 - 2025 Weber Informatics LLC | Privacy Policy