Context Navigation

Editing DevelopersGuide/HelpSystem

Adjust edit area height: Edit side-by-side

[[PageOutline]]
= Context-sensitive help =

== Help content ==
Content for the JOSM help system is maintained on the [wikitr:/Help JOSM wiki]. 
Most of the pages are context specific Help topics, see [wiki:/DevelopersGuide/HelpSystem/HelpTopicsList List of Help topics]. 
Additional pages inform on specific issues, like [wikitr:/Rules] or [wikitr:/Styles].

=== Structure of the help content trees ===
The content is structured into language specific content trees. 
 * The '''default content tree''' is under [wiki:/Help /Help]. Content in this tree is maintained in English.
 * For each supported language a '''language specific tree''' unter {{{/Xyz:Help}}} where {{{Xyz}}} is the [wikitr:/Translations/Wiki#Languagecodes ISO language code] in title case. Examples:
   * [wiki:/De:Help /De:Help] - help in German 
   * [wiki:/Zh_CN:Help /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. [[BR]] 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. [[BR]] 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 [/ticket/16101 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 [wikitr:/Translations 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 [source:/trunk/src/org/openstreetmap/josm/gui/help/HelpUtil.java 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 [wiki:/DevelopersGuide/HelpSystem/HelpTopicsList 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 [source:/trunk/src/org/openstreetmap/josm/gui/help/ContextSensitiveHelpAction.java ContextSensitiveHelpAction]:
{{{
#!java
  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:
{{{
#!java
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:

{{{
#!java
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.

{{{
#!java
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 ===
[source:/trunk/src/org/openstreetmap/josm/gui/ExtendedDialog.java 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.

{{{
#!java
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 [source:/trunk/src/org/openstreetmap/josm/gui/HelpAwareOptionPane.java 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:

{{{
#!java
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.

{{{
#!java
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;
}}}

Note: See WikiFormatting and TracWiki for help on editing wiki content.

Change information

Your email or username:

E-mail address and name can be saved in the Preferences

Comment about this change (optional):

Note: See TracWiki for help on using the wiki.