Context-sensitive help

Help content

Help content for the JOSM help system is maintained on the JOSM wiki.

Structure of the help content

The content is structured into language specific content trees.

• there is a default content tree under /Help. Content in this tree is maintained in english.
• for each supported language there is a language specific tree unter /Xyz:Help where Xyz is the ISO language code in title case. Examples:
  • /De:Help - help in German
  • /Zh_CN:Help - help in simplified variant of Chinese

Help topics

Help topics are "addresses" of individual help pages in the JOSM help content. There are two kinds of help topics:

• absolute help topics - absolute help topics consist of a pointer to help content including the language specific root. Examples:
  • /Help/Action/Download - help topic for the help content about the download action, in English
  • /Fr:Help/Dialog/LayerList - help topic for the help content about the layer dialog, in French

• relative help topics - relative help topics consist of a pointer to help content not including the language specific root. They are language independent references to help content. Examples:
  • /Action/Download - help topic for the help content about the download action
  • /Dialog/LayerList - help topic for the help content about the layer dialog

Optionally, help topics can include a fragment after a #. Example: /ErrorMessages#BadRequest. The fragment refers to a named section in the help content and the help content should either include a HTML element with an id or a name whose value is equal to the fragment. There are three approaches for creating these HTML elements:

1. declare the id of a wiki heading, i.e.

   == Error message for bad request == #BadRequest
   

