Changes between Initial Version and Version 1 of DevelopersGuide/HelpSystem

Timestamp:

2009-11-08T16:46:24+01:00 (16 years ago)

Author:

Gubaer

Comment:

created

DevelopersGuide/HelpSystem

@@ +1 @@
+= Context-sensitive help =
+
+== Help content ==
+Help content for the JOSM help system is maintained on the [wiki:/Help JOSM wiki]. 
+
+=== Structure of the help content ===
+The content is structured into language specific content trees. 
+ * there is a '''default content tree''' under [wiki:/Help /Help]. Content in this tree is maintained in english.
+ * for each supported language there is a '''language specific tree''' unter {{{/Xy:Help}}} where {{{Xy}}} is the ISO language code in title case. Examples:
+   * [wiki:/De:Help /De:Help] - help in german 
+   * [wiki:/Fr:Help /Fr:Help] - help in french
+
+=== 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:
+    * [wiki:/Help/Action/Download /Help/Action/Download] - help topic for the help content about the download action, in english
+    * [wiki:/Fr:Help/Dialog/LayerDialog /Fr:Help/Dialog/LayerDialog] - 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/LayerDialog}}} - help topic for the help content about the layer dialog
+
+== 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 these help topics from the JOSM source and create a [wiki:/DevelopersGuide/HelpSystem/HelpTopicsList cross-references].
+
+=== Adding a help button to an UI ===
+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 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 wan't 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 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/org/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;
+}}}