Changes between Initial Version and Version 1 of DevelopersGuide/HelpSystem


Ignore:
Timestamp:
2009-11-08T16:46:24+01:00 (16 years ago)
Author:
Gubaer
Comment:

created

Legend:

Unmodified
Added
Removed
Modified
  • DevelopersGuide/HelpSystem

    v1 v1  
     1= Context-sensitive help =
     2
     3== Help content ==
     4Help content for the JOSM help system is maintained on the [wiki:/Help JOSM wiki].
     5
     6=== Structure of the help content ===
     7The content is structured into language specific content trees.
     8 * there is a '''default content tree''' under [wiki:/Help /Help]. Content in this tree is maintained in english.
     9 * for each supported language there is a '''language specific tree''' unter {{{/Xy:Help}}} where {{{Xy}}} is the ISO language code in title case. Examples:
     10   * [wiki:/De:Help /De:Help] - help in german
     11   * [wiki:/Fr:Help /Fr:Help] - help in french
     12
     13=== Help topics ===
     14Help topics are "addresses" of individual help pages in the JOSM help content. There are two kinds of help topics:
     15  * '''absolute help topics''' - absolute help topics consist of a pointer to help content '''including''' the language specific root. Examples:
     16    * [wiki:/Help/Action/Download /Help/Action/Download] - help topic for the help content about the download action, in english
     17    * [wiki:/Fr:Help/Dialog/LayerDialog /Fr:Help/Dialog/LayerDialog] - help topic for the help content about the layer dialog, in french
     18
     19  * '''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:
     20    * {{{/Action/Download}}} - help topic for the help content about the download action
     21    * {{{/Dialog/LayerDialog}}} - help topic for the help content about the layer dialog
     22
     23== Enabling context-sensitive help ==
     24=== Declaring help topics ===
     25If 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'''.
     26
     27Always 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 these help topics from the JOSM source and create a [wiki:/DevelopersGuide/HelpSystem/HelpTopicsList cross-references].
     28
     29=== Adding a help button to an UI ===
     30You 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 ContextSensitiveHelpAction]:
     31{{{
     32#!java
     33  import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
     34  import org.openstreetmap.josm.gui.help.ContextSensitiveHelpAction;
     35
     36  // Example: add a help button to a panel. If a user clicks on the button
     37  // he will be redirected to the help topic /Action/MyAction, whenever
     38  // possible in the language he's using JOSM
     39  //
     40  JPanel pnl = new JPanel(new FlowLayout());
     41  pnl.add(new JButton(new ContextSensitiveHelpAction(ht("/Action/MyAction"));
     42}}}
     43
     44=== Enabling context-sensitive help with F1 ===
     45You can easily activate F1 to trigger context sensitive help for any JComponent. Here's an example for a JPanel:
     46{{{
     47#!java
     48import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
     49import static org.openstreetmap.josm.gui.help.HelpUtil.setHelpContext;
     50
     51// Example: enables F1 on a panel. The user is directed to the help topic
     52// /Dialog/MyDialog.
     53//
     54JPanel pnl = new JPanel(new FlowLayout());
     55setHelpContext(pnl, ht("/Dialog/MyDialog"));
     56}}}
     57
     58If you wan't to activate context-sensitive help for a JDialog or a JFrame, configure it for the root pane:
     59
     60{{{
     61#!java
     62import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
     63import static org.openstreetmap.josm.gui.help.HelpUtil.setHelpContext;
     64
     65// Example: enables F1 on a panel. The user is directed to the help topic
     66// /Dialog/MyDialog.
     67//
     68JFrame frame = new JFrame("My sample frame");
     69setHelpContext(frame.getRootPane(), ht("/Dialog/MyDialog"));
     70}}}
     71
     72At 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.
     73
     74=== Context-sensitive help for the ExtendedDialog ===
     75[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.
     76
     77{{{
     78#!java
     79import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
     80
     81// Example: enables F1 on an extended dialog and displays a help button in
     82// the button row at the bottom of the dialog.
     83// The help topic is /Dialog/MyMergeDialog
     84//
     85ExtendedDialog dialog = new ExtendedDialog(
     86    Main.parent,
     87    tr("Select target layer"),
     88    new String[] { tr("Merge"), tr("Cancel")}
     89);
     90dialog.setButtonIcons(new String[] { "dialogs/mergedown", "cancel" });
     91dialog.setContent(tr("Please select the target layer."));
     92dialog.configureContextSensitiveHelp(ht("/Dialog/MyMergeDialog"), true /* display a help button */));
     93dialog.showDialog();
     94}}}
     95
     96=== Context-sensitive help in message dialogs ===
     97The utiliy class [source:/trunk/src/org/openstreetmap/org/josm/gui/HelpAwareOptionPane.java HelpAwareOptionPane] provides static utility methods for displaying message dialogs with enabled context-sensitive help.
     98
     99The simplest case is to display a message dialog with an ok button and a help button:
     100
     101{{{
     102#!java
     103import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
     104import static org.openstreetmap.josm.gui.HelpAwareOptionPane;
     105
     106// Example: shows a message dialog with an OK button and a help button.
     107// The help topic is /ErrorMessages#AnErrorMessage. The user is redirected
     108// to the help content when he either clicks on the help button or presses
     109// F1 when the mouse is over the message dialog.
     110//
     111// Note that the dialog isn't closed if the user clicks on the help button.
     112//
     113HelpAwareOptionPane.showOptionDialog(
     114    Main.parent,
     115    tr("This text explains the error situation"),
     116    tr("Error"),
     117    JOptionPane.ERROR_MESSAGE,
     118    ht("/ErrorMessages#AnErrorMessage")
     119);
     120}}}
     121
     122In 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.
     123
     124{{{
     125#!java
     126import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
     127import static org.openstreetmap.josm.gui.HelpAwareOptionPane;
     128
     129// two buttons to be displayed in the option pane. In addition, a help button is displayed.
     130// You don't have to specify it here.
     131//
     132ButtonSpec [] options = new ButtonSpec[] {
     133    new ButtonSpec(
     134        tr("Yes, create a conflict and close"),
     135        ImageProvider.get("ok"),
     136        tr("Click to create a conflict and close this relation editor") ,
     137        null /* no specific help topic */
     138    ),
     139    new ButtonSpec(
     140         tr("No, continue editing"),
     141         ImageProvider.get("cancel"),
     142         tr("Click to to return to the relation editor and to resume relation editing") ,
     143         null /* no specific help topic */
     144    )
     145};
     146
     147int ret = HelpAwareOptionPane.showOptionDialog(
     148          Main.parent,
     149          tr("This text explains the error situation"),
     150          tr("Conflict in data"),
     151          JOptionPane.WARNING_MESSAGE,
     152          null, /* no specific icon */
     153          options,
     154          options[0], // OK is default
     155          ht("/Dialog/RelationEditor#RelationChangedOutsideOfEditor") // the help topic
     156);
     157return ret == 0;
     158}}}