2. create a <span> with an id, i.e.

   [=#BadRequest In case of a bad request file…]
   

3. include an HTML anchor, i.e.

   {{{
   #!html
   <a name="BadRequest"/>
   }}}
   

Translating help content

You're encouraged to translate help content into your language. You may start with this list of expected help pages and either translate already existing pages or fill in new pages with content in other languages.

Do not translate the relative help topics, though. The names of relative help topics, including the optional fragments after a # have to be the same in all languages. The German help page for /Help/Action/Upload should be /De:Help/Action/Upload, not /Help/Aktion/Hochladen or even /Hilfe/Aktion/Hochladen.

Help content within help pages

You will notice that JOSMs help browser doesn't display the complete help page available on the wiki. JOSM extracts the core help content from wiki pages and slightly transforms it such that its internal browser can render it.

Enabling context-sensitive help

Declaring help topics

If you enable context-sensitive help for an UI widget or add a help button to the UI the help context is declared with a relative help topic.

Always use the marker method ht("...")​ to declare a help topic. ht just replies the relative help topic. It's purpose is only to make explicit which string constants are used as help topics. There are scripts which harvest them from the JOSM source and create a cross-references.

Adding a help button to an UI widget

You can easily add a help button to a GUI element. The easiest way is to reuse ContextSensitiveHelpAction:

  import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
  import org.openstreetmap.josm.gui.help.ContextSensitiveHelpAction;

  // Example: add a help button to a panel. If a user clicks on the button
  // he will be redirected to the help topic /Action/MyAction, whenever
  // possible in the language he's using JOSM 
  // 
  JPanel pnl = new JPanel(new FlowLayout());
  pnl.add(new JButton(new ContextSensitiveHelpAction(ht("/Action/MyAction"));

Enabling context-sensitive help with F1

You can easily activate F1 to trigger context sensitive help for any JComponent. Here's an example for a JPanel:

import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
import static org.openstreetmap.josm.gui.help.HelpUtil.setHelpContext;

// Example: enables F1 on a panel. The user is directed to the help topic
// /Dialog/MyDialog.
// 
JPanel pnl = new JPanel(new FlowLayout());
setHelpContext(pnl, ht("/Dialog/MyDialog"));

If you wan't to activate context-sensitive help for a JDialog or a JFrame, configure it for the root pane:

import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
import static org.openstreetmap.josm.gui.help.HelpUtil.setHelpContext;

// Example: enables F1 on a panel. The user is directed to the help topic
// /Dialog/MyDialog.
// 
JFrame frame = new JFrame("My sample frame");
setHelpContext(frame.getRootPane(), ht("/Dialog/MyDialog"));

At run-time, JOSM walks up the ui component tree and redirects the user to the first, i.e. the most specific help topic it finds along this way.

Context-sensitive help for an action

You can easily configure context-sensitive help for an action. If you later add the action to a button or a menu item, both the button or the menu item will redirect the user to the declared help topic if he presses F1.

import static org.openstreetmap.josm.gui.help.HelpUtil.ht;

// Example: a custom action with a declared help topic 
// 
class MyAction extends AbstractAction {
   public MyAction() {
      putValue("help", ht("/Action/MyAction"));  // configure help topic for the action 
   }

   public void actionPerformed(ActionEvent evt) {
     // tbd
   }
}

// btn will respond to F1. Help topic is /Action/MyAction 
//
JButton btn = nwe JButton(new MyAction());

Context-sensitive help for the ExtendedDialog

ExtendedDialog​ is an UI class used throughout the JOSM code base to implement simple modal dialogs. You can enable context-sensitive help for an ExtendedDialog, too.

import static org.openstreetmap.josm.gui.help.HelpUtil.ht;

// Example: enables F1 on an extended dialog and displays a help button in
// the button row at the bottom of the dialog. 
// The help topic is /Dialog/MyMergeDialog
// 
ExtendedDialog dialog = new ExtendedDialog(
    Main.parent,
    tr("Select target layer"),
    new String[] { tr("Merge"), tr("Cancel")}
);
dialog.setButtonIcons(new String[] { "dialogs/mergedown", "cancel" });
dialog.setContent(tr("Please select the target layer."));
dialog.configureContextSensitiveHelp(ht("/Dialog/MyMergeDialog"), true /* display a help button */));
dialog.showDialog();

Context-sensitive help in message dialogs

The utiliy class HelpAwareOptionPane provides static utility methods for displaying message dialogs with enabled context-sensitive help.

The simplest case is to display a message dialog with an ok button and a help button:

import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
import static org.openstreetmap.josm.gui.HelpAwareOptionPane;

// Example: shows a message dialog with an OK button and a help button.
// The help topic is /ErrorMessages#AnErrorMessage. The user is redirected
// to the help content when he either clicks on the help button or presses
// F1 when the mouse is over the message dialog. 
// 
// Note that the dialog isn't closed if the user clicks on the help button.
//
HelpAwareOptionPane.showOptionDialog(
    Main.parent,
    tr("This text explains the error situation"),
    tr("Error"),
    JOptionPane.ERROR_MESSAGE,
    ht("/ErrorMessages#AnErrorMessage")
);

In a more complex example the option pane can be configured with arbitrary buttons. You can specify the text, an icon, and the tooltip text of every button. If necessary, you can also declare a context-sensitive help topic for every button but in most cases one help topic for the whole option dialog will be precise enough.

import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
import static org.openstreetmap.josm.gui.HelpAwareOptionPane;

// two buttons to be displayed in the option pane. In addition, a help button is displayed.
// You don't have to specify it here.
//
ButtonSpec [] options = new ButtonSpec[] {
    new ButtonSpec(
        tr("Yes, create a conflict and close"),
        ImageProvider.get("ok"),
        tr("Click to create a conflict and close this relation editor") ,
        null /* no specific help topic */
    ),
    new ButtonSpec(
         tr("No, continue editing"),
         ImageProvider.get("cancel"),
         tr("Click to to return to the relation editor and to resume relation editing") ,
         null /* no specific help topic */
    )
};

int ret = HelpAwareOptionPane.showOptionDialog(
          Main.parent,
          tr("This text explains the error situation"),
          tr("Conflict in data"),
          JOptionPane.WARNING_MESSAGE,
          null, /* no specific icon */
          options,
          options[0], // OK is default
          ht("/Dialog/RelationEditor#RelationChangedOutsideOfEditor") // the help topic 
);
return ret == 0;