Context-sensitive help

Help content

Content for the JOSM help system is maintained on the JOSM wiki. Most of the pages are context specific Help topics, see List of Help topics. Additional pages inform on specific issues, like Rules or Styles.

Structure of the help content trees

The content is structured into language specific content trees.

• The default content tree is under /Help. Content in this tree is maintained in English.
• For each supported language 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 Chinese

Help topics

Help topics are "addresses" of individual pages in the JOSM help content. Three ways exist to address a help topic:

• relative - relative addressing points to content not including the language specific root. This is used in JOSM code as language independent references to wiki content. If that language specific wiki page does not exist, then JOSM calls the English page.
  Example: /Action/Download - topic for the download action

• absolute - absolute addressing consist of a pointer including the language specific root. This should only be used when the reference needs to be language specific.
  Example: /Fr:Help/Action/Download - topic for the download action in French

• translated - translated addressing is used inside the wiki. Links point always to the default content using the [wikitr:/Help/Action/Download] macro. If translated content is available, Trac rewrites the target URL to it. This addressing is recommend for the Wiki. It is possible since March 2018.

Optionally, help topics can include a fragment after a #. Example: /ErrorMessages#BadRequest. The fragment refers to a named section in the content. So the page should either include a HTML element with an id or a name equal to the fragment. Three approaches for creating these HTML anchors are possible:

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] a bug or try a tea…
   

3. include an HTML anchor, i.e.

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

Anchors are case sensitive and not translatable. They shall be in CamelCaseAfterSpace format but must obey the source code.

Translating help content

You're encouraged to translate help content into your language.

Do not translate the relative help topics, though. Their names have to be the same in all languages. The help page for /Help/Action/Upload in German should be /De:Help/Action/Upload and not /Help/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 want 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;